@j0hanz/filesystem-mcp 1.2.3 → 1.3.0

package/dist/server/bootstrap.js

@@ -1,16 +1,18 @@
 import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import * as http from 'node:http';
+import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { InMemoryTaskMessageQueue, InMemoryTaskStore, } from '@modelcontextprotocol/sdk/experimental/tasks/stores/in-memory.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SetLevelRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { registerCompletions } from '../completions.js';
 import { formatUnknownErrorMessage } from '../lib/errors.js';
 import { createInMemoryResourceStore } from '../lib/resource-store.js';
 import { pkgInfo } from '../pkg-info.js';
 import { registerGetHelpPrompt } from '../prompts.js';
-import { registerInstructionResource, registerResultResources, } from '../resources.js';
+import { registerInstructionResource, registerMetricsResource, registerResultResources, } from '../resources.js';
+import { buildServerInstructions } from '../resources/generated-instructions.js';
 import { registerAllTools } from '../tools.js';
 import { withDefaultIcons } from '../tools/shared.js';
 import { buildServerCapabilities, supportsTaskToolRequests, } from './capabilities.js';
@@ -25,19 +27,8 @@ function getRootsManager(server) {
     }
     return manager;
 }
-async function loadServerInstructions() {
-    const defaultInstructions = `
-Filesystem MCP Instructions
-(Detailed instructions failed to load - check logs)
-`;
-    try {
-        const currentDir = path.dirname(fileURLToPath(import.meta.url));
-        return await fs.readFile(path.join(currentDir, '../instructions.md'), 'utf-8');
-    }
-    catch (error) {
-        console.error('[WARNING] Failed to load instructions.md:', formatUnknownErrorMessage(error));
-        return defaultInstructions;
-    }
+function loadServerInstructions() {
+    return buildServerInstructions();
 }
 async function getLocalIconInfo() {
     const name = 'logo.svg';
@@ -60,7 +51,7 @@ async function getLocalIconInfo() {
 }
 export async function createServer(options = {}) {
     const resourceStore = createInMemoryResourceStore();
-    const serverInstructions = await loadServerInstructions();
+    const serverInstructions = loadServerInstructions();
     const localIcon = await getLocalIconInfo();
     const taskToolSupport = supportsTaskToolRequests();
     const serverConfig = {
@@ -74,7 +65,10 @@ export async function createServer(options = {}) {
         serverConfig.taskMessageQueue = new InMemoryTaskMessageQueue();
     }
     if (serverInstructions) {
-        serverConfig.instructions = serverInstructions;
+        serverConfig.instructions =
+            'filesystem-mcp: Secure local filesystem MCP server. ' +
+                'Essential sequence: roots → ls/tree/find → read/grep. ' +
+                'Full reference: read the internal://instructions resource or invoke the get-help prompt.';
     }
     const server = new McpServer(withDefaultIcons({
         name: 'filesystem-mcp',
@@ -93,7 +87,8 @@ export async function createServer(options = {}) {
     registerInstructionResource(server, serverInstructions, localIcon);
     registerGetHelpPrompt(server, serverInstructions, localIcon);
     registerResultResources(server, resourceStore, localIcon);
-    registerCompletions(server);
+    registerMetricsResource(server, localIcon);
+    registerCompletions(server, serverInstructions);
     registerAllTools(server, {
         resourceStore,
         isInitialized: () => rootsManager.isInitialized(),
@@ -115,3 +110,214 @@ export async function startServer(server) {
     };
     rootsManager.logMissingDirectoriesIfNeeded(server);
 }
+async function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (chunk) => {
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf-8');
+            if (!raw) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                resolve(undefined);
+            }
+        });
+        req.on('error', reject);
+    });
+}
+async function createHttpSession(options, sessions) {
+    const mcpServer = await createServer(options);
+    const rootsManager = getRootsManager(mcpServer);
+    rootsManager.registerHandlers(mcpServer);
+    await rootsManager.recomputeAllowedDirectories();
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (sessionId) => {
+            sessions.set(sessionId, { server: mcpServer, transport });
+            rootsManager.logMissingDirectoriesIfNeeded(mcpServer);
+        },
+        onsessionclosed: (sessionId) => {
+            sessions.delete(sessionId);
+        },
+    });
+    transport.onclose = () => {
+        const { sessionId } = transport;
+        if (sessionId) {
+            sessions.delete(sessionId);
+        }
+        rootsManager.destroy();
+        mcpServer.close().catch((err) => {
+            console.error('[HTTP] Error closing MCP server:', formatUnknownErrorMessage(err));
+        });
+    };
+    await mcpServer.connect(transport);
+    return { server: mcpServer, transport };
+}
+export async function startHttpServer(port, options) {
+    const sessions = new Map();
+    async function handleMcpRequest(req, res) {
+        const { method } = req;
+        const sessionId = req.headers['mcp-session-id'];
+        const apiKey = process.env['FILESYSTEM_MCP_API_KEY'];
+        if (apiKey) {
+            const authHeader = req.headers['authorization'];
+            const bearerPrefix = 'Bearer ';
+            let authorized = false;
+            if (typeof authHeader === 'string' &&
+                authHeader.startsWith(bearerPrefix)) {
+                const userKey = authHeader.slice(bearerPrefix.length);
+                const expectedHash = createHash('sha256').update(apiKey).digest();
+                const actualHash = createHash('sha256').update(userKey).digest();
+                authorized = timingSafeEqual(expectedHash, actualHash);
+            }
+            if (!authorized) {
+                res.writeHead(401, {
+                    'Content-Type': 'application/json',
+                    'WWW-Authenticate': 'Bearer',
+                });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: { code: -32000, message: 'Unauthorized' },
+                    id: null,
+                }));
+                return;
+            }
+        }
+        try {
+            if (method === 'POST') {
+                const body = await readRequestBody(req);
+                if (sessionId && sessions.has(sessionId)) {
+                    const session = sessions.get(sessionId);
+                    if (session) {
+                        await session.transport.handleRequest(req, res, body);
+                    }
+                    else {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({
+                            jsonrpc: '2.0',
+                            error: {
+                                code: -32000,
+                                message: 'Bad Request: Session not found',
+                            },
+                            id: null,
+                        }));
+                    }
+                }
+                else if (!sessionId && isInitializeRequest(body)) {
+                    const { transport } = await createHttpSession(options, sessions);
+                    await transport.handleRequest(req, res, body);
+                }
+                else {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: No valid session ID provided',
+                        },
+                        id: null,
+                    }));
+                }
+            }
+            else if (method === 'GET') {
+                if (!sessionId || !sessions.has(sessionId)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: Invalid or missing session ID',
+                        },
+                        id: null,
+                    }));
+                    return;
+                }
+                const session = sessions.get(sessionId);
+                if (session) {
+                    await session.transport.handleRequest(req, res);
+                }
+                else {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: Session not found',
+                        },
+                        id: null,
+                    }));
+                }
+            }
+            else if (method === 'DELETE') {
+                if (!sessionId || !sessions.has(sessionId)) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: Invalid or missing session ID',
+                        },
+                        id: null,
+                    }));
+                    return;
+                }
+                const session = sessions.get(sessionId);
+                if (session) {
+                    await session.transport.handleRequest(req, res);
+                }
+                else {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: {
+                            code: -32000,
+                            message: 'Bad Request: Session not found',
+                        },
+                        id: null,
+                    }));
+                }
+            }
+            else {
+                res.writeHead(405, { Allow: 'GET, POST, DELETE' });
+                res.end('Method Not Allowed');
+            }
+        }
+        catch (error) {
+            console.error('[HTTP] Error handling request:', formatUnknownErrorMessage(error));
+            if (!res.headersSent) {
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: { code: -32603, message: 'Internal Server Error' },
+                    id: null,
+                }));
+            }
+        }
+    }
+    const httpServer = http.createServer((req, res) => {
+        const urlPath = (req.url ?? '/').split('?')[0];
+        if (urlPath === '/mcp') {
+            handleMcpRequest(req, res).catch((err) => {
+                console.error('[HTTP] Unhandled error in request handler:', formatUnknownErrorMessage(err));
+            });
+        }
+        else {
+            res.writeHead(404);
+            res.end('Not Found');
+        }
+    });
+    return new Promise((resolve, reject) => {
+        httpServer.once('error', reject);
+        httpServer.listen(port, () => {
+            console.error(`MCP HTTP server listening on port ${port}`);
+            resolve(httpServer);
+        });
+    });
+}

