@j0hanz/filesystem-mcp 1.11.1 → 1.13.0

package/dist/tools/edit-file.js

@@ -1,6 +1,6 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { createTwoFilesPatch } from 'diff';
+import { readFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { createTwoFilesPatch, diffLines } from 'diff';
 import RE2 from 're2';
 import { MAX_TEXT_FILE_SIZE } from '../lib/constants.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
@@ -13,7 +13,7 @@ export const EDIT_FILE_TOOL = {
     name: 'edit',
     title: 'Edit File',
     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. ' +
+        '`oldText` must match exactly — include 3–5 lines of context for unique targeting. ' +
         'Use `dryRun:true` to preview.',
     inputSchema: EditFileInputSchema,
     outputSchema: EditFileOutputSchema,
@@ -25,117 +25,203 @@ export const EDIT_FILE_TOOL = {
 function escapeRegExp(string) {
     return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function computeDiffStats(original, modified) {
-    const patch = createTwoFilesPatch('a', 'b', original, modified);
-    let linesAdded = 0;
-    let linesRemoved = 0;
-    for (const line of patch.split('\n')) {
-        if (line.startsWith('+') && !line.startsWith('+++'))
-            linesAdded++;
-        else if (line.startsWith('-') && !line.startsWith('---'))
-            linesRemoved++;
+function getLineNumberAtIndex(str, maxIndex = str.length) {
+    let count = 1;
+    let pos = 0;
+    while (pos < maxIndex) {
+        pos = str.indexOf('\n', pos);
+        if (pos === -1 || pos >= maxIndex)
+            break;
+        count++;
+        pos++;
     }
-    return { linesAdded, linesRemoved };
+    return count;
 }
-function applyEdits(content, edits, ignoreWhitespace) {
-    let newContent = content;
-    let appliedEdits = 0;
-    const unmatchedEdits = [];
-    let minLine;
-    let maxLine;
-    for (const edit of edits) {
-        if (ignoreWhitespace) {
-            const pattern = escapeRegExp(edit.oldText).replace(/\s+/g, '\\s+');
-            const regex = new RE2(pattern);
-            const match = regex.exec(newContent);
-            if (!match) {
-                unmatchedEdits.push(edit.oldText);
-                continue;
-            }
-            const { index } = match;
-            const matchLength = match[0].length;
-            const linesBefore = newContent.slice(0, index).split('\n').length;
-            const newTextLines = edit.newText.split('\n').length;
-            const startLine = linesBefore;
-            const endLine = linesBefore + newTextLines - 1;
-            if (minLine === undefined || startLine < minLine)
-                minLine = startLine;
-            if (maxLine === undefined || endLine > maxLine)
-                maxLine = endLine;
-            newContent =
-                newContent.slice(0, index) +
-                    edit.newText +
-                    newContent.slice(index + matchLength);
-            appliedEdits += 1;
+function countLines(str) {
+    return getLineNumberAtIndex(str);
+}
+async function computeDiffStats(original, modified) {
+    return new Promise((resolve) => {
+        diffLines(original, modified, {
+            callback: (changes) => {
+                let linesAdded = 0;
+                let linesRemoved = 0;
+                for (const part of changes) {
+                    if (part.added) {
+                        linesAdded += part.count;
+                    }
+                    else if (part.removed) {
+                        linesRemoved += part.count;
+                    }
+                }
+                resolve({ linesAdded, linesRemoved });
+            },
+        });
+    });
+}
+function findEditMatch(content, oldText, ignoreWhitespace, regexCache) {
+    if (ignoreWhitespace) {
+        const pattern = escapeRegExp(oldText).replace(/\s+/g, '\\s+');
+        let regex = regexCache?.get(pattern);
+        if (!regex) {
+            regex = new RE2(pattern);
+            if (regexCache)
+                regexCache.set(pattern, regex);
         }
-        else {
-            if (!newContent.includes(edit.oldText)) {
-                unmatchedEdits.push(edit.oldText);
-                continue;
-            }
-            const index = newContent.indexOf(edit.oldText);
-            const linesBefore = newContent.slice(0, index).split('\n').length;
-            const newTextLines = edit.newText.split('\n').length;
-            const startLine = linesBefore;
-            const endLine = linesBefore + newTextLines - 1;
-            if (minLine === undefined || startLine < minLine)
-                minLine = startLine;
-            if (maxLine === undefined || endLine > maxLine)
-                maxLine = endLine;
-            newContent = newContent.replace(edit.oldText, () => edit.newText);
-            appliedEdits += 1;
+        const match = regex.exec(content);
+        if (!match) {
+            return undefined;
         }
+        return {
+            startIndex: match.index,
+            length: match[0].length,
+        };
+    }
+    const index = content.indexOf(oldText);
+    if (index === -1) {
+        return undefined;
+    }
+    return {
+        startIndex: index,
+        length: oldText.length,
+    };
+}
+function replaceEditMatch(content, match, newText) {
+    return (content.slice(0, match.startIndex) +
+        newText +
+        content.slice(match.startIndex + match.length));
+}
+function mergeLineRange(currentRange, content, matchStartIndex, newText) {
+    const startLine = getLineNumberAtIndex(content, matchStartIndex);
+    const endLine = startLine + countLines(newText) - 1;
+    if (!currentRange) {
+        return [startLine, endLine];
     }
+    return [
+        Math.min(currentRange[0], startLine),
+        Math.max(currentRange[1], endLine),
+    ];
+}
+function buildStructuredEditOutput(validPath, result) {
+    return {
+        ok: true,
+        path: validPath,
+        appliedEdits: result.appliedEdits,
+        ...(result.appliedEdits > 0
+            ? {
+                linesAdded: result.linesAdded,
+                linesRemoved: result.linesRemoved,
+            }
+            : {}),
+        ...(result.unmatchedEdits.length > 0
+            ? { unmatchedEdits: result.unmatchedEdits }
+            : {}),
+        ...(result.lineRange ? { lineRange: result.lineRange } : {}),
+    };
+}
+async function finalizeEditResult(originalContent, updatedContent, appliedEdits, unmatchedEdits, lineRange) {
     const { linesAdded, linesRemoved } = appliedEdits > 0
-        ? computeDiffStats(content, newContent)
+        ? await computeDiffStats(originalContent, updatedContent)
         : { linesAdded: 0, linesRemoved: 0 };
-    const result = {
-        content: newContent,
+    return {
+        content: updatedContent,
         appliedEdits,
         unmatchedEdits,
         linesAdded,
         linesRemoved,
+        ...(lineRange ? { lineRange } : {}),
     };
-    if (minLine !== undefined && maxLine !== undefined) {
-        result.lineRange = [minLine, maxLine];
+}
+async function buildDiff(validPath, original, modified) {
+    const fileName = basename(validPath);
+    return new Promise((resolve) => {
+        createTwoFilesPatch(fileName, fileName, original, modified, 'Original', 'Modified', {
+            callback: (res) => {
+                resolve(res ?? '');
+            },
+        });
+    });
+}
+function formatUnmatchedEditsNote(unmatchedEdits) {
+    if (unmatchedEdits.length === 0) {
+        return '';
     }
-    return result;
+    return ` — ${unmatchedEdits.length} unmatched: [${unmatchedEdits
+        .map((text) => JSON.stringify(text.length > 40 ? `${text.slice(0, 40)}…` : text))
+        .join(', ')}]`;
 }
-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);
+function buildEditMessage(requestedPath, result) {
+    const unmatchedNote = formatUnmatchedEditsNote(result.unmatchedEdits);
+    if (result.appliedEdits === 0) {
+        return `No edits applied to ${requestedPath}${unmatchedNote}`;
+    }
+    return `Successfully applied ${result.appliedEdits} edits to ${requestedPath}${unmatchedNote}`;
+}
+async function loadEditableFile(requestedPath, signal) {
+    const validPath = await validateExistingPath(requestedPath, signal);
+    assertAllowedFileAccess(requestedPath, validPath);
+    const stats = await withAbort(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 });
+        throw new McpError(ErrorCode.E_TOO_LARGE, `File too large for edit: ${requestedPath} (${stats.size} bytes > ${MAX_TEXT_FILE_SIZE} bytes)`, requestedPath, { size: stats.size, maxFileSize: MAX_TEXT_FILE_SIZE });
     }
-    const content = await fs.readFile(validPath, { encoding: 'utf-8', signal });
-    const { content: newContent, appliedEdits, unmatchedEdits, linesAdded, linesRemoved, lineRange, } = applyEdits(content, args.edits, args.ignoreWhitespace);
-    const structured = {
-        ok: true,
-        path: validPath,
-        appliedEdits,
-        ...(appliedEdits > 0 ? { linesAdded, linesRemoved } : {}),
-        ...(unmatchedEdits.length > 0 ? { unmatchedEdits } : {}),
-        ...(lineRange ? { lineRange } : {}),
-    };
+    const content = await readFile(validPath, { encoding: 'utf-8', signal });
+    return { validPath, content };
+}
+function buildEditProgressMessage(args) {
+    const name = basename(args.path);
+    const tag = args.dryRun ? ' [dry run]' : '';
+    return `🛠 edit: ${name}${tag}`;
+}
+function buildEditCompletionMessage(args, result) {
+    const name = basename(args.path);
+    if (result.isError)
+        return `🛠 edit: ${name} • failed`;
+    const { structuredContent } = result;
+    if (!structuredContent.ok)
+        return `🛠 edit: ${name} • failed`;
+    const applied = structuredContent.appliedEdits ?? 0;
+    if (applied === 0)
+        return `🛠 edit: ${name} • no changes`;
+    const added = structuredContent.linesAdded ?? 0;
+    const removed = structuredContent.linesRemoved ?? 0;
+    const dry = args.dryRun ? 'dry run ' : '';
+    return `🛠 edit: ${name} • ${dry}+${added} -${removed}`;
+}
+async function applyEdits(content, edits, ignoreWhitespace) {
+    let newContent = content;
+    let appliedEdits = 0;
+    const unmatchedEdits = [];
+    let lineRange;
+    const regexCache = ignoreWhitespace ? new Map() : undefined;
+    for (const edit of edits) {
+        const match = findEditMatch(newContent, edit.oldText, ignoreWhitespace, regexCache);
+        if (!match) {
+            unmatchedEdits.push(edit.oldText);
+            continue;
+        }
+        lineRange = mergeLineRange(lineRange, newContent, match.startIndex, edit.newText);
+        newContent = replaceEditMatch(newContent, match, edit.newText);
+        appliedEdits += 1;
+    }
+    return finalizeEditResult(content, newContent, appliedEdits, unmatchedEdits, lineRange);
+}
+export async function handleEditFile(args, signal) {
+    const { validPath, content } = await loadEditableFile(args.path, signal);
+    const editResult = await applyEdits(content, args.edits, args.ignoreWhitespace);
+    const structured = buildStructuredEditOutput(validPath, editResult);
     if (args.dryRun) {
-        if (appliedEdits > 0) {
-            structured.diff = createTwoFilesPatch(path.basename(validPath), path.basename(validPath), content, newContent, 'Original', 'Modified');
+        if (editResult.appliedEdits > 0) {
+            structured.diff = await buildDiff(validPath, content, editResult.content);
         }
-        return buildToolResponse(`Dry run complete. ${appliedEdits} edits would be applied.`, structured);
+        return buildToolResponse(`Dry run complete. ${editResult.appliedEdits} edits would be applied.`, structured);
     }
-    if (appliedEdits > 0) {
-        await atomicWriteFile(validPath, newContent, { encoding: 'utf-8', signal });
+    if (editResult.appliedEdits > 0) {
+        await atomicWriteFile(validPath, editResult.content, {
+            encoding: 'utf-8',
+            signal,
+        });
     }
-    const unmatchedNote = unmatchedEdits.length > 0
-        ? ` — ${unmatchedEdits.length} unmatched: [${unmatchedEdits
-            .map((s) => JSON.stringify(s.length > 40 ? `${s.slice(0, 40)}\u2026` : s))
-            .join(', ')}]`
-        : '';
-    const message = appliedEdits === 0
-        ? `No edits applied to ${args.path}${unmatchedNote}`
-        : `Successfully applied ${appliedEdits} edits to ${args.path}${unmatchedNote}`;
-    return buildToolResponse(message, structured);
+    return buildToolResponse(buildEditMessage(args.path, editResult), structured);
 }
 export function registerEditFileTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
@@ -148,26 +234,8 @@ export function registerEditFileTool(server, options = {}) {
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => {
-            const name = path.basename(args.path);
-            const tag = args.dryRun ? ' [dry run]' : '';
-            return `🛠 edit: ${name}${tag}`;
-        },
-        completionMessage: (args, result) => {
-            const name = path.basename(args.path);
-            if (result.isError)
-                return `🛠 edit: ${name} • failed`;
-            const sc = result.structuredContent;
-            if (!sc.ok)
-                return `🛠 edit: ${name} • failed`;
-            const applied = sc.appliedEdits ?? 0;
-            if (applied === 0)
-                return `🛠 edit: ${name} • no changes`;
-            const added = sc.linesAdded ?? 0;
-            const removed = sc.linesRemoved ?? 0;
-            const dry = args.dryRun ? 'dry run — ' : '';
-            return `🛠 edit: ${name} • ${dry} +${added} -${removed}`;
-        },
+        progressMessage: buildEditProgressMessage,
+        completionMessage: buildEditCompletionMessage,
     });
     const validatedHandler = withValidatedArgs(EditFileInputSchema, wrappedHandler);
     if (registerToolTaskIfAvailable(server, 'edit', EDIT_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))

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;