@j0hanz/filesystem-mcp 1.8.0 → 1.9.1

package/dist/server/bootstrap.d.ts

@@ -1,6 +1,24 @@
 import * as http from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { ServerOptions } from './types.js';
+import type { LoggingLevel } from '@modelcontextprotocol/sdk/types.js';
+export interface ServerOptions {
+    allowCwd?: boolean;
+    cliAllowedDirs?: string[];
+}
+interface CapabilityOptions {
+    enablePromptListChanged?: boolean;
+    enableTaskToolRequests?: boolean;
+}
+type ServerCapabilities = NonNullable<ConstructorParameters<typeof McpServer>[1]>['capabilities'];
+type NonOptionalServerCapabilities = NonNullable<ServerCapabilities>;
+export declare function buildServerCapabilities(options?: CapabilityOptions): NonOptionalServerCapabilities;
+export declare function supportsTaskToolRequests(): boolean;
+export interface LoggingState {
+    minimumLevel: LoggingLevel;
+}
+export declare function createLoggingState(minimumLevel?: LoggingLevel): LoggingState;
+export declare function logToMcp(server: McpServer | undefined, level: LoggingLevel, data: string, minLevel?: LoggingLevel): void;
 export declare function createServer(options?: ServerOptions): Promise<McpServer>;
 export declare function startServer(server: McpServer): Promise<void>;
 export declare function startHttpServer(port: number, options: ServerOptions): Promise<http.Server>;
+export {};

package/dist/server/bootstrap.js

@@ -6,19 +6,105 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { registerCompletions } from '../completions.js';
-import { DEFAULT_LOG_LEVEL, parseEnvInt, REQUIRED_MCP_PROTOCOL_VERSION, } from '../lib/constants.js';
+import { DEFAULT_LOG_LEVEL, parseEnvInt } from '../lib/constants.js';
 import { formatUnknownErrorMessage } from '../lib/errors.js';
+import { withAllowedDirectoriesState } from '../lib/paths.js';
 import { createInMemoryResourceStore } from '../lib/resource-store.js';
+import { isRecord } from '../lib/utils.js';
+import { registerCompletions } from '../completions.js';
 import { pkgInfo } from '../pkg-info.js';
 import { registerGetHelpPrompt } from '../prompts.js';
 import { registerInstructionResource, registerMetricsResource, registerResultResources, registerToolCatalogResource, registerToolInfoResource, registerWorkflowGuideResource, } 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';
-import { createLoggingState } from './logging.js';
 import { RootsManager } from './roots-manager.js';