package/dist/server.d.ts

@@ -1,2 +1,2 @@
-export { createServer, startServer } from './server/bootstrap.js';
+export { createServer, startHttpServer, startServer, } from './server/bootstrap.js';
 export type { ServerOptions } from './server/types.js';

package/dist/server.js

@@ -1 +1 @@
-export { createServer, startServer } from './server/bootstrap.js';
+export { createServer, startHttpServer, startServer, } from './server/bootstrap.js';

package/dist/tools/apply-patch.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const APPLY_PATCH_TOOL: ToolContract;
 export declare function registerApplyPatchTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/apply-patch.js

@@ -8,7 +8,8 @@ import { validateExistingPath } from '../lib/path-validation.js';
 import { ApplyPatchInputSchema, ApplyPatchOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const APPLY_PATCH_TOOL = {
+export const APPLY_PATCH_TOOL = {
+    name: 'apply_patch',
     title: 'Apply Patch',
     description: 'Apply a unified diff patch to a file. ' +
         'Generate the patch with `diff_files`, then validate with `dryRun: true` before writing. ' +
@@ -16,6 +17,7 @@ const APPLY_PATCH_TOOL = {
     inputSchema: ApplyPatchInputSchema,
     outputSchema: ApplyPatchOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    gotchas: ['Patch must include valid hunk headers; use `dryRun=true` first.'],
 };
 function assertPatchTargetSizeWithinLimit(filePath, size, maxFileSize) {
     if (size <= maxFileSize)
@@ -69,8 +71,7 @@ export function registerApplyPatchTool(server, options = {}) {
         run: (signal) => handleApplyPatch(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(ApplyPatchInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -90,7 +91,8 @@ export function registerApplyPatchTool(server, options = {}) {
             return `🛠 apply_patch: ${name} • applied`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'apply_patch', APPLY_PATCH_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(ApplyPatchInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'apply_patch', APPLY_PATCH_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('apply_patch', withDefaultIcons({ ...APPLY_PATCH_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('apply_patch', withDefaultIcons({ ...APPLY_PATCH_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/calculate-hash.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const CALCULATE_HASH_TOOL: ToolContract;
 export declare function registerCalculateHashTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/calculate-hash.js

@@ -12,12 +12,16 @@ import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas
 import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
-const CALCULATE_HASH_TOOL = {
+export const CALCULATE_HASH_TOOL = {
+    name: 'calculate_hash',
     title: 'Calculate Hash',
     description: 'Calculate SHA-256 hash of a file or directory.',
     inputSchema: CalculateHashInputSchema,
     outputSchema: CalculateHashOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: [
+        'Directory hashing respects root `.gitignore` and sorts paths for stable output.',
+    ],
 };
 async function hashFile(filePath, encoding, signal) {
     assertNotAborted(signal);
@@ -204,11 +208,11 @@ export function registerCalculateHashTool(server, options = {}) {
         },
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(CalculateHashInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'calculate_hash', CALCULATE_HASH_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(CalculateHashInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'calculate_hash', CALCULATE_HASH_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('calculate_hash', withDefaultIcons({ ...CALCULATE_HASH_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('calculate_hash', withDefaultIcons({ ...CALCULATE_HASH_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/contract.d.ts

@@ -0,0 +1,41 @@
+import type { ZodType } from 'zod';
+export interface ToolContract {
+    /**
+     * The unique name of the tool (e.g., "read", "grep").
+     * This name is used in registration and client calls.
+     */
+    name: string;
+    /**
+     * A short human-readable title for documentation (e.g., "Read File").
+     */
+    title: string;
+    /**
+     * A detailed description of what the tool does.
+     */
+    description: string;
+    /**
+     * Zod schema for the tool's input arguments.
+     */
+    inputSchema: ZodType;
+    /**
+     * Zod schema for the tool's output result (optional).
+     */
+    outputSchema?: ZodType;
+    /**
+     * Optional annotations for tool behavior hints.
+     */
+    annotations?: {
+        readOnlyHint?: boolean;
+        idempotentHint?: boolean;
+        destructiveHint?: boolean;
+        openWorldHint?: boolean;
+    };
+    /**
+     * Specific usage nuances or edge cases for documentation.
+     */
+    nuances?: string[];
+    /**
+     * Common pitfalls or warnings for documentation.
+     */
+    gotchas?: string[];
+}

package/dist/tools/contract.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/create-directory.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const CREATE_DIRECTORY_TOOL: ToolContract;
 export declare function registerCreateDirectoryTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/create-directory.js

@@ -6,7 +6,8 @@ import { validatePathForWrite } from '../lib/path-validation.js';
 import { CreateDirectoryInputSchema, CreateDirectoryOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, IDEMPOTENT_WRITE_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const CREATE_DIRECTORY_TOOL = {
+export const CREATE_DIRECTORY_TOOL = {
+    name: 'mkdir',
     title: 'Create Directory',
     description: 'Create a new directory at the specified path (recursive)',
     inputSchema: CreateDirectoryInputSchema,
@@ -30,8 +31,7 @@ export function registerCreateDirectoryTool(server, options = {}) {
         run: (signal) => handleCreateDirectory(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(CreateDirectoryInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path) || args.path;
@@ -44,7 +44,8 @@ export function registerCreateDirectoryTool(server, options = {}) {
             return `🛠 mkdir: ${name} • created`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'mkdir', CREATE_DIRECTORY_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(CreateDirectoryInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'mkdir', CREATE_DIRECTORY_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('mkdir', withDefaultIcons({ ...CREATE_DIRECTORY_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('mkdir', withDefaultIcons({ ...CREATE_DIRECTORY_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/delete-file.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const DELETE_FILE_TOOL: ToolContract;
 export declare function registerDeleteFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/delete-file.js

@@ -6,12 +6,16 @@ import { validatePathForWrite } from '../lib/path-validation.js';
 import { DeleteFileInputSchema, DeleteFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const DELETE_FILE_TOOL = {
+export const DELETE_FILE_TOOL = {
+    name: 'rm',
     title: 'Delete File',
     description: 'Delete a file or directory.',
     inputSchema: DeleteFileInputSchema,
     outputSchema: DeleteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    gotchas: [
+        'Non-empty directory delete requires `recursive=true`; else returns actionable input error.',
+    ],
 };
 async function handleDeleteFile(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
@@ -74,8 +78,7 @@ export function registerDeleteFileTool(server, options = {}) {
             return buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path);
         },
     });
-    const validatedHandler = withValidatedArgs(DeleteFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🛠 rm: ${path.basename(args.path)}`,
         completionMessage: (args, result) => {
@@ -85,7 +88,8 @@ export function registerDeleteFileTool(server, options = {}) {
             return `🛠 rm: ${name} • deleted`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'rm', DELETE_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(DeleteFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'rm', DELETE_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('rm', withDefaultIcons({ ...DELETE_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('rm', withDefaultIcons({ ...DELETE_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/diff-files.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const DIFF_FILES_TOOL: ToolContract;
 export declare function registerDiffFilesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/diff-files.js

@@ -7,7 +7,8 @@ import { withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { DiffFilesInputSchema, DiffFilesOutputSchema } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const DIFF_FILES_TOOL = {
+export const DIFF_FILES_TOOL = {
+    name: 'diff_files',
     title: 'Diff Files',
     description: 'Generate a unified diff between two files. ' +
         'Output feeds directly into `apply_patch`. ' +
@@ -15,6 +16,7 @@ const DIFF_FILES_TOOL = {
     inputSchema: DiffFilesInputSchema,
     outputSchema: DiffFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    gotchas: ['`isIdentical=true` means no hunks (`@@`) and empty diff.'],
 };
 function assertDiffFileSizeWithinLimit(filePath, size, maxFileSize) {
     if (size <= maxFileSize)
@@ -80,8 +82,7 @@ export function registerDiffFilesTool(server, options = {}) {
         run: (signal) => handleDiffFiles(args, signal, options.resourceStore),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.original),
     });
-    const validatedHandler = withValidatedArgs(DiffFilesInputSchema, handler);
-    server.registerTool('diff_files', withDefaultIcons({ ...DIFF_FILES_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name1 = path.basename(args.original);
@@ -101,5 +102,7 @@ export function registerDiffFilesTool(server, options = {}) {
             const hunks = (sc.diff?.match(/@@/g) ?? []).length;
             return `🕮 diff_files: ${n1} ⟷ ${n2} • ${hunks} hunk${hunks !== 1 ? 's' : ''}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(DiffFilesInputSchema, wrappedHandler);
+    server.registerTool('diff_files', withDefaultIcons({ ...DIFF_FILES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/edit-file.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const EDIT_FILE_TOOL: ToolContract;
 export declare function registerEditFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/edit-file.js

@@ -5,7 +5,8 @@ import { atomicWriteFile } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
 import { EditFileInputSchema, EditFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const EDIT_FILE_TOOL = {
+export const EDIT_FILE_TOOL = {
+    name: 'edit',
     title: 'Edit File',
     description: 'Edit a file by replacing text. Sequentially applies a list of string replacements. ' +
         'Replaces the first occurrence of each `oldText`. ' +
@@ -14,6 +15,12 @@ const EDIT_FILE_TOOL = {
     inputSchema: EditFileInputSchema,
     outputSchema: EditFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    nuances: [
+        'Apply sequential literal replacements (first occurrence per edit).',
+    ],
+    gotchas: [
+        '`oldText` must match exactly; unmatched items are reported in `unmatchedEdits`.',
+    ],
 };
 function applyEdits(content, edits) {
     let newContent = content;
@@ -65,9 +72,14 @@ async function handleEditFile(args, signal) {
     if (appliedEdits > 0) {
         await atomicWriteFile(validPath, newContent, { encoding: 'utf-8', signal });
     }
+    const unmatchedNote = unmatchedEdits.length > 0
+        ? ` — ${unmatchedEdits.length} unmatched: [${unmatchedEdits
+            .map((s) => JSON.stringify(s.length > 40 ? `${s.slice(0, 40)}\u2026` : s))
+            .join(', ')}]`
+        : '';
     const message = appliedEdits === 0
-        ? `No edits applied to ${args.path}`
-        : `Successfully applied ${appliedEdits} edits to ${args.path}`;
+        ? `No edits applied to ${args.path}${unmatchedNote}`
+        : `Successfully applied ${appliedEdits} edits to ${args.path}${unmatchedNote}`;
     return buildToolResponse(message, structured);
 }
 export function registerEditFileTool(server, options = {}) {
@@ -79,8 +91,7 @@ export function registerEditFileTool(server, options = {}) {
         run: (signal) => handleEditFile(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(EditFileInputSchema, handler);
-    server.registerTool('edit', withDefaultIcons({ ...EDIT_FILE_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -98,5 +109,7 @@ export function registerEditFileTool(server, options = {}) {
             }
             return `🛠 edit: ${name} • [${sc.appliedEdits ?? 0} edits]`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(EditFileInputSchema, wrappedHandler);
+    server.registerTool('edit', withDefaultIcons({ ...EDIT_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/list-directory.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const LIST_DIRECTORY_TOOL: ToolContract;
 export declare function registerListDirectoryTool(server: McpServer, options?: ToolRegistrationOptions): void;