@j0hanz/filesystem-mcp 1.2.3 → 1.3.0

package/dist/tools/list-directory.js

@@ -5,7 +5,8 @@ import { ErrorCode } from '../lib/errors.js';
 import { listDirectory } from '../lib/file-operations/list-directory.js';
 import { ListDirectoryInputSchema, ListDirectoryOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const LIST_DIRECTORY_TOOL = {
+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. ' +
@@ -15,6 +16,7 @@ const LIST_DIRECTORY_TOOL = {
     inputSchema: ListDirectoryInputSchema,
     outputSchema: ListDirectoryOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['`pattern` enables filtered recursive traversal up to `maxDepth`.'],
 };
 function buildListTextResult(result) {
     const { entries, summary, path } = result;
@@ -53,7 +55,7 @@ function buildStructuredListEntry(entry) {
         modified: entry.modified?.toISOString(),
     };
 }
-function buildStructuredListResult(result) {
+function buildStructuredListResult(result, nextCursor) {
     const { entries, summary, path: resultPath } = result;
     const structuredEntries = [];
     for (const entry of entries) {
@@ -71,22 +73,48 @@ function buildStructuredListResult(result) {
         ...(summary.skippedInaccessible
             ? { skippedInaccessible: summary.skippedInaccessible }
             : {}),
+        ...(nextCursor !== undefined ? { nextCursor } : {}),
     };
 }
+function encodeCursor(offset) {
+    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
+}
+function decodeCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.offset === 'number') {
+            const { offset } = parsed;
+            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
+        }
+    }
+    catch {
+        // ignore malformed cursor
+    }
+    return 0;
+}
 async function handleListDirectory(args, signal) {
     const dirPath = resolvePathOrRoot(args.path);
+    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const pageSize = args.maxEntries ?? 20_000;
     const options = {
         includeHidden: args.includeHidden,
         excludePatterns: args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS,
         sortBy: args.sortBy,
         includeSymlinkTargets: args.includeSymlinkTargets,
         ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
-        ...(args.maxEntries !== undefined ? { maxEntries: args.maxEntries } : {}),
+        maxEntries: cursorOffset + pageSize,
         ...(args.pattern !== undefined ? { pattern: args.pattern } : {}),
         ...(signal ? { signal } : {}),
     };
     const result = await listDirectory(dirPath, options);
-    return buildToolResponse(buildListTextResult(result), buildStructuredListResult(result));
+    const displayEntries = cursorOffset > 0 ? result.entries.slice(cursorOffset) : result.entries;
+    const nextCursor = result.summary.truncated && displayEntries.length > 0
+        ? encodeCursor(cursorOffset + displayEntries.length)
+        : undefined;
+    const displayResult = { ...result, entries: displayEntries };
+    return buildToolResponse(buildListTextResult(displayResult), buildStructuredListResult(displayResult, nextCursor));
 }
 export function registerListDirectoryTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
@@ -96,8 +124,7 @@ export function registerListDirectoryTool(server, options = {}) {
         run: (signal) => handleListDirectory(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, args.path ?? '.'),
     });