+let cachedTaskToolSupport;
+function detectTaskToolSupport() {
+    if (cachedTaskToolSupport !== undefined) {
+        return cachedTaskToolSupport;
+    }
+    try {
+        // Instantiate a minimal, unconnected probe server to duck-type check for
+        // task tool support. The probe has no transport or active connections, so
+        // close() only releases in-memory state; fire-and-forget is safe here.
+        const probe = new McpServer({
+            name: 'filesystem-mcp-capability-probe',
+            version: '0.0.0',
+        }, { capabilities: { tools: {} } });
+        cachedTaskToolSupport =
+            typeof probe.experimental.tasks.registerToolTask === 'function';
+        probe.close().catch(() => { });
+    }
+    catch {
+        cachedTaskToolSupport = false;
+    }
+    return cachedTaskToolSupport;
+}
+export function buildServerCapabilities(options = {}) {
+    const capabilities = {
+        logging: {},
+        resources: {},
+        tools: {},
+        prompts: options.enablePromptListChanged ? { listChanged: true } : {},
+        completions: {},
+    };
+    if (options.enableTaskToolRequests) {
+        // NOTE: enabling task tool requests requires the caller to configure
+        // an InMemoryTaskStore and InMemoryTaskMessageQueue on the McpServer.
+        // InMemoryTaskStore accumulates completed task records with no TTL eviction —
+        // suitable for short-lived stdio sessions. Long-running HTTP servers should
+        // replace it with a TTL-evicting store to avoid unbounded memory growth.
+        capabilities.tasks = {
+            list: {},
+            cancel: {},
+            requests: { tools: { call: {} } },
+        };
+    }
+    return capabilities;
+}
+export function supportsTaskToolRequests() {
+    return detectTaskToolSupport();
+}
+const MCP_LOGGER_NAME = 'filesystem-mcp';
+const LOG_LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    notice: 2,
+    warning: 3,
+    error: 4,
+    critical: 5,
+    alert: 6,
+    emergency: 7,
+};
+export function createLoggingState(minimumLevel = 'debug') {
+    return { minimumLevel };
+}
+function canSendMcpLogs(server) {
+    const capabilities = server.server.getClientCapabilities();
+    if (!isRecord(capabilities))
+        return false;
+    if (!('logging' in capabilities))
+        return false;
+    return !!capabilities['logging'];
+}
+export function logToMcp(server, level, data, minLevel = 'debug') {
+    if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[minLevel]) {
+        return;
+    }
+    if (!server || !canSendMcpLogs(server)) {
+        console.error(data);
+        return;
+    }
+    const params = {
+        level,
+        logger: MCP_LOGGER_NAME,
+        data,
+    };
+    void server.sendLoggingMessage(params).catch((error) => {
+        console.error(`Failed to send MCP log: ${level} | ${data}`, formatUnknownErrorMessage(error));
+    });
+}
 const { version: SERVER_VERSION, description: SERVER_DESCRIPTION, homepage: SERVER_HOMEPAGE, } = pkgInfo;
 const rootsManagers = new WeakMap();
 function getRootsManager(server) {
@@ -164,7 +250,7 @@ async function createHttpSession(options, sessions) {
     const transport = new StreamableHTTPServerTransport({
         sessionIdGenerator: () => randomUUID(),
         onsessioninitialized: (sessionId) => {
-            sessions.set(sessionId, { server: mcpServer, transport });
+            sessions.set(sessionId, { server: mcpServer, rootsManager, transport });
             rootsManager.logMissingDirectoriesIfNeeded(mcpServer);
         },
     });
@@ -179,7 +265,7 @@ async function createHttpSession(options, sessions) {
         });
     };
     await mcpServer.connect(transport);
-    return { server: mcpServer, transport };
+    return { server: mcpServer, rootsManager, transport };
 }
 function sendJsonRpcError(res, status, code, message) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
@@ -195,32 +281,33 @@ function isAllowedOrigin(origin) {
         return true; // Non-browser clients omit Origin.
     return LOCALHOST_ORIGIN_RE.test(origin);
 }
-function getProtocolVersionHeader(req) {
-    const rawProtocolVersion = req.headers['mcp-protocol-version'];
-    if (typeof rawProtocolVersion === 'string') {
-        return rawProtocolVersion;
-    }
-    if (Array.isArray(rawProtocolVersion)) {
-        return rawProtocolVersion.find((value) => value === REQUIRED_MCP_PROTOCOL_VERSION);
-    }
-    return undefined;
-}
-function ensureProtocolVersionHeader(req, res) {
-    const protocolVersion = getProtocolVersionHeader(req);
-    if (protocolVersion === REQUIRED_MCP_PROTOCOL_VERSION) {
-        return true;
-    }
-    sendJsonRpcError(res, 400, -32000, 'Bad Request: MCP-Protocol-Version header missing or unsupported');
-    return false;
-}
 function discardRequestBody(req) {
     req.on('error', () => {
         // Best effort drain to avoid corrupting keep-alive pipelines.
     });
     req.resume();
 }
