@baitong-dev/filesystem-mcp 0.0.2

package/descriptions/edit.txt

@@ -0,0 +1,10 @@
+Performs exact string replacements in files.
+
+Usage:
+- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file.
+- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: line number + colon + space (e.g., `1: `). Everything after that space is the actual file content to match. Never include any part of the line number prefix in the oldString or newString.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
+- The edit will FAIL if `oldString` is not found in the file with an error "oldString not found in content".
+- The edit will FAIL if `oldString` is found multiple times in the file with an error "Found multiple matches for oldString. Provide more surrounding lines in oldString to identify the correct match." Either provide a larger string with more surrounding context to make it unique or use `replaceAll` to change every instance of `oldString`.
+- Use `replaceAll` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.

package/descriptions/read.txt

@@ -0,0 +1,13 @@
+Read a file or directory from the local filesystem. If the path does not exist, an error is returned.
+
+Usage:
+- The filePath parameter should be an absolute path.
+- By default, this tool returns up to 2000 lines from the start of the file.
+- The offset parameter is the line number to start from (1-indexed).
+- To read later sections, call this tool again with a larger offset.
+- Use the grep tool to find specific content in large files or files with long lines.
+- If you are unsure of the correct file path, use the glob tool to look up filenames by glob pattern.
+- Contents are returned with each line prefixed by its line number as `<line>: <content>`. For example, if a file has contents "foo\n", you will receive "1: foo\n". For directories, entries are returned one per line (without line numbers) with a trailing `/` for subdirectories.
+- Any line longer than 2000 characters is truncated.
+- Call this tool in parallel when you know there are multiple files you want to read.
+- Avoid tiny repeated slices (30 line chunks). If you need more context, read a larger window.

package/descriptions/write.txt

@@ -0,0 +1,7 @@
+Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.

package/dist/edit.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export type Replacer = (content: string, find: string) => Generator<string, void, unknown>;
+export declare const SimpleReplacer: Replacer;
+export declare const LineTrimmedReplacer: Replacer;
+export declare const BlockAnchorReplacer: Replacer;
+export declare const WhitespaceNormalizedReplacer: Replacer;
+export declare const IndentationFlexibleReplacer: Replacer;
+export declare const EscapeNormalizedReplacer: Replacer;
+export declare const MultiOccurrenceReplacer: Replacer;
+export declare const TrimmedBoundaryReplacer: Replacer;
+export declare const ContextAwareReplacer: Replacer;
+export declare function trimDiff(diff: string): string;
+export declare function replace(content: string, oldString: string, newString: string, replaceAll?: boolean): string;
+export declare function registerEditTool(server: McpServer): void;

package/dist/edit.js