-    const validatedHandler = withValidatedArgs(ListDirectoryInputSchema, handler);
-    server.registerTool('ls', withDefaultIcons({ ...LIST_DIRECTORY_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             if (args.path) {
@@ -115,5 +142,7 @@ export function registerListDirectoryTool(server, options = {}) {
             const count = sc.totalEntries ?? 0;
             return `≣ ls: ${base} • ${count} ${count === 1 ? 'entry' : 'entries'}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(ListDirectoryInputSchema, wrappedHandler);
+    server.registerTool('ls', withDefaultIcons({ ...LIST_DIRECTORY_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/move-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 MOVE_FILE_TOOL: ToolContract;
 export declare function registerMoveFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/move-file.js

@@ -6,12 +6,14 @@ import { validateExistingPath, validatePathForWrite, } from '../lib/path-validat
 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';
-const MOVE_FILE_TOOL = {
+export const MOVE_FILE_TOOL = {
+    name: 'mv',
     title: 'Move File',
     description: 'Move or rename a file or directory.',
     inputSchema: MoveFileInputSchema,
     outputSchema: MoveFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    nuances: ['Cross-device moves fall back to copy+delete.'],
 };
 async function handleMoveFile(args, signal) {
     const validSource = await validateExistingPath(args.source, signal);
@@ -46,8 +48,7 @@ export function registerMoveFileTool(server, options = {}) {
         run: (signal) => handleMoveFile(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source),
     });
-    const validatedHandler = withValidatedArgs(MoveFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🛠 mv: ${path.basename(args.source)} → ${path.basename(args.destination)}`,
         completionMessage: (args, result) => {
@@ -58,7 +59,8 @@ export function registerMoveFileTool(server, options = {}) {
             return `🛠 mv: ${src} → ${dst} • moved`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'mv', MOVE_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(MoveFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'mv', MOVE_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('mv', withDefaultIcons({ ...MOVE_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('mv', withDefaultIcons({ ...MOVE_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/read-multiple.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 READ_MULTIPLE_FILES_TOOL: ToolContract;
 export declare function registerReadMultipleFilesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/read-multiple.js

@@ -5,7 +5,8 @@ import { readMultipleFiles } from '../lib/file-operations/read-multiple-files.js
 import { ReadMultipleFilesInputSchema, ReadMultipleFilesOutputSchema, } 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';
-const READ_MULTIPLE_FILES_TOOL = {
+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. ' +
@@ -13,6 +14,10 @@ const READ_MULTIPLE_FILES_TOOL = {
     inputSchema: ReadMultipleFilesInputSchema,
     outputSchema: ReadMultipleFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Total read budget is capped by `MAX_READ_MANY_TOTAL_SIZE`.'],
+    gotchas: [
+        'Per-file `truncationReason` can be `head`, `range`, or `externalized`.',
+    ],
 };
 async function handleReadMultipleFiles(args, signal, resourceStore) {
     const options = {
@@ -121,8 +126,7 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, primaryPath),
         });
     };
-    const validatedHandler = withValidatedArgs(ReadMultipleFilesInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const first = path.basename(args.paths[0] ?? '');
@@ -143,7 +147,8 @@ export function registerReadMultipleFilesTool(server, options = {}) {
             return `🕮 read_many: ${total} files read`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(ReadMultipleFilesInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('read_many', withDefaultIcons({ ...READ_MULTIPLE_FILES_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('read_many', withDefaultIcons({ ...READ_MULTIPLE_FILES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/read.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 READ_FILE_TOOL: ToolContract;
 export declare function registerReadFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/read.js

@@ -5,7 +5,8 @@ import { readFile } from '../lib/fs-helpers.js';
 import { ReadFileInputSchema, ReadFileOutputSchema } 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';
-const READ_FILE_TOOL = {
+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. ' +
@@ -13,6 +14,9 @@ const READ_FILE_TOOL = {
     inputSchema: ReadFileInputSchema,
     outputSchema: ReadFileOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: [
+        'Large content is externalized to `filesystem-mcp://result/{id}` and preview is returned inline.',
+    ],
 };
 async function handleReadFile(args, signal, resourceStore) {
     const options = {
@@ -80,8 +84,7 @@ export function registerReadFileTool(server, options = {}) {
         run: (signal) => handleReadFile(args, signal, options.resourceStore),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FILE, args.path),
     });
-    const validatedHandler = withValidatedArgs(ReadFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
@@ -105,7 +108,8 @@ export function registerReadFileTool(server, options = {}) {
             return `🕮 read: ${name} • ${sc.totalLines ?? '?'} lines`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'read', READ_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(ReadFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'read', READ_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('read', withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('read', withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/replace-in-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 SEARCH_AND_REPLACE_TOOL: ToolContract;
 export declare function registerSearchAndReplaceTool(server: McpServer, options?: ToolRegistrationOptions): void;

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

@@ -10,7 +10,8 @@ import { validateExistingPath, validatePathForWrite, } from '../lib/path-validat
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, createProgressReporter, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, notifyProgress, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const SEARCH_AND_REPLACE_TOOL = {
+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). ' +
@@ -20,6 +21,12 @@ const SEARCH_AND_REPLACE_TOOL = {
     inputSchema: SearchAndReplaceInputSchema,
     outputSchema: SearchAndReplaceOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    gotchas: [
+        'Literal mode is default; `isRegex=true` enables RE2 + capture replacements (`$1`, `$2`).',
+    ],
+    nuances: [
+        'Changed-file sample and failure sample are capped/truncated in output.',
+    ],
 };
 const MAX_FAILURES = 20;
 const REPLACE_CONCURRENCY = Math.min(PARALLEL_CONCURRENCY, 8);
@@ -189,8 +196,8 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const entries = globEntries({
         cwd: root,
         pattern: args.filePattern,
-        excludePatterns: DEFAULT_EXCLUDE_PATTERNS,
-        includeHidden: false,
+        excludePatterns: args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS,
+        includeHidden: args.includeHidden ?? false,
         baseNameMatch: false,
         caseSensitiveMatch: true, // Default to sensitive for file paths
         followSymbolicLinks: false,
@@ -279,11 +286,11 @@ export function registerSearchAndReplaceTool(server, options = {}) {
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
     const { isInitialized } = options;
-    const validatedHandler = withValidatedArgs(SearchAndReplaceInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'search_and_replace', SEARCH_AND_REPLACE_TOOL, wrappedHandler, options.iconInfo, isInitialized))
+    const validatedHandler = withValidatedArgs(SearchAndReplaceInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'search_and_replace', SEARCH_AND_REPLACE_TOOL, validatedHandler, options.iconInfo, isInitialized))
         return;
-    server.registerTool('search_and_replace', withDefaultIcons({ ...SEARCH_AND_REPLACE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('search_and_replace', withDefaultIcons({ ...SEARCH_AND_REPLACE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/roots.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_ALLOWED_DIRECTORIES_TOOL: ToolContract;
 export declare function registerListAllowedDirectoriesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/roots.js

@@ -3,7 +3,8 @@ import { ErrorCode } from '../lib/errors.js';
 import { getAllowedDirectories } from '../lib/path-validation.js';
 import { ListAllowedDirectoriesInputSchema, ListAllowedDirectoriesOutputSchema, } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const LIST_ALLOWED_DIRECTORIES_TOOL = {
+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. ' +
@@ -11,6 +12,7 @@ const LIST_ALLOWED_DIRECTORIES_TOOL = {
     inputSchema: ListAllowedDirectoriesInputSchema,
     outputSchema: ListAllowedDirectoriesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Other tools are constrained to these roots.'],
 };
 function buildTextRoots(dirs) {
     if (dirs.length === 0) {
@@ -38,8 +40,7 @@ export function registerListAllowedDirectoriesTool(server, options = {}) {
         run: () => handleListAllowedDirectories(),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN),
     });
-    const validatedHandler = withValidatedArgs(ListAllowedDirectoriesInputSchema, handler);
-    server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: () => '≣ roots',
         completionMessage: (_args, result) => {
@@ -51,5 +52,7 @@ export function registerListAllowedDirectoriesTool(server, options = {}) {
             const count = sc.rootsCount ?? 0;
             return `≣ roots • ${count} ${count === 1 ? 'root' : 'roots'}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(ListAllowedDirectoriesInputSchema, wrappedHandler);
+    server.registerTool('roots', withDefaultIcons({ ...LIST_ALLOWED_DIRECTORIES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/search-content.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 SEARCH_CONTENT_TOOL: ToolContract;
 export declare function registerSearchContentTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/search-content.js

@@ -7,8 +7,9 @@ import { searchContent } from '../lib/file-operations/search-content.js';
 import { SearchContentInputSchema, SearchContentOutputSchema, } from '../schemas.js';
 import { buildResourceLink, buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const MAX_INLINE_MATCHES = 50;
-const SEARCH_CONTENT_TOOL = {
+const MAX_INLINE_MATCHES = parseInt(process.env['FS_CONTEXT_MAX_INLINE_MATCHES'] ?? '', 10) || 50;
+export const SEARCH_CONTENT_TOOL = {
+    name: 'grep',
     title: 'Search Content',
     description: 'Search for text within file contents (grep-like). ' +
         'Returns matching lines. ' +
@@ -18,6 +19,13 @@ const SEARCH_CONTENT_TOOL = {
     inputSchema: SearchContentInputSchema,
     outputSchema: SearchContentOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: [
+        'Inline match rows are capped (first 50); full structured results are externalized via `resourceUri`.',
+        'Skips binary and oversized files.',
+    ],
+    gotchas: [
+        'Inline match rows are capped (first 50); full structured results are externalized via `resourceUri`.',
+    ],
 };
 function assertValidRegexPattern(pattern) {
     try {
@@ -261,11 +269,11 @@ export function registerSearchContentTool(server, options = {}) {
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? '.'),
     });
     const { isInitialized } = options;
-    const validatedHandler = withValidatedArgs(SearchContentInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'grep', SEARCH_CONTENT_TOOL, wrappedHandler, options.iconInfo, isInitialized))
+    const validatedHandler = withValidatedArgs(SearchContentInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'grep', SEARCH_CONTENT_TOOL, validatedHandler, options.iconInfo, isInitialized))
         return;
-    server.registerTool('grep', withDefaultIcons({ ...SEARCH_CONTENT_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('grep', withDefaultIcons({ ...SEARCH_CONTENT_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/search-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 SEARCH_FILES_TOOL: ToolContract;
 export declare function registerSearchFilesTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/search-files.js

@@ -6,7 +6,26 @@ import { searchFiles } from '../lib/file-operations/search-files.js';
 import { SearchFilesInputSchema, SearchFilesOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, createProgressReporter, executeToolWithDiagnostics, notifyProgress, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const SEARCH_FILES_TOOL = {
+function encodeCursor(offset) {
+    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
+}
+function decodeCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.offset === 'number') {
+            const { offset } = parsed;
+            return Number.isInteger(offset) && offset >= 0 ? offset : 0;
+        }
+    }
+    catch {
+        // ignore malformed cursor
+    }
+    return 0;
+}
+export const SEARCH_FILES_TOOL = {
+    name: 'find',
     title: 'Find Files',
     description: 'Find files by glob pattern (e.g., **/*.ts). ' +
         'Returns a list of matching files with metadata. ' +
@@ -15,12 +34,19 @@ const SEARCH_FILES_TOOL = {
     inputSchema: SearchFilesInputSchema,
     outputSchema: SearchFilesOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: [
+        'Respects `.gitignore` unless `includeIgnored=true`.',
+        'Returns relative paths plus metadata; may truncate.',
+    ],
 };
 async function handleSearchFiles(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
     const excludePatterns = args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS;
+    const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
+    const pageSize = args.maxResults;
+    const fetchMax = cursorOffset + pageSize;
     const searchOptions = {
-        maxResults: args.maxResults,
+        maxResults: fetchMax,
         includeHidden: args.includeHidden,
         sortBy: args.sortBy,
         respectGitignore: !args.includeIgnored,
@@ -29,8 +55,13 @@ async function handleSearchFiles(args, signal, onProgress) {
         ...(signal ? { signal } : {}),
     };
     const result = await searchFiles(basePath, args.pattern, excludePatterns, searchOptions);
+    const allResults = result.results;
+    const displayResults = cursorOffset > 0 ? allResults.slice(cursorOffset) : allResults;
+    const nextCursor = result.summary.truncated && displayResults.length > 0
+        ? encodeCursor(cursorOffset + displayResults.length)
+        : undefined;
     const relativeResults = [];
-    for (const entry of result.results) {
+    for (const entry of displayResults) {
         relativeResults.push({
             path: path.relative(result.basePath, entry.path),
             size: entry.size,
@@ -53,6 +84,7 @@ async function handleSearchFiles(args, signal, onProgress) {
         ...(result.summary.stoppedReason
             ? { stoppedReason: result.summary.stoppedReason }
             : {}),
+        ...(nextCursor !== undefined ? { nextCursor } : {}),
     };
     let truncatedReason;
     if (result.summary.truncated) {
@@ -152,11 +184,11 @@ export function registerSearchFilesTool(server, options = {}) {
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
     const { isInitialized } = options;
-    const validatedHandler = withValidatedArgs(SearchFilesInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: isInitialized,
     });
-    if (registerToolTaskIfAvailable(server, 'find', SEARCH_FILES_TOOL, wrappedHandler, options.iconInfo, isInitialized))
+    const validatedHandler = withValidatedArgs(SearchFilesInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'find', SEARCH_FILES_TOOL, validatedHandler, options.iconInfo, isInitialized))
         return;
-    server.registerTool('find', withDefaultIcons({ ...SEARCH_FILES_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('find', withDefaultIcons({ ...SEARCH_FILES_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/shared.d.ts

@@ -4,6 +4,7 @@ import type { FileInfo } from '../config.js';
 import { ErrorCode } from '../lib/errors.js';
 import type { ResourceStore } from '../lib/resource-store.js';
 import type { ToolErrorResponseSchema } from '../schemas.js';
+export { type ToolContract } from './contract.js';
 export declare const READ_ONLY_TOOL_ANNOTATIONS: {
     readonly readOnlyHint: true;
     readonly idempotentHint: true;
@@ -48,7 +49,7 @@ interface ToolErrorResponse extends Record<string, unknown> {
 }
 export type ToolResult<T> = ToolResponse<T> | ToolErrorResponse;
 export declare function parseToolArgs<Schema extends z.ZodType>(schema: Schema, args: unknown): z.infer<Schema>;
-export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>): (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>;
+export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>): (args: unknown, extra: ToolExtra) => Promise<ToolResult<Result>>;
 type ProgressToken = string | number;
 export interface ToolExtra {
     signal?: AbortSignal;
@@ -116,4 +117,3 @@ export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extr
     completionMessage?: (args: Args, result: ToolResult<Result>) => string | undefined;
 }): (args: Args, extra?: ToolExtra) => Promise<ToolResult<Result>>;
 export declare function resolvePathOrRoot(pathValue: string | undefined): string;
-export {};

package/dist/tools/shared.js

@@ -1,12 +1,20 @@
+import { channel } from 'node:diagnostics_channel';
 import { z } from 'zod';
 import { createDetailedError, ErrorCode, formatDetailedError, getSuggestion, McpError, } from '../lib/errors.js';
 import { createTimedAbortSignal } from '../lib/fs-helpers.js';
 import { withToolDiagnostics } from '../lib/observability.js';
 import { getAllowedDirectories } from '../lib/path-validation.js';
-const MAX_INLINE_CONTENT_CHARS = 20_000;
+export {} from './contract.js';
+const MAX_INLINE_CONTENT_CHARS = parseInt(process.env['FS_CONTEXT_MAX_INLINE_CHARS'] ?? '', 10) || 20_000;
 const MAX_INLINE_PREVIEW_CHARS = 4_000;
 const PROGRESS_RATE_LIMIT_MS = 50;
 const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes']);
+const CONTEXT_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:context');
+function publishContextDiagnostics(event) {
+    if (!CONTEXT_DIAGNOSTICS_CHANNEL.hasSubscribers)
+        return;
+    CONTEXT_DIAGNOSTICS_CHANNEL.publish(event);
+}
 export const READ_ONLY_TOOL_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
@@ -61,6 +69,13 @@ export function maybeExternalizeTextContent(resourceStore, content, params) {
         ...(params.mimeType !== undefined ? { mimeType: params.mimeType } : {}),
         text: content,
     });
+    publishContextDiagnostics({
+        phase: 'externalize_text',
+        name: params.name,
+        ...(params.mimeType !== undefined ? { mimeType: params.mimeType } : {}),
+        chars: content.length,
+        uri: entry.uri,
+    });
     return {
         entry,
         preview: buildTextPreview(content),

package/dist/tools/stat-many.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 GET_MULTIPLE_FILE_INFO_TOOL: ToolContract;
 export declare function registerGetMultipleFileInfoTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/stat-many.js

@@ -6,12 +6,14 @@ import { getMultipleFileInfo } from '../lib/file-operations/file-info.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
 import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const GET_MULTIPLE_FILE_INFO_TOOL = {
+export const GET_MULTIPLE_FILE_INFO_TOOL = {
+    name: 'stat_many',
     title: 'Get Multiple File Info',
     description: 'Get metadata for multiple files or directories in one request.',
     inputSchema: GetMultipleFileInfoInputSchema,
     outputSchema: GetMultipleFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetail(info) {
     const lines = [
@@ -73,8 +75,7 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, primaryPath),
         });
     };
-    const validatedHandler = withValidatedArgs(GetMultipleFileInfoInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const first = path.basename(args.paths[0] ?? '');
@@ -95,7 +96,8 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
             return `🕮 stat_many: ${total} OK`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'stat_many', GET_MULTIPLE_FILE_INFO_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(GetMultipleFileInfoInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'stat_many', GET_MULTIPLE_FILE_INFO_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('stat_many', withDefaultIcons({ ...GET_MULTIPLE_FILE_INFO_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('stat_many', withDefaultIcons({ ...GET_MULTIPLE_FILE_INFO_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/stat.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 GET_FILE_INFO_TOOL: ToolContract;
 export declare function registerGetFileInfoTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/stat.js

@@ -5,12 +5,14 @@ import { ErrorCode } from '../lib/errors.js';
 import { getFileInfo } from '../lib/file-operations/file-info.js';
 import { GetFileInfoInputSchema, GetFileInfoOutputSchema } from '../schemas.js';
 import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
-const GET_FILE_INFO_TOOL = {
+export const GET_FILE_INFO_TOOL = {
+    name: 'stat',
     title: 'Get File Info',
     description: 'Get metadata (size, modified time, permissions, mime type) for a file or directory.',
     inputSchema: GetFileInfoInputSchema,
     outputSchema: GetFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetails(info) {
     const lines = [
@@ -45,8 +47,7 @@ export function registerGetFileInfoTool(server, options = {}) {
         run: (signal) => handleGetFileInfo(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_FOUND, args.path),
     });
-    const validatedHandler = withValidatedArgs(GetFileInfoInputSchema, handler);
-    server.registerTool('stat', withDefaultIcons({ ...GET_FILE_INFO_TOOL }, options.iconInfo), wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🕮 stat: ${path.basename(args.path)}`,
         completionMessage: (args, result) => {
@@ -58,5 +59,7 @@ export function registerGetFileInfoTool(server, options = {}) {
                 return `🕮 stat: ${name} • failed`;
             return `🕮 stat: ${sc.info.name} • ${sc.info.type}, ${formatBytes(sc.info.size)}`;
         },
-    }));
+    });
+    const validatedHandler = withValidatedArgs(GetFileInfoInputSchema, wrappedHandler);
+    server.registerTool('stat', withDefaultIcons({ ...GET_FILE_INFO_TOOL }, options.iconInfo), validatedHandler);
 }