@j0hanz/filesystem-mcp 1.11.0 → 1.12.0

package/dist/tools/read-multiple.js

@@ -1,12 +1,15 @@
 import * as path from 'node:path';
-import { DEFAULT_READ_MANY_MAX_TOTAL_SIZE, DEFAULT_SEARCH_TIMEOUT_MS, } from '../lib/constants.js';
+import { DEFAULT_SEARCH_TIMEOUT_MS } from '../lib/constants.js';
 import { ErrorCode } from '../lib/errors.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',
+const READ_MANY_TOOL_NAME = 'read_many';
+const READ_MANY_TOOL_LABEL = '🕮 read_many';
+const FULL_FILE_CONTENTS_DESCRIPTION = 'Full file contents';
+export const READ_MANY_TOOL = {
+    name: READ_MANY_TOOL_NAME,
     title: 'Read Multiple Files',
     description: 'Read multiple text files in one request with contents and metadata. ' +
         'For a single file, use `read`.',
@@ -19,131 +22,152 @@ export const READ_MULTIPLE_FILES_TOOL = {
         'Per-file `truncationReason` can be `head`, `tail`, `range`, or `externalized`.',
     ],
 };
+function buildReadManyResourceName(filePath) {
+    return `read:${path.basename(filePath)}`;
+}
 function toStructuredReadManyResult(result) {
-    const structured = {
+    const structuredResult = {
         path: result.path,
     };
     if (result.content !== undefined)
-        structured.content = result.content;
+        structuredResult.content = result.content;
     if (result.truncated)
-        structured.truncated = result.truncated;
+        structuredResult.truncated = true;
     if (result.resourceUri)
-        structured.resourceUri = result.resourceUri;
+        structuredResult.resourceUri = result.resourceUri;
     if (result.head !== undefined)
-        structured.head = result.head;
+        structuredResult.head = result.head;
     if (result.tail !== undefined)
-        structured.tail = result.tail;
-    if (result.startLine !== undefined)
-        structured.startLine = result.startLine;
+        structuredResult.tail = result.tail;
+    if (result.startLine !== undefined) {
+        structuredResult.startLine = result.startLine;
+    }
     if (result.endLine !== undefined)
-        structured.endLine = result.endLine;
+        structuredResult.endLine = result.endLine;
     if (result.hasMoreLines)
-        structured.hasMoreLines = result.hasMoreLines;
-    if (result.totalLines !== undefined)
-        structured.totalLines = result.totalLines;
-    if (result.linesRead !== undefined)
-        structured.linesRead = result.linesRead;
+        structuredResult.hasMoreLines = true;
+    if (result.totalLines !== undefined) {
+        structuredResult.totalLines = result.totalLines;
+    }
+    if (result.linesRead !== undefined) {
+        structuredResult.linesRead = result.linesRead;
+    }
     if (result.truncationReason) {
-        structured.truncationReason = result.truncationReason;
+        structuredResult.truncationReason = result.truncationReason;
     }
     if (result.error)
-        structured.error = result.error;
-    return structured;
+        structuredResult.error = result.error;
+    return structuredResult;
 }
-async function handleReadMultipleFiles(args, signal, resourceStore, onReadComplete) {
-    const options = {
-        ...(signal ? { signal } : {}),
-        ...(args.head !== undefined ? { head: args.head } : {}),
-        ...(args.tail !== undefined ? { tail: args.tail } : {}),
-        ...(args.startLine !== undefined ? { startLine: args.startLine } : {}),
-        ...(args.endLine !== undefined ? { endLine: args.endLine } : {}),
-        ...(onReadComplete ? { onReadComplete } : {}),
+function resolveReadManyTruncationReason(result) {
+    if (!result.truncated)
+        return undefined;
+    if (result.readMode === 'head')
+        return 'head';
+    if (result.readMode === 'tail')
+        return 'tail';
+    if (result.readMode === 'range')
+        return 'range';
+    return undefined;
+}
+function maybeExternalizeReadManyResult(result, resourceStore) {
+    const truncationReason = resolveReadManyTruncationReason(result);
+    const baseResult = {
+        ...result,
+        ...(truncationReason ? { truncationReason } : {}),
     };
-    const results = await readMultipleFiles(args.paths, options);
-    const maxTotalSize = DEFAULT_READ_MANY_MAX_TOTAL_SIZE;
-    const mappedResults = results.map((result) => {
-        let baseTruncationReason;
-        if (result.truncated && result.readMode === 'head') {
-            baseTruncationReason = 'head';
-        }
-        else if (result.truncated && result.readMode === 'tail') {
-            baseTruncationReason = 'tail';
-        }
-        else if (result.truncated && result.readMode === 'range') {
-            baseTruncationReason = 'range';
-        }
-        const baseResult = {
-            ...result,
-            maxTotalSize,
-            ...(baseTruncationReason
-                ? { truncationReason: baseTruncationReason }
-                : {}),
-        };
-        if (!result.content) {
-            return baseResult;
-        }
-        const externalized = maybeExternalizeTextContent(resourceStore, result.content, { name: `read:${path.basename(result.path)}`, mimeType: 'text/plain' });
-        if (!externalized) {
-            return baseResult;
-        }
-        return {
-            ...baseResult,
-            content: externalized.preview,
-            truncated: true,
-            resourceUri: externalized.entry.uri,
-            truncationReason: 'externalized',
-        };
-    });
+    if (!result.content) {
+        return baseResult;
+    }
+    const externalized = maybeExternalizeTextContent(resourceStore, result.content, { name: buildReadManyResourceName(result.path), mimeType: 'text/plain' });
+    if (!externalized) {
+        return baseResult;
+    }
+    return {
+        ...baseResult,
+        content: externalized.preview,
+        truncated: true,
+        resourceUri: externalized.entry.uri,
+        truncationReason: 'externalized',
+    };
+}
+function buildReadManyTextSection(result) {
+    const header = `=== ${result.path} ===`;
+    if (result.error) {
+        return `${header}\nError: ${result.error}`;
+    }
+    return `${header}\n${result.content ?? ''}`;
+}
+function buildReadMultipleOptions(args, signal, onReadComplete) {
+    const options = {};
+    if (signal)
+        options.signal = signal;
+    if (args.head !== undefined)
+        options.head = args.head;
+    if (args.tail !== undefined)
+        options.tail = args.tail;
+    if (args.startLine !== undefined)
+        options.startLine = args.startLine;
+    if (args.endLine !== undefined)
+        options.endLine = args.endLine;
+    if (onReadComplete)
+        options.onReadComplete = onReadComplete;
+    return options;
+}
+function buildReadManyResponsePayload(results, resourceStore) {
+    const resourceLinks = [];
+    const structuredResults = [];
+    const textSections = [];
     let succeeded = 0;
-    let failed = 0;
-    for (const result of mappedResults) {
-        if (result.error === undefined)
+    for (const result of results) {
+        const mappedResult = maybeExternalizeReadManyResult(result, resourceStore);
+        structuredResults.push(toStructuredReadManyResult(mappedResult));
+        textSections.push(buildReadManyTextSection(mappedResult));
+        if (mappedResult.resourceUri) {
+            resourceLinks.push(buildResourceLink({
+                uri: mappedResult.resourceUri,
+                name: buildReadManyResourceName(mappedResult.path),
+                description: FULL_FILE_CONTENTS_DESCRIPTION,
+            }));
+        }
+        if (mappedResult.error === undefined)
             succeeded += 1;
-        else
-            failed += 1;
     }
-    const structured = {
-        ok: true,
-        results: mappedResults.map((result) => toStructuredReadManyResult(result)),
+    const total = structuredResults.length;
+    return {
+        resourceLinks,
+        structuredResults,
         summary: {
-            total: mappedResults.length,
+            total,
             succeeded,
-            failed,
+            failed: total - succeeded,
         },
+        text: textSections.join('\n\n'),
     };
-    const resourceLinks = [];
-    for (const result of mappedResults) {
-        if (!result.resourceUri)
-            continue;
-        resourceLinks.push(buildResourceLink({
-            uri: result.resourceUri,
-            name: `read:${path.basename(result.path)}`,
-            description: 'Full file contents',
-        }));
-    }
-    const text = mappedResults
-        .map((result) => {
-        const header = `=== ${result.path} ===`;
-        if (result.error) {
-            return `${header}\nError: ${result.error}`;
-        }
-        return `${header}\n${result.content ?? ''}`;
-    })
-        .join('\n\n');
-    return buildToolResponse(text, structured, resourceLinks);
+}
+async function handleReadMultipleFiles(args, signal, resourceStore, onReadComplete) {
+    const options = buildReadMultipleOptions(args, signal, onReadComplete);
+    const results = await readMultipleFiles(args.paths, options);
+    const payload = buildReadManyResponsePayload(results, resourceStore);
+    const structured = {
+        ok: true,
+        results: payload.structuredResults,
+        summary: payload.summary,
+    };
+    return buildToolResponse(payload.text, structured, payload.resourceLinks);
 }
 export function registerReadMultipleFilesTool(server, options = {}) {
     const handler = (args, extra) => {
         const primaryPath = args.paths[0] ?? '';
         return executeToolWithDiagnostics({
-            toolName: 'read_many',
+            toolName: READ_MANY_TOOL_NAME,
             extra,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
             run: async (signal) => {
                 const context = buildBatchPathContext(args.paths, 'files');
                 const { progress, onItemComplete } = createBatchProgressCallbacks(extra, {
-                    toolLabel: '🕮 read_many',
+                    toolLabel: READ_MANY_TOOL_LABEL,
                     context,
                     totalItems: args.paths.length,
                     itemVerb: 'read',
@@ -154,11 +178,11 @@ export function registerReadMultipleFilesTool(server, options = {}) {
                     const suffix = buildBatchCompletionSuffix(sc.summary, 'files read', 'file read');
                     const total = sc.summary?.total ?? 0;
                     const finalCurrent = resolveFinalProgressCurrent(progress, total);
-                    progress.complete(`🕮 read_many: ${context} • ${suffix}`, finalCurrent);
+                    progress.complete(`${READ_MANY_TOOL_LABEL}: ${context} • ${suffix}`, finalCurrent);
                     return result;
                 }
                 catch (error) {
-                    progress.fail(`🕮 read_many: ${context} • failed`);
+                    progress.fail(`${READ_MANY_TOOL_LABEL}: ${context} • failed`);
                     throw error;
                 }
             },
@@ -169,7 +193,7 @@ export function registerReadMultipleFilesTool(server, options = {}) {
         guard: options.isInitialized,
     });
     const validatedHandler = withValidatedArgs(ReadMultipleFilesInputSchema, wrappedHandler);
-    if (registerToolTaskIfAvailable(server, 'read_many', READ_MULTIPLE_FILES_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
+    if (registerToolTaskIfAvailable(server, READ_MANY_TOOL_NAME, READ_MANY_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('read_many', withDefaultIcons({ ...READ_MULTIPLE_FILES_TOOL }, options.iconInfo), validatedHandler);
+    server.registerTool(READ_MANY_TOOL_NAME, withDefaultIcons({ ...READ_MANY_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/read.js

@@ -18,53 +18,63 @@ export const READ_FILE_TOOL = {
     nuances: [
         'Large content is externalized to `filesystem-mcp://result/{id}` and preview is returned inline.',
     ],
-    taskSupport: 'optional',
+    taskSupport: 'forbidden',
 };
-async function handleReadFile(args, signal, resourceStore) {
+const READ_TOOL_NAME = 'read';
+const READ_TOOL_LABEL = '🕮 read';
+const FULL_FILE_CONTENTS_DESCRIPTION = 'Full file contents';
+function buildReadResourceName(filePath) {
+    return `read:${path.basename(filePath)}`;
+}
+function buildReadOptions(args, signal) {
     const options = {
         encoding: 'utf-8',
         maxSize: MAX_TEXT_FILE_SIZE,
         skipBinary: true,
     };
-    if (args.head !== undefined) {
+    if (signal)
+        options.signal = signal;
+    if (args.head !== undefined)
         options.head = args.head;
-    }
-    if (args.tail !== undefined) {
+    if (args.tail !== undefined)
         options.tail = args.tail;
-    }
-    if (args.startLine !== undefined) {
+    if (args.startLine !== undefined)
         options.startLine = args.startLine;
-    }
-    if (args.endLine !== undefined) {
+    if (args.endLine !== undefined)
         options.endLine = args.endLine;
-    }
-    if (signal) {
-        options.signal = signal;
-    }
-    const result = await readFile(args.path, options);
+    return options;
+}
+function toStructuredReadFileResult(args, result) {
     const structured = {
         ok: true,
         path: args.path,
         content: result.content,
-        ...(result.truncated ? { truncated: result.truncated } : {}),
-        ...(result.totalLines !== undefined
-            ? { totalLines: result.totalLines }
-            : {}),
-        ...(result.head !== undefined ? { head: result.head } : {}),
-        ...(result.tail !== undefined ? { tail: result.tail } : {}),
-        ...(result.startLine !== undefined ? { startLine: result.startLine } : {}),
-        ...(result.endLine !== undefined ? { endLine: result.endLine } : {}),
-        ...(result.linesRead !== undefined ? { linesRead: result.linesRead } : {}),
-        ...(result.hasMoreLines ? { hasMoreLines: result.hasMoreLines } : {}),
     };
-    const externalized = maybeExternalizeTextContent(resourceStore, result.content, { name: `read:${path.basename(args.path)}`, mimeType: 'text/plain' });
-    if (args.includeHash) {
-        structured.contentHash = createHash('sha256')
-            .update(result.content, 'utf-8')
-            .digest('hex');
-    }
+    if (result.truncated)
+        structured.truncated = true;
+    if (result.totalLines !== undefined)
+        structured.totalLines = result.totalLines;
+    if (result.head !== undefined)
+        structured.head = result.head;
+    if (result.tail !== undefined)
+        structured.tail = result.tail;
+    if (result.startLine !== undefined)
+        structured.startLine = result.startLine;
+    if (result.endLine !== undefined)
+        structured.endLine = result.endLine;
+    if (result.linesRead !== undefined)
+        structured.linesRead = result.linesRead;
+    if (result.hasMoreLines)
+        structured.hasMoreLines = true;
+    return structured;
+}
+function maybeBuildExternalizedReadResponse(filePath, content, structured, resourceStore) {
+    const externalized = maybeExternalizeTextContent(resourceStore, content, {
+        name: buildReadResourceName(filePath),
+        mimeType: 'text/plain',
+    });
     if (!externalized) {
-        return buildToolResponse(result.content, structured);
+        return undefined;
     }
     const { entry, preview } = externalized;
     const structuredWithResource = {
@@ -74,7 +84,7 @@ async function handleReadFile(args, signal, resourceStore) {
         resourceUri: entry.uri,
     };
     const text = [
-        `Output too large to inline (${result.content.length} chars).`,
+        `Output too large to inline (${content.length} chars).`,
         'Preview:',
         preview,
     ].join('\n');
@@ -83,14 +93,70 @@ async function handleReadFile(args, signal, resourceStore) {
             uri: entry.uri,
             name: entry.name,
             mimeType: entry.mimeType,
-            description: 'Full file contents',
+            description: FULL_FILE_CONTENTS_DESCRIPTION,
             expiresAt: entry.expiresAt,
         }),
     ]);
 }
+function buildReadProgressMessage(args) {
+    const name = path.basename(args.path);
+    if (args.startLine !== undefined) {
+        const end = args.endLine ?? '…';
+        return `${READ_TOOL_LABEL}: ${name} [lines ${args.startLine}–${end}]`;
+    }
+    if (args.head !== undefined)
+        return `${READ_TOOL_LABEL}: ${name} [head ${args.head}]`;
+    if (args.tail !== undefined)
+        return `${READ_TOOL_LABEL}: ${name} [tail ${args.tail}]`;
+    return `${READ_TOOL_LABEL}: ${name}`;
+}
+function buildReadCompletionMessage(args, result) {
+    const name = path.basename(args.path);
+    if (result.isError)
+        return `${READ_TOOL_LABEL}: ${name} • failed`;
+    const structured = result.structuredContent;
+    if (!structured.ok)
+        return `${READ_TOOL_LABEL}: ${name} • failed`;
+    const lines = structured.linesRead ?? structured.totalLines;
+    if (structured.startLine !== undefined) {
+        const end = structured.linesRead
+            ? structured.startLine + structured.linesRead - 1
+            : (structured.endLine ?? '…');
+        return `${READ_TOOL_LABEL}: ${name} • lines ${structured.startLine}–${end}`;
+    }
+    if (structured.head !== undefined) {
+        return structured.hasMoreLines
+            ? `${READ_TOOL_LABEL}: ${name} • first ${String(lines ?? structured.head)} lines`
+            : `${READ_TOOL_LABEL}: ${name} • ${String(lines ?? structured.head)} lines`;
+    }
+    if (structured.tail !== undefined) {
+        return structured.hasMoreLines
+            ? `${READ_TOOL_LABEL}: ${name} • last ${String(lines ?? structured.tail)} lines`
+            : `${READ_TOOL_LABEL}: ${name} • ${String(lines ?? structured.tail)} lines`;
+    }
+    if (structured.truncated) {
+        return `${READ_TOOL_LABEL}: ${name} • truncated [${String(lines)} lines]`;
+    }
+    return `${READ_TOOL_LABEL}: ${name} • ${String(lines)} lines`;
+}
+async function handleReadFile(args, signal, resourceStore) {
+    const options = buildReadOptions(args, signal);
+    const result = await readFile(args.path, options);
+    const structured = toStructuredReadFileResult(args, result);
+    if (args.includeHash) {
+        structured.contentHash = createHash('sha256')
+            .update(result.content, 'utf-8')
+            .digest('hex');
+    }
+    const externalizedResponse = maybeBuildExternalizedReadResponse(args.path, result.content, structured, resourceStore);
+    if (externalizedResponse) {
+        return externalizedResponse;
+    }
+    return buildToolResponse(result.content, structured);
+}
 export function registerReadFileTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
-        toolName: 'read',
+        toolName: READ_TOOL_NAME,
         extra,
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path },
@@ -99,49 +165,11 @@ export function registerReadFileTool(server, options = {}) {
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => {
-            const name = path.basename(args.path);
-            if (args.startLine !== undefined) {
-                const end = args.endLine ?? '…';
-                return `🕮 read: ${name} [lines ${args.startLine}–${end}]`;
-            }
-            if (args.head !== undefined)
-                return `🕮 read: ${name} [head ${args.head}]`;
-            if (args.tail !== undefined)
-                return `🕮 read: ${name} [tail ${args.tail}]`;
-            return `🕮 read: ${name}`;
-        },
-        completionMessage: (args, result) => {
-            const name = path.basename(args.path);
-            if (result.isError)
-                return `🕮 read: ${name} • failed`;
-            const sc = result.structuredContent;
-            if (!sc.ok)
-                return `🕮 read: ${name} • failed`;
-            const lines = sc.linesRead ?? sc.totalLines;
-            if (sc.startLine !== undefined) {
-                const end = sc.linesRead
-                    ? sc.startLine + sc.linesRead - 1
-                    : (sc.endLine ?? '…');
-                return `🕮 read: ${name} • lines ${sc.startLine}–${end}`;
-            }
-            if (sc.head !== undefined) {
-                return sc.hasMoreLines
-                    ? `🕮 read: ${name} • first ${lines ?? sc.head} lines`
-                    : `🕮 read: ${name} • ${lines ?? sc.head} lines`;
-            }
-            if (sc.tail !== undefined) {
-                return sc.hasMoreLines
-                    ? `🕮 read: ${name} • last ${lines ?? sc.tail} lines`
-                    : `🕮 read: ${name} • ${lines ?? sc.tail} lines`;
-            }
-            if (sc.truncated)
-                return `🕮 read: ${name} • truncated [${String(lines)} lines]`;
-            return `🕮 read: ${name} • ${String(lines)} lines`;
-        },
+        progressMessage: buildReadProgressMessage,
+        completionMessage: buildReadCompletionMessage,
     });
     const validatedHandler = withValidatedArgs(ReadFileInputSchema, wrappedHandler);
-    if (registerToolTaskIfAvailable(server, 'read', READ_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
+    if (registerToolTaskIfAvailable(server, READ_TOOL_NAME, READ_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('read', withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), validatedHandler);
+    server.registerTool(READ_TOOL_NAME, withDefaultIcons({ ...READ_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/replace-in-files.d.ts

@@ -3,8 +3,11 @@ import type { z } from 'zod';
 import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema } from '../schemas.js';
 import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const SEARCH_AND_REPLACE_TOOL: ToolContract;
-export declare function handleSearchAndReplace(args: z.infer<typeof SearchAndReplaceInputSchema>, signal?: AbortSignal, onProgress?: (progress: {
+type SearchAndReplaceArgs = z.infer<typeof SearchAndReplaceInputSchema>;
+type SearchAndReplaceOutput = z.infer<typeof SearchAndReplaceOutputSchema>;
+export declare function handleSearchAndReplace(args: SearchAndReplaceArgs, signal?: AbortSignal, onProgress?: (progress: {
     total?: number;
     current: number;
-}) => void): Promise<ToolResponse<z.infer<typeof SearchAndReplaceOutputSchema>>>;
+}) => void): Promise<ToolResponse<SearchAndReplaceOutput>>;
 export declare function registerSearchAndReplaceTool(server: McpServer, options?: ToolRegistrationOptions): void;
+export {};