@j0hanz/filesystem-mcp 1.7.3 → 1.9.0

package/dist/server/bootstrap.js

@@ -6,19 +6,104 @@ 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 { formatUnknownErrorMessage } from '../lib/errors.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) {
@@ -242,9 +327,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, {
@@ -283,7 +370,7 @@ 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;
@@ -316,8 +403,15 @@ export async function startHttpServer(port, options) {
                 }
             }
             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) {

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

@@ -1,6 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type LoggingState } from './logging.js';
-import type { ServerOptions } from './types.js';
+import { type LoggingState } from './bootstrap.js';
+import type { ServerOptions } from './bootstrap.js';
 export declare class RootsManager {
     private rootsUpdateTimeout;
     private rootDirectories;

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 { getAllowedDirectories, getValidRootDirectories, isPathWithinDirectories, normalizePath, setAllowedDirectoriesResolved, } 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) {

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 });
@@ -48,6 +49,9 @@ async function handleApplyPatch(args, signal) {
     if (patched === false) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, 'Patch application failed. The file content may have changed or patch context is insufficient. Generate a fresh patch via diff_files against the current file, then retry. If differences are minor, enable fuzzy matching with the fuzzFactor parameter.');
     }
+    if (patched === content) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Patch had no effect — the file content is unchanged after applying. The patch may not match the current file content. Generate a fresh patch via diff_files and retry.');
+    }
     if (args.dryRun) {
         return buildToolResponse('Dry run successful. Patch can be applied.', {
             ok: true,

package/dist/tools/calculate-hash.js

@@ -4,12 +4,13 @@ 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 { 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, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 const WINDOWS_PATH_SEPARATOR = /\\/gu;
 export const CALCULATE_HASH_TOOL = {
@@ -54,13 +55,6 @@ function updateCompositeHash(hasher, pathLengthBytes, relativePath, fileHash) {
     hasher.update(relativePathBytes);
     hasher.update(fileHash);
 }
-function reportHashProgress(onProgress, current, force = false) {
-    if (!onProgress || current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current });
-}
 async function hashDirectory(dirPath, options = {}) {
     const { signal, onProgress } = options;
     const gitignoreMatcher = await loadRootGitignore(dirPath, signal);
@@ -102,9 +96,12 @@ async function hashDirectory(dirPath, options = {}) {
         }));
         entries.push(...batchResults);
         filesHashed += batchResults.length;
-        reportHashProgress(onProgress, filesHashed);
+        reportPeriodicProgress(onProgress, filesHashed, { throttleModulo: 25 });
     }
-    reportHashProgress(onProgress, filesHashed, true);
+    reportPeriodicProgress(onProgress, filesHashed, {
+        throttleModulo: 25,
+        force: true,
+    });
     assertNotAborted(signal);
     // Sort by path with byte-wise semantics for deterministic ordering.
     entries.sort(comparePaths);
@@ -141,7 +138,10 @@ async function handleCalculateHash(args, signal, onProgress) {
     else {
         // Hash single file
         const hash = await hashFile(validPath, 'hex', signal);
-        reportHashProgress(onProgress, 1, true);
+        reportPeriodicProgress(onProgress, 1, {
+            throttleModulo: 25,
+            force: true,
+        });
         return buildToolResponse(hash, {
             ok: true,
             path: validPath,
@@ -171,7 +171,7 @@ export function registerCalculateHashTool(server, options = {}) {
                 const result = await handleCalculateHash(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
                 const totalFiles = sc.ok ? (sc.fileCount ?? 1) : 1;
-                const finalCurrent = Math.max(totalFiles + 1, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, totalFiles + 1);
                 let suffix;
                 if (!sc.ok) {
                     suffix = 'failed';

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

@@ -1,8 +1,8 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { ErrorCode, isNodeError } from '../lib/errors.js';
+import { ErrorCode, isNodeError, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
-import { 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,12 +14,15 @@ 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) {
     const validPath = await validatePathForWrite(args.path, signal);
+    if (isAllowedDirectoryRoot(validPath)) {
+        throw new McpError(ErrorCode.E_ACCESS_DENIED, `Deleting a workspace root directory is not allowed: ${args.path}`);
+    }
     let stats;
     try {
         stats = await withAbort(fs.lstat(validPath), 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 { buildBatchPathContext, buildResourceLink, buildToolErrorResponse, buildToolResponse, createToolProgressSession, executeToolWithDiagnostics, maybeExternalizeTextContent, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.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,
@@ -20,23 +19,6 @@ export const READ_MULTIPLE_FILES_TOOL = {
         'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
     ],
 };
-function buildReadManyCompletionSuffix(summary) {
-    const total = summary?.total ?? 0;
-    const failed = summary?.failed ?? 0;
-    const succeeded = summary?.succeeded ?? 0;
-    if (failed) {
-        return `${succeeded}/${total} read, ${failed} failed`;
-    }
-    const label = total === 1 ? 'file' : 'files';
-    return `${total} ${label} read`;
-}
-function createReadManyProgressCallbacks(extra, context, totalPaths) {
-    const progress = createToolProgressSession(extra, `🕮 read_many: ${context}`);
-    const onReadComplete = () => {
-        progress.increment((current) => `🕮 read_many: ${context} [${current}/${totalPaths} read]`);
-    };
-    return { progress, onReadComplete };
-}
 function toStructuredReadManyResult(result) {
     const structured = {
         path: result.path,
@@ -152,13 +134,18 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             context: { path: primaryPath },
             run: async (signal) => {
                 const context = buildBatchPathContext(args.paths, 'files');
-                const { progress, onReadComplete } = createReadManyProgressCallbacks(extra, context, args.paths.length);
+                const { progress, onItemComplete } = createBatchProgressCallbacks(extra, {
+                    toolLabel: '🕮 read_many',
+                    context,
+                    totalItems: args.paths.length,
+                    itemVerb: 'read',
+                });
                 try {
-                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onReadComplete);
+                    const result = await handleReadMultipleFiles(args, signal, options.resourceStore, onItemComplete);
                     const sc = result.structuredContent;
-                    const suffix = buildReadManyCompletionSuffix(sc.summary);
+                    const suffix = buildBatchCompletionSuffix(sc.summary, 'files read', 'file read');
                     const total = sc.summary?.total ?? 0;
-                    const finalCurrent = Math.max(total, progress.getCurrent() + 1);
+                    const finalCurrent = resolveFinalProgressCurrent(progress, total);
                     progress.complete(`🕮 read_many: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }

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,27 +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 { 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, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.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.',
@@ -204,13 +203,6 @@ function createReplacementMatcher(args) {
     }
     return createLiteralReplacementMatcher(args.searchPattern);
 }
-function reportReplaceProgress(onProgress, current, force = false) {
-    if (current === 0)
-        return;
-    if (!force && current % 25 !== 0)
-        return;
-    onProgress({ current });
-}
 export async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
@@ -233,14 +225,19 @@ export async function handleSearchAndReplace(args, signal, onProgress = () => {
         concurrency: REPLACE_CONCURRENCY,
         onEntry: () => {
             summary.processedFiles++;
-            reportReplaceProgress(onProgress, summary.processedFiles);
+            reportPeriodicProgress(onProgress, summary.processedFiles, {
+                throttleModulo: 25,
+            });
         },
         runEntry: async (entryPath) => processEntry(entryPath, {
             dryRun: args.dryRun,
             returnDiff: args.returnDiff ?? false,
         }, args.replacement, matcher, maxFileSize, signal, summary),
     });
-    reportReplaceProgress(onProgress, summary.processedFiles, true);
+    reportPeriodicProgress(onProgress, summary.processedFiles, {
+        throttleModulo: 25,
+        force: true,
+    });
     const failureSuffix = summary.failedFiles > 0 ? ` (${summary.failedFiles} failed)` : '';
     return buildToolResponse(`Found ${summary.totalMatches} matches in ${summary.filesChanged} files${failureSuffix}.${args.dryRun ? ' (Dry run)' : ''}`, {
         ok: true,
@@ -279,7 +276,7 @@ export function registerSearchAndReplaceTool(server, options = {}) {
             try {
                 const result = await handleSearchAndReplace(args, signal, progressWithMessage);
                 const sc = result.structuredContent;
-                const finalCurrent = Math.max((sc.processedFiles ?? 0) + 1, progress.getCurrent() + 1);
+                const finalCurrent = resolveFinalProgressCurrent(progress, (sc.processedFiles ?? 0) + 1);
                 const matchWord = (sc.matches ?? 0) === 1 ? 'match' : 'matches';
                 const fileWord = (sc.filesChanged ?? 0) === 1 ? 'file' : 'files';
                 let endSuffix = `${sc.matches ?? 0} ${matchWord} in ${sc.filesChanged ?? 0} ${fileWord}`;

package/dist/tools/roots.js

@@ -1,19 +1,17 @@
-import { joinLines } from '../config.js';
 import { ErrorCode } from '../lib/errors.js';
-import { getAllowedDirectories } from '../lib/path-validation.js';
+import { getAllowedDirectories } from '../lib/paths.js';
+import { joinLines } from '../config.js';
 import { ListAllowedDirectoriesInputSchema, ListAllowedDirectoriesOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const LIST_ALLOWED_DIRECTORIES_TOOL = {
     name: 'roots',
     title: 'Workspace Roots',
-    description: 'List the workspace roots this server can access. ' +
-        'Call this first to see available directories. ' +
-        'All other tools only work within these directories.',
+    description: 'List allowed workspace roots. Call first \u2014 all other tools are scoped to these directories.',
     inputSchema: ListAllowedDirectoriesInputSchema,
     outputSchema: ListAllowedDirectoriesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
-    nuances: ['Other tools are constrained to these roots.'],
+    nuances: ['Returns absolute paths of all allowed directories.'],
 };
 function buildTextRoots(dirs) {
     if (dirs.length === 0) {