+async function handleSessionTransportRequest(session, req, res, body) {
+    await withAllowedDirectoriesState(session.rootsManager.getAllowedDirectoriesState(), () => session.transport.handleRequest(req, res, body));
+}
+function isLoopbackHttpHost(host) {
+    const normalized = host.trim().toLowerCase();
+    return (normalized === '127.0.0.1' ||
+        normalized === 'localhost' ||
+        normalized === '::1' ||
+        normalized === '[::1]');
+}
+function assertHttpBindingSecurity(host) {
+    if (isLoopbackHttpHost(host))
+        return;
+    if (process.env['FILESYSTEM_MCP_API_KEY'])
+        return;
+    throw new Error(`Refusing to bind HTTP server to non-loopback host '${host}' without FILESYSTEM_MCP_API_KEY.`);
+}
 export async function startHttpServer(port, options) {
     const sessions = new Map();
+    const httpHost = process.env['FILESYSTEM_MCP_HTTP_HOST'] ?? '127.0.0.1';
+    assertHttpBindingSecurity(httpHost);
     async function handleMcpRequest(req, res) {
         const { method } = req;
         const MAX_SESSION_ID_LENGTH = 256;
@@ -242,9 +329,11 @@ export async function startHttpServer(port, options) {
             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 (userKey.length <= 4096) {
+                    const expectedHash = createHash('sha256').update(apiKey).digest();
+                    const actualHash = createHash('sha256').update(userKey).digest();
+                    authorized = timingSafeEqual(expectedHash, actualHash);
+                }
             }
             if (!authorized) {
                 res.writeHead(401, {
@@ -267,14 +356,10 @@ export async function startHttpServer(port, options) {
                         discardRequestBody(req);
                         return;
                     }
-                    if (!ensureProtocolVersionHeader(req, res)) {
-                        discardRequestBody(req);
-                        return;
-                    }
                     const body = await readRequestBody(req);
                     const session = sessions.get(sessionId);
                     if (session) {
-                        await session.transport.handleRequest(req, res, body);
+                        await handleSessionTransportRequest(session, req, res, body);
                     }
                     else {
                         sendJsonRpcError(res, 404, -32000, 'Session not found');
@@ -283,13 +368,13 @@ export async function startHttpServer(port, options) {
                 }
                 const body = await readRequestBody(req);
                 if (isInitializeRequest(body)) {
-                    const maxSessions = parseInt(process.env['FILESYSTEM_MCP_MAX_HTTP_SESSIONS'] ?? '', 10) || 100;
+                    const maxSessions = parseEnvInt('FILESYSTEM_MCP_MAX_HTTP_SESSIONS', 100, 1, 10_000);
                     if (sessions.size >= maxSessions) {
                         sendJsonRpcError(res, 503, -32000, 'Too many sessions');
                         return;
                     }
-                    const { transport } = await createHttpSession(options, sessions);
-                    await transport.handleRequest(req, res, body);
+                    const session = await createHttpSession(options, sessions);
+                    await handleSessionTransportRequest(session, req, res, body);
                     return;
                 }
                 sendJsonRpcError(res, 400, -32000, 'Bad Request: No valid session ID provided');
@@ -304,20 +389,24 @@ export async function startHttpServer(port, options) {
                     sendJsonRpcError(res, 404, -32000, 'Session not found');
                     return;
                 }
-                if (!ensureProtocolVersionHeader(req, res)) {
-                    return;
-                }
                 const session = sessions.get(sessionId);
                 if (session) {
-                    await session.transport.handleRequest(req, res);
+                    await handleSessionTransportRequest(session, req, res);
                 }
                 else {
                     sendJsonRpcError(res, 404, -32000, 'Session not found');
                 }
             }
             else {
-                res.writeHead(405, { Allow: 'GET, POST, DELETE' });
-                res.end('Method Not Allowed');
+                res.writeHead(405, {
+                    Allow: 'GET, POST, DELETE',
+                    'Content-Type': 'application/json',
+                });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: { code: -32000, message: 'Method Not Allowed' },
+                    id: null,
+                }));
             }
         }
         catch (error) {
@@ -345,9 +434,6 @@ export async function startHttpServer(port, options) {
             res.end('Not Found');
         }
     });
