feat: update MCP tools to structured output format with SDK v1.15.0

package.json

@@ -74,7 +74,7 @@
   "type": "module",
   "dependencies": {
     "@clack/prompts": "^0.10.1",
-    "@modelcontextprotocol/sdk": "^1.11.0",
+    "@modelcontextprotocol/sdk": "^1.15.0",
     "@secretlint/core": "^9.3.1",
     "@secretlint/secretlint-rule-preset-recommend": "^9.3.1",
     "clipboardy": "^4.0.0",

src/mcp/mcpServer.ts

@@ -10,11 +10,26 @@ import { registerPackCodebaseTool } from './tools/packCodebaseTool.js';
 import { registerPackRemoteRepositoryTool } from './tools/packRemoteRepositoryTool.js';
 import { registerReadRepomixOutputTool } from './tools/readRepomixOutputTool.js';
 
+/**
+ * Instructions for the Repomix MCP Server that describe its capabilities and usage
+ */
+const MCP_SERVER_INSTRUCTIONS =
+  'Repomix MCP Server provides AI-optimized codebase analysis tools. ' +
+  'Use pack_codebase or pack_remote_repository to consolidate code into a single XML file, ' +
+  'then read_repomix_output and grep_repomix_output to analyze it. ' +
+  'Perfect for code reviews, documentation generation, bug investigation, GitHub repository analysis, and understanding large codebases. ' +
+  'Includes security scanning and supports compression for token efficiency.';
+
 export const createMcpServer = async () => {
-  const mcpServer = new McpServer({
-    name: 'repomix-mcp-server',
-    version: await getVersion(),
-  });
+  const mcpServer = new McpServer(
+    {
+      name: 'repomix-mcp-server',
+      version: await getVersion(),
+    },
+    {
+      instructions: MCP_SERVER_INSTRUCTIONS,
+    },
+  );
 
   // Register the prompts
   registerPackRemoteRepositoryPrompt(mcpServer);

src/mcp/tools/fileSystemReadDirectoryTool.ts

@@ -6,56 +6,82 @@
 import { logger } from '../../shared/logger.js';
 import { buildMcpToolErrorResponse, buildMcpToolSuccessResponse } from './mcpToolRuntime.js';
 
+const fileSystemReadDirectoryInputSchema = z.object({
+  path: z.string().describe('Absolute path to the directory to list'),
+});
+
+const fileSystemReadDirectoryOutputSchema = z.object({
+  path: z.string().describe('The directory path that was listed'),
+  contents: z.array(z.string()).describe('Array of directory contents with [FILE]/[DIR] indicators'),
+  totalItems: z.number().describe('Total number of items in the directory'),
+  fileCount: z.number().describe('Number of files in the directory'),
+  directoryCount: z.number().describe('Number of subdirectories in the directory'),
+});
+
 /**
  * Register file system directory listing tool
  */
 export const registerFileSystemReadDirectoryTool = (mcpServer: McpServer) => {
-  mcpServer.tool(
+  mcpServer.registerTool(
     'file_system_read_directory',
-    'List the contents of a directory using an absolute path. Returns a formatted list showing files and subdirectories with clear [FILE]/[DIR] indicators. Useful for exploring project structure and understanding codebase organization.',
-    {
-      path: z.string().describe('Absolute path to the directory to list'),
-    },
     {
       title: 'Read Directory',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
+      description:
+        'List the contents of a directory using an absolute path. Returns a formatted list showing files and subdirectories with clear [FILE]/[DIR] indicators. Useful for exploring project structure and understanding codebase organization.',
+      inputSchema: fileSystemReadDirectoryInputSchema.shape,
+      outputSchema: fileSystemReadDirectoryOutputSchema.shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
     },
     async ({ path: directoryPath }): Promise<CallToolResult> => {
       try {
         logger.trace(`Listing directory at absolute path: ${directoryPath}`);
 
         // Ensure path is absolute
         if (!path.isAbsolute(directoryPath)) {
-          return buildMcpToolErrorResponse([`Error: Path must be absolute. Received: ${directoryPath}`]);
+          return buildMcpToolErrorResponse({
+            errorMessage: `Error: Path must be absolute. Received: ${directoryPath}`,
+          });
         }
 
         // Check if directory exists
         try {
           const stats = await fs.stat(directoryPath);
           if (!stats.isDirectory()) {
-            return buildMcpToolErrorResponse([
-              `Error: The specified path is not a directory: ${directoryPath}. Use file_system_read_file for files.`,
-            ]);
+            return buildMcpToolErrorResponse({
+              errorMessage: `Error: The specified path is not a directory: ${directoryPath}. Use file_system_read_file for files.`,
+            });
           }
         } catch {
-          return buildMcpToolErrorResponse([`Error: Directory not found at path: ${directoryPath}`]);
+          return buildMcpToolErrorResponse({
+            errorMessage: `Error: Directory not found at path: ${directoryPath}`,
+          });
         }
 
         // Read directory contents
         const entries = await fs.readdir(directoryPath, { withFileTypes: true });
-        const formatted = entries
-          .map((entry) => `${entry.isDirectory() ? '[DIR]' : '[FILE]'} ${entry.name}`)
-          .join('\n');
+        const contents = entries.map((entry) => `${entry.isDirectory() ? '[DIR]' : '[FILE]'} ${entry.name}`);
+
+        const fileCount = entries.filter((entry) => entry.isFile()).length;
+        const directoryCount = entries.filter((entry) => entry.isDirectory()).length;
+        const totalItems = entries.length;
 
-        return buildMcpToolSuccessResponse([`Contents of ${directoryPath}:`, formatted || '(empty directory)']);
+        return buildMcpToolSuccessResponse({
+          path: directoryPath,
+          contents: contents.length > 0 ? contents : ['(empty directory)'],
+          totalItems,
+          fileCount,
+          directoryCount,
+        } satisfies z.infer<typeof fileSystemReadDirectoryOutputSchema>);
       } catch (error) {
         logger.error(`Error in file_system_read_directory tool: ${error}`);
-        return buildMcpToolErrorResponse([
-          `Error listing directory: ${error instanceof Error ? error.message : String(error)}`,
-        ]);
+        return buildMcpToolErrorResponse({
+          errorMessage: `Error listing directory: ${error instanceof Error ? error.message : String(error)}`,
+        });
       }
     },
   );

src/mcp/tools/fileSystemReadFileTool.ts

@@ -8,47 +8,68 @@
 import { logger } from '../../shared/logger.js';
 import { buildMcpToolErrorResponse, buildMcpToolSuccessResponse } from './mcpToolRuntime.js';
 
+const fileSystemReadFileInputSchema = z.object({
+  path: z.string().describe('Absolute path to the file to read'),
+});
+
+const fileSystemReadFileOutputSchema = z.object({
+  path: z.string().describe('The file path that was read'),
+  content: z.string().describe('The file content'),
+  size: z.number().describe('File size in bytes'),
+  encoding: z.string().describe('Text encoding used to read the file'),
+  lines: z.number().describe('Number of lines in the file'),
+});
+
 /**
  * Register file system read file tool with security checks
  */
 export const registerFileSystemReadFileTool = (mcpServer: McpServer) => {
-  mcpServer.tool(
+  mcpServer.registerTool(
     'file_system_read_file',
-    'Read a file from the local file system using an absolute path. Includes built-in security validation to detect and prevent access to files containing sensitive information (API keys, passwords, secrets).',
-    {
-      path: z.string().describe('Absolute path to the file to read'),
-    },
     {
       title: 'Read File',
-      readOnlyHint: true,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
+      description:
+        'Read a file from the local file system using an absolute path. Includes built-in security validation to detect and prevent access to files containing sensitive information (API keys, passwords, secrets).',
+      inputSchema: fileSystemReadFileInputSchema.shape,
+      outputSchema: fileSystemReadFileOutputSchema.shape,
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
     },
     async ({ path: filePath }): Promise<CallToolResult> => {
       try {
         logger.trace(`Reading file at absolute path: ${filePath}`);
 
         // Ensure path is absolute
         if (!path.isAbsolute(filePath)) {
-          return buildMcpToolErrorResponse([`Error: Path must be absolute. Received: ${filePath}`]);
+          return buildMcpToolErrorResponse({
+            errorMessage: `Error: Path must be absolute. Received: ${filePath}`,
+          });
         }
 
         // Check if file exists
         try {
           await fs.access(filePath);
         } catch {
-          return buildMcpToolErrorResponse([`Error: File not found at path: ${filePath}`]);
+          return buildMcpToolErrorResponse({
+            errorMessage: `Error: File not found at path: ${filePath}`,
+          });
         }
 
         // Check if it's a directory
         const stats = await fs.stat(filePath);
         if (stats.isDirectory()) {
-          return buildMcpToolErrorResponse([
-            `Error: The specified path is a directory, not a file: ${filePath}. Use file_system_read_directory for directories.`,
-          ]);
+          return buildMcpToolErrorResponse({
+            errorMessage: `Error: The specified path is a directory, not a file: ${filePath}. Use file_system_read_directory for directories.`,
+          });
         }
 
+        // Get file stats
+        const fileStats = await fs.stat(filePath);
+
         // Read file content
         const fileContent = await fs.readFile(filePath, 'utf8');
 
@@ -58,17 +79,27 @@
 
         // If security check found issues, block the file
         if (securityCheckResult !== null) {
-          return buildMcpToolErrorResponse([
-            `Error: Security check failed. The file at ${filePath} may contain sensitive information.`,
-          ]);
+          return buildMcpToolErrorResponse({
+            errorMessage: `Error: Security check failed. The file at ${filePath} may contain sensitive information.`,
+          });
         }
 
-        return buildMcpToolSuccessResponse([`Content of ${filePath}:`, fileContent]);
+        // Calculate file metrics
+        const lines = fileContent.split('\n').length;
+        const size = fileStats.size;
+
+        return buildMcpToolSuccessResponse({
+          path: filePath,
+          content: fileContent,
+          size,
+          encoding: 'utf8',
+          lines,
+        } satisfies z.infer<typeof fileSystemReadFileOutputSchema>);
       } catch (error) {
         logger.error(`Error in file_system_read_file tool: ${error}`);
-        return buildMcpToolErrorResponse([
-          `Error reading file: ${error instanceof Error ? error.message : String(error)}`,
-        ]);
+        return buildMcpToolErrorResponse({
+          errorMessage: `Error reading file: ${error instanceof Error ? error.message : String(error)}`,
+        });
       }
     },
   );