@@ -0,0 +1,591 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContextAwareReplacer = exports.TrimmedBoundaryReplacer = exports.MultiOccurrenceReplacer = exports.EscapeNormalizedReplacer = exports.IndentationFlexibleReplacer = exports.WhitespaceNormalizedReplacer = exports.BlockAnchorReplacer = exports.LineTrimmedReplacer = exports.SimpleReplacer = void 0;
+exports.trimDiff = trimDiff;
+exports.replace = replace;
+exports.registerEditTool = registerEditTool;
+const edit_txt_1 = __importDefault(require("../descriptions/edit.txt"));
+const zod_1 = __importDefault(require("zod"));
+const path_1 = __importDefault(require("path"));
+const mcp_helpers_1 = require("@baitong-dev/mcp-helpers");
+const diff_1 = require("diff");
+// const MAX_DIAGNOSTICS_PER_FILE = 20
+function normalizeLineEndings(text) {
+    return text.replaceAll('\r\n', '\n');
+}
+// Similarity thresholds for block anchor fallback matching
+const SINGLE_CANDIDATE_SIMILARITY_THRESHOLD = 0.0;
+const MULTIPLE_CANDIDATES_SIMILARITY_THRESHOLD = 0.3;
+/**
+ * Levenshtein distance algorithm implementation
+ */
+function levenshtein(a, b) {
+    // Handle empty strings
+    if (a === '' || b === '') {
+        return Math.max(a.length, b.length);
+    }
+    const matrix = Array.from({ length: a.length + 1 }, (_, i) => Array.from({ length: b.length + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0)));
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+        }
+    }
+    return matrix[a.length][b.length];
+}
+const SimpleReplacer = function* (_content, find) {
+    yield find;
+};
+exports.SimpleReplacer = SimpleReplacer;
+const LineTrimmedReplacer = function* (content, find) {
+    const originalLines = content.split('\n');
+    const searchLines = find.split('\n');
+    if (searchLines[searchLines.length - 1] === '') {
+        searchLines.pop();
+    }
+    for (let i = 0; i <= originalLines.length - searchLines.length; i++) {
+        let matches = true;
+        for (let j = 0; j < searchLines.length; j++) {
+            const originalTrimmed = originalLines[i + j].trim();
+            const searchTrimmed = searchLines[j].trim();
+            if (originalTrimmed !== searchTrimmed) {
+                matches = false;
+                break;
+            }
+        }
+        if (matches) {
+            let matchStartIndex = 0;
+            for (let k = 0; k < i; k++) {
+                matchStartIndex += originalLines[k].length + 1;
+            }
+            let matchEndIndex = matchStartIndex;
+            for (let k = 0; k < searchLines.length; k++) {
+                matchEndIndex += originalLines[i + k].length;
+                if (k < searchLines.length - 1) {
+                    matchEndIndex += 1; // Add newline character except for the last line
+                }
+            }
+            yield content.substring(matchStartIndex, matchEndIndex);
+        }
+    }
+};
+exports.LineTrimmedReplacer = LineTrimmedReplacer;
+const BlockAnchorReplacer = function* (content, find) {
+    const originalLines = content.split('\n');
+    const searchLines = find.split('\n');
+    if (searchLines.length < 3) {
+        return;
+    }
+    if (searchLines[searchLines.length - 1] === '') {
+        searchLines.pop();
+    }
+    const firstLineSearch = searchLines[0].trim();
+    const lastLineSearch = searchLines[searchLines.length - 1].trim();
+    const searchBlockSize = searchLines.length;
+    // Collect all candidate positions where both anchors match
+    const candidates = [];
+    for (let i = 0; i < originalLines.length; i++) {
+        if (originalLines[i].trim() !== firstLineSearch) {
+            continue;
+        }
+        // Look for the matching last line after this first line
+        for (let j = i + 2; j < originalLines.length; j++) {
+            if (originalLines[j].trim() === lastLineSearch) {
+                candidates.push({ startLine: i, endLine: j });
+                break; // Only match the first occurrence of the last line
+            }
+        }
+    }
+    // Return immediately if no candidates
+    if (candidates.length === 0) {
+        return;
+    }
+    // Handle single candidate scenario (using relaxed threshold)
+    if (candidates.length === 1) {
+        const { startLine, endLine } = candidates[0];
+        const actualBlockSize = endLine - startLine + 1;
+        let similarity = 0;
+        const linesToCheck = Math.min(searchBlockSize - 2, actualBlockSize - 2); // Middle lines only
+        if (linesToCheck > 0) {
+            for (let j = 1; j < searchBlockSize - 1 && j < actualBlockSize - 1; j++) {
+                const originalLine = originalLines[startLine + j].trim();
+                const searchLine = searchLines[j].trim();
+                const maxLen = Math.max(originalLine.length, searchLine.length);
+                if (maxLen === 0) {
+                    continue;
+                }
+                const distance = levenshtein(originalLine, searchLine);
+                similarity += (1 - distance / maxLen) / linesToCheck;
+                // Exit early when threshold is reached
+                if (similarity >= SINGLE_CANDIDATE_SIMILARITY_THRESHOLD) {
+                    break;
+                }
+            }
+        }
+        else {
+            // No middle lines to compare, just accept based on anchors
+            similarity = 1.0;
+        }
+        if (similarity >= SINGLE_CANDIDATE_SIMILARITY_THRESHOLD) {
+            let matchStartIndex = 0;
+            for (let k = 0; k < startLine; k++) {
+                matchStartIndex += originalLines[k].length + 1;
+            }
+            let matchEndIndex = matchStartIndex;
+            for (let k = startLine; k <= endLine; k++) {
+                matchEndIndex += originalLines[k].length;
+                if (k < endLine) {
+                    matchEndIndex += 1; // Add newline character except for the last line
+                }
+            }
+            yield content.substring(matchStartIndex, matchEndIndex);
+        }
+        return;
+    }
+    // Calculate similarity for multiple candidates
+    let bestMatch = null;
+    let maxSimilarity = -1;
+    for (const candidate of candidates) {
+        const { startLine, endLine } = candidate;
+        const actualBlockSize = endLine - startLine + 1;
+        let similarity = 0;
+        const linesToCheck = Math.min(searchBlockSize - 2, actualBlockSize - 2); // Middle lines only
+        if (linesToCheck > 0) {
+            for (let j = 1; j < searchBlockSize - 1 && j < actualBlockSize - 1; j++) {
+                const originalLine = originalLines[startLine + j].trim();
+                const searchLine = searchLines[j].trim();
+                const maxLen = Math.max(originalLine.length, searchLine.length);
+                if (maxLen === 0) {
+                    continue;
+                }
+                const distance = levenshtein(originalLine, searchLine);
+                similarity += 1 - distance / maxLen;
+            }
+            similarity /= linesToCheck; // Average similarity
+        }
+        else {
+            // No middle lines to compare, just accept based on anchors
+            similarity = 1.0;
+        }
+        if (similarity > maxSimilarity) {
+            maxSimilarity = similarity;
+            bestMatch = candidate;
+        }
+    }
+    // Threshold judgment
+    if (maxSimilarity >= MULTIPLE_CANDIDATES_SIMILARITY_THRESHOLD && bestMatch) {
+        const { startLine, endLine } = bestMatch;
+        let matchStartIndex = 0;
+        for (let k = 0; k < startLine; k++) {
+            matchStartIndex += originalLines[k].length + 1;
+        }
+        let matchEndIndex = matchStartIndex;
+        for (let k = startLine; k <= endLine; k++) {
+            matchEndIndex += originalLines[k].length;
+            if (k < endLine) {
+                matchEndIndex += 1;
+            }
+        }
+        yield content.substring(matchStartIndex, matchEndIndex);
+    }
+};
+exports.BlockAnchorReplacer = BlockAnchorReplacer;
+const WhitespaceNormalizedReplacer = function* (content, find) {
+    const normalizeWhitespace = (text) => text.replace(/\s+/g, ' ').trim();
+    const normalizedFind = normalizeWhitespace(find);
+    // Handle single line matches
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (normalizeWhitespace(line) === normalizedFind) {
+            yield line;
+        }
+        else {
+            // Only check for substring matches if the full line doesn't match
+            const normalizedLine = normalizeWhitespace(line);
+            if (normalizedLine.includes(normalizedFind)) {
+                // Find the actual substring in the original line that matches
+                const words = find.trim().split(/\s+/);
+                if (words.length > 0) {
+                    const pattern = words
+                        .map(word => word.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+                        .join('\\s+');
+                    try {
+                        const regex = new RegExp(pattern);
+                        const match = line.match(regex);
+                        if (match) {
+                            yield match[0];
+                        }
+                    }
+                    catch {
+                        // Invalid regex pattern, skip
+                    }
+                }
+            }
+        }
+    }
+    // Handle multi-line matches
+    const findLines = find.split('\n');
+    if (findLines.length > 1) {
+        for (let i = 0; i <= lines.length - findLines.length; i++) {
+            const block = lines.slice(i, i + findLines.length);
+            if (normalizeWhitespace(block.join('\n')) === normalizedFind) {
+                yield block.join('\n');
+            }
+        }
+    }
+};
+exports.WhitespaceNormalizedReplacer = WhitespaceNormalizedReplacer;
+const IndentationFlexibleReplacer = function* (content, find) {
+    const removeIndentation = (text) => {
+        const lines = text.split('\n');
+        const nonEmptyLines = lines.filter(line => line.trim().length > 0);
+        if (nonEmptyLines.length === 0)
+            return text;
+        const minIndent = Math.min(...nonEmptyLines.map(line => {
+            const match = line.match(/^(\s*)/);
+            return match ? match[1].length : 0;
+        }));
+        return lines.map(line => (line.trim().length === 0 ? line : line.slice(minIndent))).join('\n');
+    };
+    const normalizedFind = removeIndentation(find);
+    const contentLines = content.split('\n');
+    const findLines = find.split('\n');
+    for (let i = 0; i <= contentLines.length - findLines.length; i++) {
+        const block = contentLines.slice(i, i + findLines.length).join('\n');
+        if (removeIndentation(block) === normalizedFind) {
+            yield block;
+        }
+    }
+};
+exports.IndentationFlexibleReplacer = IndentationFlexibleReplacer;
+const EscapeNormalizedReplacer = function* (content, find) {
+    const unescapeString = (str) => {
+        return str.replace(/\\(n|t|r|'|"|`|\\|\n|\$)/g, (match, capturedChar) => {
+            switch (capturedChar) {
+                case 'n':
+                    return '\n';
+                case 't':
+                    return '\t';
+                case 'r':
+                    return '\r';
+                case "'":
+                    return "'";
+                case '"':
+                    return '"';
+                case '`':
+                    return '`';
+                case '\\':
+                    return '\\';
+                case '\n':
+                    return '\n';
+                case '$':
+                    return '$';
+                default:
+                    return match;
+            }
+        });
+    };
+    const unescapedFind = unescapeString(find);
+    // Try direct match with unescaped find string
+    if (content.includes(unescapedFind)) {
+        yield unescapedFind;
+    }
+    // Also try finding escaped versions in content that match unescaped find
+    const lines = content.split('\n');
+    const findLines = unescapedFind.split('\n');
+    for (let i = 0; i <= lines.length - findLines.length; i++) {
+        const block = lines.slice(i, i + findLines.length).join('\n');
+        const unescapedBlock = unescapeString(block);
+        if (unescapedBlock === unescapedFind) {
+            yield block;
+        }
+    }
+};
+exports.EscapeNormalizedReplacer = EscapeNormalizedReplacer;
+const MultiOccurrenceReplacer = function* (content, find) {
+    // This replacer yields all exact matches, allowing the replace function
+    // to handle multiple occurrences based on replaceAll parameter
+    let startIndex = 0;
+    while (true) {
+        const index = content.indexOf(find, startIndex);
+        if (index === -1)
+            break;
+        yield find;
+        startIndex = index + find.length;
+    }
+};
+exports.MultiOccurrenceReplacer = MultiOccurrenceReplacer;
+const TrimmedBoundaryReplacer = function* (content, find) {
+    const trimmedFind = find.trim();
+    if (trimmedFind === find) {
+        // Already trimmed, no point in trying
+        return;
+    }
+    // Try to find the trimmed version
+    if (content.includes(trimmedFind)) {
+        yield trimmedFind;
+    }
+    // Also try finding blocks where trimmed content matches
+    const lines = content.split('\n');
+    const findLines = find.split('\n');
+    for (let i = 0; i <= lines.length - findLines.length; i++) {
+        const block = lines.slice(i, i + findLines.length).join('\n');
+        if (block.trim() === trimmedFind) {
+            yield block;
+        }
+    }
+};
+exports.TrimmedBoundaryReplacer = TrimmedBoundaryReplacer;
+const ContextAwareReplacer = function* (content, find) {
+    const findLines = find.split('\n');
+    if (findLines.length < 3) {
+        // Need at least 3 lines to have meaningful context
+        return;
+    }
+    // Remove trailing empty line if present
+    if (findLines[findLines.length - 1] === '') {
+        findLines.pop();
+    }
+    const contentLines = content.split('\n');
+    // Extract first and last lines as context anchors
+    const firstLine = findLines[0].trim();
+    const lastLine = findLines[findLines.length - 1].trim();
+    // Find blocks that start and end with the context anchors
+    for (let i = 0; i < contentLines.length; i++) {
+        if (contentLines[i].trim() !== firstLine)
+            continue;
+        // Look for the matching last line
+        for (let j = i + 2; j < contentLines.length; j++) {
+            if (contentLines[j].trim() === lastLine) {
+                // Found a potential context block
+                const blockLines = contentLines.slice(i, j + 1);
+                const block = blockLines.join('\n');
+                // Check if the middle content has reasonable similarity
+                // (simple heuristic: at least 50% of non-empty lines should match when trimmed)
+                if (blockLines.length === findLines.length) {
+                    let matchingLines = 0;
+                    let totalNonEmptyLines = 0;
+                    for (let k = 1; k < blockLines.length - 1; k++) {
+                        const blockLine = blockLines[k].trim();
+                        const findLine = findLines[k].trim();
+                        if (blockLine.length > 0 || findLine.length > 0) {
+                            totalNonEmptyLines++;
+                            if (blockLine === findLine) {
+                                matchingLines++;
+                            }
+                        }
+                    }
+                    if (totalNonEmptyLines === 0 || matchingLines / totalNonEmptyLines >= 0.5) {
+                        yield block;
+                        break; // Only match the first occurrence
+                    }
+                }
+                break;
+            }
+        }
+    }
+};
+exports.ContextAwareReplacer = ContextAwareReplacer;
+function trimDiff(diff) {
+    const lines = diff.split('\n');
+    const contentLines = lines.filter(line => (line.startsWith('+') || line.startsWith('-') || line.startsWith(' ')) &&
+        !line.startsWith('---') &&
+        !line.startsWith('+++'));
+    if (contentLines.length === 0)
+        return diff;
+    let min = Infinity;
+    for (const line of contentLines) {
+        const content = line.slice(1);
+        if (content.trim().length > 0) {
+            const match = content.match(/^(\s*)/);
+            if (match)
+                min = Math.min(min, match[1].length);
+        }
+    }
+    if (min === Infinity || min === 0)
+        return diff;
+    const trimmedLines = lines.map(line => {
+        if ((line.startsWith('+') || line.startsWith('-') || line.startsWith(' ')) &&
+            !line.startsWith('---') &&
+            !line.startsWith('+++')) {
+            const prefix = line[0];
+            const content = line.slice(1);
+            return prefix + content.slice(min);
+        }
+        return line;
+    });
+    return trimmedLines.join('\n');
+}
+function replace(content, oldString, newString, replaceAll = false) {
+    if (oldString === newString) {
+        throw new Error('No changes to apply: oldString and newString are identical.');
+    }
+    let notFound = true;
+    for (const replacer of [
+        exports.SimpleReplacer,
+        exports.LineTrimmedReplacer,
+        exports.BlockAnchorReplacer,
+        exports.WhitespaceNormalizedReplacer,
+        exports.IndentationFlexibleReplacer,
+        exports.EscapeNormalizedReplacer,
+        exports.TrimmedBoundaryReplacer,
+        exports.ContextAwareReplacer,
+        exports.MultiOccurrenceReplacer
+    ]) {
+        for (const search of replacer(content, oldString)) {
+            const index = content.indexOf(search);
+            if (index === -1)
+                continue;
+            notFound = false;
+            if (replaceAll) {
+                return content.replaceAll(search, newString);
+            }
+            const lastIndex = content.lastIndexOf(search);
+            if (index !== lastIndex)
+                continue;
+            return content.substring(0, index) + newString + content.substring(index + search.length);
+        }
+    }
+    if (notFound) {
+        throw new Error('Could not find oldString in the file. It must match exactly, including whitespace, indentation, and line endings.');
+    }
+    throw new Error('Found multiple matches for oldString. Provide more surrounding context to make the match unique.');
+}
+function registerEditTool(server) {
+    server.registerTool('edit', {
+        description: edit_txt_1.default,
+        inputSchema: zod_1.default.object({
+            filePath: zod_1.default.string().describe('The absolute path to the file to modify'),
+            oldString: zod_1.default.string().describe('The text to replace'),
+            newString: zod_1.default
+                .string()
+                .describe('The text to replace it with (must be different from oldString)'),
+            replaceAll: zod_1.default
+                .boolean()
+                .optional()
+                .describe('Replace all occurrences of oldString (default false)'),
+            toolInfo: mcp_helpers_1.Tool.Info
+        })
+    }, async (args) => {
+        if (!args.filePath) {
+            throw new Error('filePath is required');
+        }
+        if (args.oldString === args.newString) {
+            throw new Error('No changes to apply: oldString and newString are identical.');
+        }
+        const filePath = path_1.default.isAbsolute(args.filePath)
+            ? args.filePath
+            : path_1.default.join(mcp_helpers_1.MCP_WORKSPACE_DIR, args.filePath);
+        // await assertExternalDirectory(ctx, filePath)
+        let diff = '';
+        let contentOld = '';
+        let contentNew = '';
+        const sessionID = args.toolInfo.sessionId;
+        await mcp_helpers_1.FileTime.withLock(filePath, async () => {
+            if (args.oldString === '') {
+                // const existed = await Filesystem.exists(filePath)
+                contentNew = args.newString;
+                diff = trimDiff((0, diff_1.createTwoFilesPatch)(filePath, filePath, contentOld, contentNew));
+                // await ctx.ask({
+                //   permission: 'edit',
+                //   patterns: [path.relative(Instance.worktree, filePath)],
+                //   always: ['*'],
+                //   metadata: {
+                //     filepath: filePath,
+                //     diff
+                //   }
+                // })
+                await mcp_helpers_1.Filesystem.write(filePath, args.newString);
+                // await Bus.publish(File.Event.Edited, {
+                //   file: filePath
+                // })
+                // await Bus.publish(FileWatcher.Event.Updated, {
+                //   file: filePath,
+                //   event: existed ? 'change' : 'add'
+                // })
+                mcp_helpers_1.FileTime.read(sessionID, filePath);
+                return;
+            }
+            const stats = await mcp_helpers_1.Filesystem.stat(filePath);
+            if (!stats)
+                throw new Error(`File ${filePath} not found`);
+            if (stats.isDirectory())
+                throw new Error(`Path is a directory, not a file: ${filePath}`);
+            await mcp_helpers_1.FileTime.assert(sessionID, filePath);
+            contentOld = await mcp_helpers_1.Filesystem.readText(filePath);
+            contentNew = replace(contentOld, args.oldString, args.newString, args.replaceAll);
+            diff = trimDiff((0, diff_1.createTwoFilesPatch)(filePath, filePath, normalizeLineEndings(contentOld), normalizeLineEndings(contentNew)));
+            // await ctx.ask({
+            //   permission: 'edit',
+            //   patterns: [path.relative(Instance.worktree, filePath)],
+            //   always: ['*'],
+            //   metadata: {
+            //     filepath: filePath,
+            //     diff
+            //   }
+            // })
+            await mcp_helpers_1.Filesystem.write(filePath, contentNew);
+            // await Bus.publish(File.Event.Edited, {
+            //   file: filePath
+            // })
+            // await Bus.publish(FileWatcher.Event.Updated, {
+            //   file: filePath,
+            //   event: 'change'
+            // })
+            contentNew = await mcp_helpers_1.Filesystem.readText(filePath);
+            diff = trimDiff((0, diff_1.createTwoFilesPatch)(filePath, filePath, normalizeLineEndings(contentOld), normalizeLineEndings(contentNew)));
+            mcp_helpers_1.FileTime.read(sessionID, filePath);
+        });
+        const filediff = {
+            file: filePath,
+            before: contentOld,
+            after: contentNew,
+            additions: 0,
+            deletions: 0
+        };
+        for (const change of (0, diff_1.diffLines)(contentOld, contentNew)) {
+            if (change.added)
+                filediff.additions += change.count || 0;
+            if (change.removed)
+                filediff.deletions += change.count || 0;
+        }
+        // ctx.metadata({
+        //   metadata: {
+        //     diff,
+        //     filediff,
+        //     diagnostics: {}
+        //   }
+        // })
+        const output = 'Edit applied successfully.';
+        // await LSP.touchFile(filePath, true)
+        // const diagnostics = await LSP.diagnostics()
+        // const normalizedFilePath = Filesystem.normalizePath(filePath)
+        // const issues = diagnostics[normalizedFilePath] ?? []
+        // const errors = issues.filter(item => item.severity === 1)
+        // if (errors.length > 0) {
+        //   const limited = errors.slice(0, MAX_DIAGNOSTICS_PER_FILE)
+        //   const suffix =
+        //     errors.length > MAX_DIAGNOSTICS_PER_FILE
+        //       ? `\n... and ${errors.length - MAX_DIAGNOSTICS_PER_FILE} more`
+        //       : ''
+        //   output += `\n\nLSP errors detected in this file, please fix:\n<diagnostics file="${filePath}">\n${limited.map(LSP.Diagnostic.pretty).join('\n')}${suffix}\n</diagnostics>`
+        // }
+        const result = {
+            metadata: {
+                // diagnostics,
+                diff,
+                filediff
+            },
+            title: `${path_1.default.relative(mcp_helpers_1.MCP_WORKSPACE_DIR, filePath)}`,
+            output
+        };
+        return {
+            content: [{ type: 'text', text: result.output }],
+            structuredContent: result
+        };
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const edit_1 = require("./edit");
+const read_1 = require("./read");
+const write_1 = require("./write");
+const MCP_NAME = 'Filesystem MCP';
+const MCP_VERSION = '0.0.1';
+const server = new mcp_js_1.McpServer({
+    name: MCP_NAME,
+    version: MCP_VERSION
+}, {
+    capabilities: {
+        logging: {}
+    }
+});
+(0, read_1.registerReadTool)(server);
+(0, edit_1.registerEditTool)(server);
+(0, write_1.registerWriteTool)(server);
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${MCP_NAME} Server v${MCP_VERSION} running`);
+}
+main().catch(error => {
+    console.error('Fatal error in main():', error);
+    process.exit(1);
+});

package/dist/read.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerReadTool(server: McpServer): void;

package/dist/read.js

@@ -0,0 +1,293 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerReadTool = registerReadTool;
+const edit_txt_1 = __importDefault(require("../descriptions/edit.txt"));
+const zod_1 = __importDefault(require("zod"));
+const path_1 = __importDefault(require("path"));
+const mcp_helpers_1 = require("@baitong-dev/mcp-helpers");
+const fs_1 = require("fs");
+const fs = __importStar(require("fs/promises"));
+const readline_1 = require("readline");
+const DEFAULT_READ_LIMIT = 2000;
+const MAX_LINE_LENGTH = 2000;
+const MAX_LINE_SUFFIX = `... (line truncated to ${MAX_LINE_LENGTH} chars)`;
+const MAX_BYTES = 50 * 1024;
+const MAX_BYTES_LABEL = `${MAX_BYTES / 1024} KB`;
+async function isBinaryFile(filepath, fileSize) {
+    const ext = path_1.default.extname(filepath).toLowerCase();
+    // binary check for common non-text extensions
+    switch (ext) {
+        case '.zip':
+        case '.tar':
+        case '.gz':
+        case '.exe':
+        case '.dll':
+        case '.so':
+        case '.class':
+        case '.jar':
+        case '.war':
+        case '.7z':
+        case '.doc':
+        case '.docx':
+        case '.xls':
+        case '.xlsx':
+        case '.ppt':
+        case '.pptx':
+        case '.odt':
+        case '.ods':
+        case '.odp':
+        case '.bin':
+        case '.dat':
+        case '.obj':
+        case '.o':
+        case '.a':
+        case '.lib':
+        case '.wasm':
+        case '.pyc':
+        case '.pyo':
+            return true;
+        default:
+            break;
+    }
+    if (fileSize === 0)
+        return false;
+    const fh = await fs.open(filepath, 'r');
+    try {
+        const sampleSize = Math.min(4096, fileSize);
+        const bytes = Buffer.alloc(sampleSize);
+        const result = await fh.read(bytes, 0, sampleSize, 0);
+        if (result.bytesRead === 0)
+            return false;
+        let nonPrintableCount = 0;
+        for (let i = 0; i < result.bytesRead; i++) {
+            if (bytes[i] === 0)
+                return true;
+            if (bytes[i] < 9 || (bytes[i] > 13 && bytes[i] < 32)) {
+                nonPrintableCount++;
+            }
+        }
+        // If >30% non-printable characters, consider it binary
+        return nonPrintableCount / result.bytesRead > 0.3;
+    }
+    finally {
+        await fh.close();
+    }
+}
+function registerReadTool(server) {
+    server.registerTool('read', {
+        description: edit_txt_1.default,
+        inputSchema: zod_1.default.object({
+            filePath: zod_1.default.string().describe('The absolute path to the file or directory to read'),
+            offset: zod_1.default.coerce
+                .number()
+                .describe('The line number to start reading from (1-indexed)')
+                .optional(),
+            limit: zod_1.default.coerce
+                .number()
+                .describe('The maximum number of lines to read (defaults to 2000)')
+                .optional(),
+            toolInfo: mcp_helpers_1.Tool.Info
+        })
+    }, async (args) => {
+        if (args.offset !== undefined && args.offset < 1) {
+            throw new Error('offset must be greater than or equal to 1');
+        }
+        const sessionID = args.toolInfo.sessionId;
+        let filepath = args.filePath;
+        if (!path_1.default.isAbsolute(filepath)) {
+            filepath = path_1.default.resolve(mcp_helpers_1.MCP_WORKSPACE_DIR, filepath);
+        }
+        const title = path_1.default.relative(mcp_helpers_1.MCP_WORKSPACE_DIR, filepath);
+        const stat = await mcp_helpers_1.Filesystem.stat(filepath);
+        // await assertExternalDirectory(ctx, filepath, {
+        //   bypass: Boolean(ctx.extra?.['bypassCwdCheck']),
+        //   kind: stat?.isDirectory() ? 'directory' : 'file'
+        // })
+        // await ctx.ask({
+        //   permission: 'read',
+        //   patterns: [filepath],
+        //   always: ['*'],
+        //   metadata: {}
+        // })
+        if (!stat) {
+            const dir = path_1.default.dirname(filepath);
+            const base = path_1.default.basename(filepath);
+            const suggestions = await fs
+                .readdir(dir)
+                .then(entries => entries
+                .filter(entry => entry.toLowerCase().includes(base.toLowerCase()) ||
+                base.toLowerCase().includes(entry.toLowerCase()))
+                .map(entry => path_1.default.join(dir, entry))
+                .slice(0, 3))
+                .catch(() => []);
+            if (suggestions.length > 0) {
+                throw new Error(`File not found: ${filepath}\n\nDid you mean one of these?\n${suggestions.join('\n')}`);
+            }
+            throw new Error(`File not found: ${filepath}`);
+        }
+        if (stat.isDirectory()) {
+            const dirents = await fs.readdir(filepath, { withFileTypes: true });
+            const entries = await Promise.all(dirents.map(async (dirent) => {
+                if (dirent.isDirectory())
+                    return dirent.name + '/';
+                if (dirent.isSymbolicLink()) {
+                    const target = await fs.stat(path_1.default.join(filepath, dirent.name)).catch(() => undefined);
+                    if (target?.isDirectory())
+                        return dirent.name + '/';
+                }
+                return dirent.name;
+            }));
+            entries.sort((a, b) => a.localeCompare(b));
+            const limit = args.limit ?? DEFAULT_READ_LIMIT;
+            const offset = args.offset ?? 1;
+            const start = offset - 1;
+            const sliced = entries.slice(start, start + limit);
+            const truncated = start + sliced.length < entries.length;
+            const output = [
+                `<path>${filepath}</path>`,
+                `<type>directory</type>`,
+                `<entries>`,
+                sliced.join('\n'),
+                truncated
+                    ? `\n(Showing ${sliced.length} of ${entries.length} entries. Use 'offset' parameter to read beyond entry ${offset + sliced.length})`
+                    : `\n(${entries.length} entries)`,
+                `</entries>`
+            ].join('\n');
+            const result = {
+                title,
+                output,
+                metadata: {
+                    preview: sliced.slice(0, 20).join('\n'),
+                    truncated,
+                    loaded: []
+                }
+            };
+            return {
+                content: [{ type: 'text', text: result.output }],
+                structuredContent: result
+            };
+        }
+        const isBinary = await isBinaryFile(filepath, Number(stat.size));
+        if (isBinary)
+            throw new Error(`Cannot read binary file: ${filepath}`);
+        const stream = (0, fs_1.createReadStream)(filepath, { encoding: 'utf8' });
+        const rl = (0, readline_1.createInterface)({
+            input: stream,
+            // Note: we use the crlfDelay option to recognize all instances of CR LF
+            // ('\r\n') in file as a single line break.
+            crlfDelay: Infinity
+        });
+        const limit = args.limit ?? DEFAULT_READ_LIMIT;
+        const offset = args.offset ?? 1;
+        const start = offset - 1;
+        const raw = [];
+        let bytes = 0;
+        let lines = 0;
+        let truncatedByBytes = false;
+        let hasMoreLines = false;
+        try {
+            for await (const text of rl) {
+                lines += 1;
+                if (lines <= start)
+                    continue;
+                if (raw.length >= limit) {
+                    hasMoreLines = true;
+                    continue;
+                }
+                const line = text.length > MAX_LINE_LENGTH
+                    ? text.substring(0, MAX_LINE_LENGTH) + MAX_LINE_SUFFIX
+                    : text;
+                const size = Buffer.byteLength(line, 'utf-8') + (raw.length > 0 ? 1 : 0);
+                if (bytes + size > MAX_BYTES) {
+                    truncatedByBytes = true;
+                    hasMoreLines = true;
+                    break;
+                }
+                raw.push(line);
+                bytes += size;
+            }
+        }
+        finally {
+            rl.close();
+            stream.destroy();
+        }
+        if (lines < offset && !(lines === 0 && offset === 1)) {
+            throw new Error(`Offset ${offset} is out of range for this file (${lines} lines)`);
+        }
+        const content = raw.map((line, index) => {
+            return `${index + offset}: ${line}`;
+        });
+        const preview = raw.slice(0, 20).join('\n');
+        let output = [`<path>${filepath}</path>`, `<type>file</type>`, '<content>'].join('\n');
+        output += content.join('\n');
+        const totalLines = lines;
+        const lastReadLine = offset + raw.length - 1;
+        const nextOffset = lastReadLine + 1;
+        const truncated = hasMoreLines || truncatedByBytes;
+        if (truncatedByBytes) {
+            output += `\n\n(Output capped at ${MAX_BYTES_LABEL}. Showing lines ${offset}-${lastReadLine}. Use offset=${nextOffset} to continue.)`;
+        }
+        else if (hasMoreLines) {
+            output += `\n\n(Showing lines ${offset}-${lastReadLine} of ${totalLines}. Use offset=${nextOffset} to continue.)`;
+        }
+        else {
+            output += `\n\n(End of file - total ${totalLines} lines)`;
+        }
+        output += '\n</content>';
+        // just warms the lsp client
+        // LSP.touchFile(filepath, false)
+        mcp_helpers_1.FileTime.read(sessionID, filepath);
+        // if (args.instructions.length > 0) {
+        //   output += `\n\n<system-reminder>\n${args.instructions.map(i => i.content).join('\n\n')}\n</system-reminder>`
+        // }
+        const result = {
+            title,
+            output,
+            metadata: {
+                preview,
+                truncated
+                // loaded: instructions.map(i => i.filepath)
+            }
+        };
+        return {
+            content: [{ type: 'text', text: result.output }],
+            structuredContent: result
+        };
+    });
+}

package/dist/write.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerWriteTool(server: McpServer): void;

package/dist/write.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerWriteTool = registerWriteTool;
+const edit_txt_1 = __importDefault(require("../descriptions/edit.txt"));
+const zod_1 = __importDefault(require("zod"));
+const path_1 = __importDefault(require("path"));
+const mcp_helpers_1 = require("@baitong-dev/mcp-helpers");
+function registerWriteTool(server) {
+    server.registerTool('write', {
+        description: edit_txt_1.default,
+        inputSchema: zod_1.default.object({
+            content: zod_1.default.string().describe('The content to write to the file'),
+            filePath: zod_1.default
+                .string()
+                .describe('The absolute path to the file to write (must be absolute, not relative)'),
+            toolInfo: mcp_helpers_1.Tool.Info
+        })
+    }, async (args) => {
+        const sessionID = args.toolInfo.sessionId;
+        const filepath = path_1.default.isAbsolute(args.filePath)
+            ? args.filePath
+            : path_1.default.join(mcp_helpers_1.MCP_WORKSPACE_DIR, args.filePath);
+        // await assertExternalDirectory(sessionID, filepath)
+        const exists = await mcp_helpers_1.Filesystem.exists(filepath);
+        // const contentOld = exists ? await Filesystem.readText(filepath) : ''
+        if (exists)
+            await mcp_helpers_1.FileTime.assert(sessionID, filepath);
+        // const diff = trimDiff(createTwoFilesPatch(filepath, filepath, contentOld, args.content))
+        // await ctx.ask({
+        //   permission: 'edit',
+        //   patterns: [path.relative(Instance.worktree, filepath)],
+        //   always: ['*'],
+        //   metadata: {
+        //     filepath,
+        //     diff
+        //   }
+        // })
+        await mcp_helpers_1.Filesystem.write(filepath, args.content);
+        // await Bus.publish(File.Event.Edited, {
+        //   file: filepath
+        // })
+        // await Bus.publish(FileWatcher.Event.Updated, {
+        //   file: filepath,
+        //   event: exists ? 'change' : 'add'
+        // })
+        mcp_helpers_1.FileTime.read(sessionID, filepath);
+        const output = 'Wrote file successfully.';
+        // await LSP.touchFile(filepath, true)
+        // const diagnostics = await LSP.diagnostics()
+        // const normalizedFilepath = Filesystem.normalizePath(filepath)
+        // let projectDiagnosticsCount = 0
+        // for (const [file, issues] of Object.entries(diagnostics)) {
+        //   const errors = issues.filter(item => item.severity === 1)
+        //   if (errors.length === 0) continue
+        //   const limited = errors.slice(0, MAX_DIAGNOSTICS_PER_FILE)
+        //   const suffix =
+        //     errors.length > MAX_DIAGNOSTICS_PER_FILE
+        //       ? `\n... and ${errors.length - MAX_DIAGNOSTICS_PER_FILE} more`
+        //       : ''
+        //   if (file === normalizedFilepath) {
+        //     output += `\n\nLSP errors detected in this file, please fix:\n<diagnostics file="${filepath}">\n${limited.map(LSP.Diagnostic.pretty).join('\n')}${suffix}\n</diagnostics>`
+        //     continue
+        //   }
+        //   if (projectDiagnosticsCount >= MAX_PROJECT_DIAGNOSTICS_FILES) continue
+        //   projectDiagnosticsCount++
+        //   output += `\n\nLSP errors detected in other files:\n<diagnostics file="${file}">\n${limited.map(LSP.Diagnostic.pretty).join('\n')}${suffix}\n</diagnostics>`
+        // }
+        const result = {
+            title: path_1.default.relative(mcp_helpers_1.MCP_WORKSPACE_DIR, filepath),
+            metadata: {
+                // diagnostics,
+                filepath,
+                exists: exists
+            },
+            output
+        };
+        return {
+            content: [{ type: 'text', text: result.output }],
+            structuredContent: result
+        };
+    });
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@baitong-dev/filesystem-mcp",
+  "version": "0.0.2",
+  "main": "./dist/index.js",
+  "bin": {
+    "@baitong-dev/filesystem-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "descriptions",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "filesystem",
+    "write",
+    "read",
+    "edit"
+  ],
+  "description": "filesystem-mcp",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "diff": "^8.0.4",
+    "zod": "^4.3.4",
+    "@baitong-dev/mcp-helpers": "0.0.7"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "scripts": {
+    "tsc": "tsc ./src/index.ts  --declaration --module commonjs  --target es2021 --esModuleInterop --outDir ./dist"
+  }
+}