-    // Default to localhost-only binding to prevent DNS-rebinding and unintended
-    // external exposure. Override with FILESYSTEM_MCP_HTTP_HOST for remote setups.
-    const httpHost = process.env['FILESYSTEM_MCP_HTTP_HOST'] ?? '127.0.0.1';
     return new Promise((resolve, reject) => {
         httpServer.once('error', reject);
         httpServer.listen(port, httpHost, () => {

package/dist/server/roots-manager.d.ts

@@ -1,9 +1,11 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type LoggingState } from './logging.js';
-import type { ServerOptions } from './types.js';
+import { type AllowedDirectoriesState } from '../lib/paths.js';
+import { type LoggingState } from './bootstrap.js';
+import type { ServerOptions } from './bootstrap.js';
 export declare class RootsManager {
     private rootsUpdateTimeout;
     private rootDirectories;
+    private allowedDirectoriesState;
     private clientInitialized;
     private updatingRoots;
     private pendingRootsUpdate;
@@ -12,6 +14,7 @@ export declare class RootsManager {
     constructor(options: ServerOptions, loggingState: LoggingState);
     isInitialized(): boolean;
     destroy(): void;
+    getAllowedDirectoriesState(): AllowedDirectoriesState;
     logMissingDirectoriesIfNeeded(server: McpServer): void;
     registerHandlers(server: McpServer): void;
     recomputeAllowedDirectories(): Promise<void>;

package/dist/server/roots-manager.js

@@ -3,9 +3,9 @@ import { InitializedNotificationSchema, RootsListChangedNotificationSchema, } fr
 import { z } from 'zod';
 import { formatUnknownErrorMessage } from '../lib/errors.js';
 import { assertNotAborted, createTimedAbortSignal, withAbort, } from '../lib/fs-helpers.js';
-import { getAllowedDirectories, getValidRootDirectories, isPathWithinDirectories, normalizePath, setAllowedDirectoriesResolved, } from '../lib/path-validation.js';
-import { isRecord } from '../lib/type-guards.js';
-import { logToMcp } from './logging.js';
+import { getValidRootDirectories, isPathWithinDirectories, normalizePath, resolveAllowedDirectoriesState, setAllowedDirectoriesStateResolved, } from '../lib/paths.js';
+import { isRecord } from '../lib/utils.js';
+import { logToMcp } from './bootstrap.js';
 const ROOTS_TIMEOUT_MS = 5000;
 const ROOTS_DEBOUNCE_MS = 100;
 function normalizeCLIDirectories(dirs) {
@@ -83,6 +83,10 @@ async function filterRootsWithinBaseline(roots, baseline, signal) {
 export class RootsManager {
     rootsUpdateTimeout;
     rootDirectories = [];
+    allowedDirectoriesState = {
+        primary: [],
+        expanded: [],
+    };
     clientInitialized = false;
     // Set to true when an update is in progress, to prevent concurrent executions. If a change arrives while true, we queue a single retry after completion to ensure the last-known state is applied. This
     updatingRoots = false;
@@ -103,8 +107,14 @@ export class RootsManager {
             this.rootsUpdateTimeout = undefined;
         }
     }
+    getAllowedDirectoriesState() {
+        return {
+            primary: [...this.allowedDirectoriesState.primary],
+            expanded: [...this.allowedDirectoriesState.expanded],
+        };
+    }
     logMissingDirectoriesIfNeeded(server) {
-        if (getAllowedDirectories().length === 0) {
+        if (this.allowedDirectoriesState.expanded.length === 0) {
             this.logMissingDirectories(server);
         }
     }
@@ -130,7 +140,9 @@ export class RootsManager {
                 ? await filterRootsWithinBaseline(this.rootDirectories, baseline, signal)
                 : this.rootDirectories;
             const combined = [...baseline, ...rootsToInclude];
-            await setAllowedDirectoriesResolved(combined, signal);
+            const nextState = await resolveAllowedDirectoriesState(combined, signal);
+            this.allowedDirectoriesState = nextState;
+            setAllowedDirectoriesStateResolved(nextState);
         }
         finally {
             cleanup();

package/dist/tools/apply-patch.js

@@ -4,7 +4,7 @@ import { applyPatch } from 'diff';
 import { MAX_TEXT_FILE_SIZE } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
-import { validateExistingPath } from '../lib/path-validation.js';
+import { assertAllowedFileAccess, validateExistingPath } from '../lib/paths.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';
@@ -12,8 +12,8 @@ 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. ' +
-        'On failure, regenerate a fresh patch via `diff_files` against the current file content and retry.',
+        'Workflow: `diff_files` \u2192 `apply_patch(dryRun:true)` \u2192 `apply_patch`. ' +
+        'On failure, regenerate the patch from current file content.',
     inputSchema: ApplyPatchInputSchema,
     outputSchema: ApplyPatchOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
@@ -36,6 +36,7 @@ function assertPatchHasHunks(patch) {
 async function handleApplyPatch(args, signal) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const validPath = await validateExistingPath(args.path, signal);
+    assertAllowedFileAccess(args.path, validPath);
     const stats = await withAbort(fs.stat(validPath), signal);
     assertPatchTargetSizeWithinLimit(validPath, stats.size, maxFileSize);
     const content = await fs.readFile(validPath, { encoding: 'utf-8', signal });

package/dist/tools/calculate-hash.js

@@ -4,11 +4,11 @@ import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
 import { PARALLEL_CONCURRENCY } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
-import { isIgnoredByGitignore, loadRootGitignore, } from '../lib/file-operations/gitignore.js';
-import { globEntries } from '../lib/file-operations/glob-engine.js';
+import { isIgnoredByGitignore, loadRootGitignore, } from '../lib/file-operations/core.js';
+import { globEntries } from '../lib/file-operations/traversal.js';
 import { assertNotAborted, withAbort } from '../lib/fs-helpers.js';
-import { validateExistingPath } from '../lib/path-validation.js';
-import { reportPeriodicProgress } from '../lib/progress-reporting.js';
+import { validateExistingPath } from '../lib/paths.js';
+import { reportPeriodicProgress } from '../lib/utils.js';
 import { CalculateHashInputSchema, CalculateHashOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';

package/dist/tools/create-directory.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises';
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
-import { validatePathForWrite } from '../lib/path-validation.js';
+import { validatePathForWrite } from '../lib/paths.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';

package/dist/tools/delete-file.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { ErrorCode, isNodeError, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
-import { isAllowedDirectoryRoot, validatePathForWrite, } from '../lib/path-validation.js';
+import { isAllowedDirectoryRoot, validatePathForWrite } from '../lib/paths.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';
@@ -14,8 +14,8 @@ export const DELETE_FILE_TOOL = {
     outputSchema: DeleteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
     gotchas: [
-        'Deletion is permanent — there is no undo or recycle bin.',
-        'Non-empty directory delete requires `recursive=true`; else returns actionable input error.',
+        'No undo — deletion is permanent.',
+        'Non-empty directories require `recursive=true`.',
     ],
 };
 async function handleDeleteFile(args, signal) {

package/dist/tools/diff-files.js

@@ -4,7 +4,7 @@ import { createTwoFilesPatch } from 'diff';
 import { MAX_TEXT_FILE_SIZE } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
-import { validateExistingPath } from '../lib/path-validation.js';
+import { validateExistingPath } from '../lib/paths.js';
 import { DiffFilesInputSchema, DiffFilesOutputSchema } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
@@ -13,7 +13,7 @@ export const DIFF_FILES_TOOL = {
     title: 'Diff Files',
     description: 'Generate a unified diff between two files. ' +
         'Output feeds directly into `apply_patch`. ' +
-        'Check `isIdentical` in the response — if true, the files are already in sync and no patch is needed.',
+        '`isIdentical=true` means files match \u2014 no patch needed.',
     inputSchema: DiffFilesInputSchema,
     outputSchema: DiffFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,

package/dist/tools/edit-file.js

@@ -1,28 +1,24 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import RE2 from 're2';
-import { ErrorCode } from '../lib/errors.js';
-import { atomicWriteFile } from '../lib/fs-helpers.js';
-import { validateExistingPath } from '../lib/path-validation.js';
+import { MAX_TEXT_FILE_SIZE } from '../lib/constants.js';
+import { ErrorCode, McpError } from '../lib/errors.js';
+import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
+import { assertAllowedFileAccess, validateExistingPath } from '../lib/paths.js';
 import { EditFileInputSchema, EditFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 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`. ' +
-        '`oldText` must match exactly — include 3–5 lines of surrounding context to uniquely target the location. ' +
-        'Use `dryRun: true` to validate edits before writing.',
+    description: 'Apply sequential literal string replacements to a file (first occurrence per edit). ' +
+        '`oldText` must match exactly \u2014 include 3\u20135 lines of context for unique targeting. ' +
+        'Use `dryRun:true` to preview.',
     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`.',
-    ],
+    nuances: ['Each edit applies to the output of the previous edit.'],
+    gotchas: ['Unmatched `oldText` entries listed in `unmatchedEdits`.'],
 };
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -88,6 +84,11 @@ function applyEdits(content, edits, ignoreWhitespace) {
 }
 export async function handleEditFile(args, signal) {
     const validPath = await validateExistingPath(args.path, signal);
+    assertAllowedFileAccess(args.path, validPath);
+    const stats = await withAbort(fs.stat(validPath), signal);
+    if (stats.size > MAX_TEXT_FILE_SIZE) {
+        throw new McpError(ErrorCode.E_TOO_LARGE, `File too large for edit: ${args.path} (${stats.size} bytes > ${MAX_TEXT_FILE_SIZE} bytes)`, args.path, { size: stats.size, maxFileSize: MAX_TEXT_FILE_SIZE });
+    }
     const content = await fs.readFile(validPath, { encoding: 'utf-8', signal });
     const { content: newContent, appliedEdits, unmatchedEdits, lineRange, } = applyEdits(content, args.edits, args.ignoreWhitespace);
     const structured = {

package/dist/tools/list-directory.js

@@ -1,19 +1,17 @@
 import * as path from 'node:path';
-import { formatOperationSummary, joinLines } from '../config.js';
 import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
-import { listDirectory } from '../lib/file-operations/list-directory.js';
+import { listDirectory } from '../lib/file-operations/metadata.js';
+import { formatOperationSummary, joinLines } from '../config.js';
 import { ListDirectoryInputSchema, ListDirectoryOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, decodeOffsetCursor, encodeOffsetCursor, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const LIST_DIRECTORY_TOOL = {
     name: 'ls',
     title: 'List Directory',
-    description: 'List the immediate contents of a directory (non-recursive). ' +
-        'Returns name, relative path, type (file/directory/symlink), size, and modified date. ' +
-        'Omit path to list the workspace root. ' +
-        'Use includeIgnored=true to include ignored directories like node_modules. ' +
-        'For recursive searches, use find instead.',
+    description: 'List immediate directory contents (non-recursive): name, path, type, size, modified date. ' +
+        'Omit path for workspace root. `includeIgnored=true` for node_modules etc. ' +
+        'For recursive search, use `find`.',
     inputSchema: ListDirectoryInputSchema,
     outputSchema: ListDirectoryOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,

package/dist/tools/move-file.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { ErrorCode, formatUnknownErrorMessage, isNodeError, McpError, } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
-import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
+import { assertAllowedFileAccess, validateExistingPath, validatePathForWrite, } from '../lib/paths.js';
 import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
@@ -48,6 +48,7 @@ export async function handleMoveFile(args, signal) {
         let validSource;
         try {
             validSource = await validateExistingPath(src, signal);
+            assertAllowedFileAccess(src, validSource);
         }
         catch (error) {
             failed.push({

package/dist/tools/read-multiple.js

@@ -1,16 +1,15 @@
 import * as path from 'node:path';
 import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.js';
-import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js';
+import { readMultipleFiles } from '../lib/file-operations/metadata.js';
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } from '../schemas.js';
 import { buildBatchCompletionSuffix, buildBatchPathContext, buildResourceLink, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const READ_MULTIPLE_FILES_TOOL = {
     name: 'read_many',
     title: 'Read Multiple Files',
-    description: 'Read multiple text files in a single request. ' +
-        'Returns contents and metadata for each file. ' +
-        'For single file, use read for simpler output.',
+    description: 'Read multiple text files in one request with contents and metadata. ' +
+        'For a single file, use `read`.',
     inputSchema: ReadMultipleFilesInputSchema,
     outputSchema: ReadMultipleFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,

package/dist/tools/read.js

@@ -8,9 +8,9 @@ import { registerToolTaskIfAvailable } from './task-support.js';
 export const READ_FILE_TOOL = {
     name: 'read',
     title: 'Read File',
-    description: 'Read the text contents of a file. ' +
-        'Use head parameter to preview the first N lines of large files. ' +
-        'For multiple files, use read_many for efficiency.',
+    description: 'Read text file contents. ' +
+        'Use `head` to preview first N lines of large files. ' +
+        'For multiple files, use `read_many`.',
     inputSchema: ReadFileInputSchema,
     outputSchema: ReadFileOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,

package/dist/tools/replace-in-files.js

@@ -5,28 +5,26 @@ import RE2 from 're2';
 import safeRegex from 'safe-regex2';
 import { DEFAULT_EXCLUDE_PATTERNS, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from '../lib/constants.js';
 import { ErrorCode, formatUnknownErrorMessage, McpError, } from '../lib/errors.js';
-import { globEntries } from '../lib/file-operations/glob-engine.js';
+import { globEntries } from '../lib/file-operations/traversal.js';
 import { atomicWriteFile, withAbort } from '../lib/fs-helpers.js';
-import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
-import { reportPeriodicProgress } from '../lib/progress-reporting.js';
+import { validateExistingPath, validatePathForWrite } from '../lib/paths.js';
+import { reportPeriodicProgress } from '../lib/utils.js';
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, resolveFinalProgressCurrent, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const SEARCH_AND_REPLACE_TOOL = {
     name: 'search_and_replace',
     title: 'Search and Replace',
-    description: 'Search and replace text across multiple files matching a glob pattern. ' +
-        'Replaces ALL occurrences in each file (unlike `edit` which replaces only the first). ' +
-        'Use `filePattern` to scope which files are touched. ' +
-        'Always run with `dryRun: true` first to verify matches before writing. ' +
-        'Returns a unified diff of changes in `dryRun` mode. ' +
-        'Literal mode (default) matches exact text; `isRegex: true` enables RE2 regex with capture groups ($1, $2).',
+    description: 'Bulk search-and-replace across files matching a glob. ' +
+        'Replaces ALL occurrences per file (unlike `edit`: first only). ' +
+        'Always `dryRun:true` first \u2014 returns a unified diff. ' +
+        'Literal matching by default; `isRegex:true` enables RE2 with capture groups ($1, $2).',
     inputSchema: SearchAndReplaceInputSchema,
     outputSchema: SearchAndReplaceOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
     taskSupport: 'optional',
     gotchas: [
-        'Literal mode is default; `isRegex=true` enables RE2 + capture replacements (`$1`, `$2`).',
+        'Replaces ALL occurrences — not just the first. Use `edit` for single replacements.',
     ],
     nuances: [
         'Changed-file sample and failure sample are capped/truncated in output.',