@j0hanz/filesystem-mcp 1.11.1 → 1.12.0

package/dist/tools/list-directory.js

@@ -1,10 +1,11 @@
 import * as path from 'node:path';
-import { DEFAULT_EXCLUDE_PATTERNS } from '../lib/constants.js';
-import { ErrorCode } from '../lib/errors.js';
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_EXCLUDE_PATTERNS, MAX_LIST_ENTRIES, } from '../lib/constants.js';
+import { ErrorCode, McpError } from '../lib/errors.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 { buildToolErrorResponse, buildToolResponse, 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',
@@ -18,6 +19,74 @@ export const LIST_DIRECTORY_TOOL = {
     taskSupport: 'optional',
     nuances: ['`pattern` enables filtered recursive traversal up to `maxDepth`.'],
 };
+const LIST_CURSOR_TTL_MS = parseInt(process.env['FS_CONTEXT_LIST_CURSOR_TTL_MS'] ?? '', 10) ||
+    5 * 60 * 1000;
+const listSnapshots = new Map();
+const listSnapshotTimers = new Map();
+function buildListFingerprint(args) {
+    return JSON.stringify({
+        path: resolvePathOrRoot(args.path),
+        includeHidden: args.includeHidden,
+        includeIgnored: args.includeIgnored,
+        maxDepth: args.maxDepth,
+        sortBy: args.sortBy,
+        pattern: args.pattern,
+        includeSymlinkTargets: args.includeSymlinkTargets,
+    });
+}
+function deleteListSnapshot(snapshotId) {
+    listSnapshots.delete(snapshotId);
+    const timer = listSnapshotTimers.get(snapshotId);
+    if (timer) {
+        clearTimeout(timer);
+        listSnapshotTimers.delete(snapshotId);
+    }
+}
+function storeListSnapshot(snapshot) {
+    const snapshotId = randomUUID();
+    listSnapshots.set(snapshotId, snapshot);
+    const timer = setTimeout(() => {
+        deleteListSnapshot(snapshotId);
+    }, LIST_CURSOR_TTL_MS);
+    if (typeof timer.unref === 'function') {
+        timer.unref();
+    }
+    listSnapshotTimers.set(snapshotId, timer);
+    return snapshotId;
+}
+function encodeListCursor(payload) {
+    return Buffer.from(JSON.stringify(payload)).toString('base64url');
+}
+function decodeListCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            typeof parsed.snapshotId === 'string' &&
+            typeof parsed.offset === 'number') {
+            const payload = parsed;
+            if (payload.snapshotId.length > 0 &&
+                Number.isInteger(payload.offset) &&
+                payload.offset >= 0) {
+                return payload;
+            }
+        }
+    }
+    catch {
+        // fall through to throw
+    }
+    throw new McpError(ErrorCode.E_INVALID_INPUT, 'Invalid cursor: the cursor value is malformed or expired.');
+}
+function resolveNextListCursor(snapshotId, offset, pageSize, totalEntries) {
+    if (!snapshotId)
+        return undefined;
+    const nextOffset = offset + pageSize;
+    if (nextOffset >= totalEntries) {
+        deleteListSnapshot(snapshotId);
+        return undefined;
+    }
+    return encodeListCursor({ snapshotId, offset: nextOffset });
+}
 function buildListTextResult(result, nextCursor) {
     const { entries, summary, path } = result;
     if (entries.length === 0) {
@@ -82,7 +151,6 @@ function buildStructuredListResult(result, nextCursor) {
 }
 async function handleListDirectory(args, signal) {
     const dirPath = resolvePathOrRoot(args.path);
-    const cursorOffset = args.cursor !== undefined ? decodeOffsetCursor(args.cursor) : 0;
     const pageSize = args.maxEntries;
     const options = {
         includeHidden: args.includeHidden,
@@ -90,15 +158,42 @@ async function handleListDirectory(args, signal) {
         sortBy: args.sortBy,
         includeSymlinkTargets: args.includeSymlinkTargets,
         ...(args.maxDepth !== undefined ? { maxDepth: args.maxDepth } : {}),
-        maxEntries: cursorOffset + pageSize,
+        maxEntries: MAX_LIST_ENTRIES,
         ...(args.pattern !== undefined ? { pattern: args.pattern } : {}),
         ...(signal ? { signal } : {}),
     };
-    const result = await listDirectory(dirPath, options);
-    const displayEntries = cursorOffset > 0 ? result.entries.slice(cursorOffset) : result.entries;
-    const nextCursor = result.summary.truncated && displayEntries.length > 0
-        ? encodeOffsetCursor(cursorOffset + displayEntries.length)
-        : undefined;
+    const fingerprint = buildListFingerprint(args);
+    let result;
+    let cursorOffset = 0;
+    let snapshotId;
+    if (args.cursor) {
+        const cursor = decodeListCursor(args.cursor);
+        const snapshot = listSnapshots.get(cursor.snapshotId);
+        if (snapshot?.fingerprint !== fingerprint) {
+            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Invalid cursor: the cursor value is malformed or expired.');
+        }
+        const { offset, snapshotId: storedSnapshotId } = cursor;
+        cursorOffset = offset;
+        snapshotId = storedSnapshotId;
+        result = {
+            path: snapshot.path,
+            entries: snapshot.entries,
+            summary: snapshot.summary,
+        };
+    }
+    else {
+        result = await listDirectory(dirPath, options);
+    }
+    const displayEntries = result.entries.slice(cursorOffset, cursorOffset + pageSize);
+    if (!args.cursor && displayEntries.length < result.entries.length) {
+        snapshotId = storeListSnapshot({
+            path: result.path,
+            entries: result.entries,
+            summary: result.summary,
+            fingerprint,
+        });
+    }
+    const nextCursor = resolveNextListCursor(snapshotId, cursorOffset, displayEntries.length, result.entries.length);
     const displayResult = { ...result, entries: displayEntries };
     return buildToolResponse(buildListTextResult(displayResult, nextCursor), buildStructuredListResult(displayResult, nextCursor));
 }

package/dist/tools/read-multiple.d.ts

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

package/dist/tools/read-multiple.js

@@ -5,8 +5,11 @@ 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,26 +22,42 @@ 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) {
-    return {
+    const structuredResult = {
         path: result.path,
-        ...(result.content !== undefined ? { content: result.content } : {}),
-        ...(result.truncated ? { truncated: result.truncated } : {}),
-        ...(result.resourceUri ? { resourceUri: result.resourceUri } : {}),
-        ...(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.hasMoreLines ? { hasMoreLines: result.hasMoreLines } : {}),
-        ...(result.totalLines !== undefined
-            ? { totalLines: result.totalLines }
-            : {}),
-        ...(result.linesRead !== undefined ? { linesRead: result.linesRead } : {}),
-        ...(result.truncationReason
-            ? { truncationReason: result.truncationReason }
-            : {}),
-        ...(result.error ? { error: result.error } : {}),
     };
+    if (result.content !== undefined)
+        structuredResult.content = result.content;
+    if (result.truncated)
+        structuredResult.truncated = true;
+    if (result.resourceUri)
+        structuredResult.resourceUri = result.resourceUri;
+    if (result.head !== undefined)
+        structuredResult.head = result.head;
+    if (result.tail !== undefined)
+        structuredResult.tail = result.tail;
+    if (result.startLine !== undefined) {
+        structuredResult.startLine = result.startLine;
+    }
+    if (result.endLine !== undefined)
+        structuredResult.endLine = result.endLine;
+    if (result.hasMoreLines)
+        structuredResult.hasMoreLines = true;
+    if (result.totalLines !== undefined) {
+        structuredResult.totalLines = result.totalLines;
+    }
+    if (result.linesRead !== undefined) {
+        structuredResult.linesRead = result.linesRead;
+    }
+    if (result.truncationReason) {
+        structuredResult.truncationReason = result.truncationReason;
+    }
+    if (result.error)
+        structuredResult.error = result.error;
+    return structuredResult;
 }
 function resolveReadManyTruncationReason(result) {
     if (!result.truncated)
@@ -60,7 +79,7 @@ function maybeExternalizeReadManyResult(result, resourceStore) {
     if (!result.content) {
         return baseResult;
     }
-    const externalized = maybeExternalizeTextContent(resourceStore, result.content, { name: `read:${path.basename(result.path)}`, mimeType: 'text/plain' });
+    const externalized = maybeExternalizeTextContent(resourceStore, result.content, { name: buildReadManyResourceName(result.path), mimeType: 'text/plain' });
     if (!externalized) {
         return baseResult;
     }
@@ -72,66 +91,83 @@ function maybeExternalizeReadManyResult(result, resourceStore) {
         truncationReason: 'externalized',
     };
 }
-function buildReadManyResourceLinks(results) {
-    return results.flatMap((result) => {
-        if (!result.resourceUri)
-            return [];
-        return [
-            buildResourceLink({
-                uri: result.resourceUri,
-                name: `read:${path.basename(result.path)}`,
-                description: 'Full file contents',
-            }),
-        ];
-    });
+function buildReadManyTextSection(result) {
+    const header = `=== ${result.path} ===`;
+    if (result.error) {
+        return `${header}\nError: ${result.error}`;
+    }
+    return `${header}\n${result.content ?? ''}`;
 }
-function buildReadManyTextResult(results) {
-    return results
-        .map((result) => {
-        const header = `=== ${result.path} ===`;
-        if (result.error) {
-            return `${header}\nError: ${result.error}`;
+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;
+    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,
+            }));
         }
-        return `${header}\n${result.content ?? ''}`;
-    })
-        .join('\n\n');
+        if (mappedResult.error === undefined)
+            succeeded += 1;
+    }
+    const total = structuredResults.length;
+    return {
+        resourceLinks,
+        structuredResults,
+        summary: {
+            total,
+            succeeded,
+            failed: total - succeeded,
+        },
+        text: textSections.join('\n\n'),
+    };
 }
 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 } : {}),
-    };
+    const options = buildReadMultipleOptions(args, signal, onReadComplete);
     const results = await readMultipleFiles(args.paths, options);
-    const mappedResults = results.map((result) => maybeExternalizeReadManyResult(result, resourceStore));
-    const succeeded = mappedResults.filter((r) => r.error === undefined).length;
-    const failed = mappedResults.length - succeeded;
+    const payload = buildReadManyResponsePayload(results, resourceStore);
     const structured = {
         ok: true,
-        results: mappedResults.map((result) => toStructuredReadManyResult(result)),
-        summary: {
-            total: mappedResults.length,
-            succeeded,
-            failed,
-        },
+        results: payload.structuredResults,
+        summary: payload.summary,
     };
-    return buildToolResponse(buildReadManyTextResult(mappedResults), structured, buildReadManyResourceLinks(mappedResults));
+    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',
@@ -142,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;
                 }
             },
@@ -157,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

@@ -20,51 +20,61 @@ export const READ_FILE_TOOL = {
     ],
     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);
 }