@j0hanz/fs-context-mcp 2.5.0 → 2.6.0

package/README.md

@@ -15,6 +15,7 @@ The `fs-context-mcp` server provides a secure interface for language models to p
 - **Filesystem Navigation**: List directories (`ls`), visualize structures (`tree`), and list allowed roots (`roots`).
 - **File Operations**: Read (`read`, `read_many`), write (`write`), edit (`edit`), move (`mv`), and delete (`rm`) files.
 - **Advanced Search**: Find files by glob pattern (`find`) or search file contents (`grep`) with regex support.
+- **Diff & Patch**: Hash files (`calculate_hash`), generate unified diffs (`diff_files`), apply patches (`apply_patch`), and bulk replace (`search_and_replace`).
 - **Batch Processing**: Efficiently read or stat multiple files in a single request (`read_many`, `stat_many`).
 - **Security**: Operations are strictly confined to allowed directories specified at startup.
 
@@ -82,7 +83,20 @@ The server is configured primarily via command-line arguments.
 
 ### Environment Variables
 
-Missing info. (No explicit environment variables found in configuration handling).
+| Variable                          | Default         | Description                                                             |
+| :-------------------------------- | :-------------- | :---------------------------------------------------------------------- |
+| `MAX_SEARCH_SIZE`                 | `1048576`       | Max file size (bytes) for `grep`/search content. Min 100 KB, max 10 MB. |
+| `MAX_FILE_SIZE`                   | `10485760`      | Max file size (bytes) for `read`/`read_many`. Min 1 MB, max 100 MB.     |
+| `MAX_READ_MANY_TOTAL_SIZE`        | `524288`        | Max total bytes returned by `read_many`. Min 10 KB, max 100 MB.         |
+| `DEFAULT_SEARCH_TIMEOUT`          | `5000`          | Timeout (ms) for search operations. Min 100 ms, max 60 s.               |
+| `FS_CONTEXT_ALLOW_SENSITIVE`      | `false`         | Allow access to sensitive files (set to `1`/`true` to allow).           |
+| `FS_CONTEXT_DENYLIST`             | (empty)         | Additional denylist patterns (comma or newline separated).              |
+| `FS_CONTEXT_ALLOWLIST`            | (empty)         | Allowlist patterns that override the denylist.                          |
+| `FS_CONTEXT_SEARCH_WORKERS`       | `min(cores, 8)` | Worker threads for content search (0-16).                               |
+| `FS_CONTEXT_SEARCH_WORKERS_DEBUG` | `0`             | Log worker debug details when set to `1`.                               |
+| `FS_CONTEXT_DIAGNOSTICS`          | `0`             | Enable diagnostics channels when set to `1`.                            |
+| `FS_CONTEXT_DIAGNOSTICS_DETAIL`   | `0`             | Diagnostics detail level: 0=off, 1=hashed paths, 2=full paths.          |
+| `FS_CONTEXT_TOOL_LOG_ERRORS`      | `0`             | Emit tool error diagnostics when enabled.                               |
 
 ## MCP Surface
 
@@ -178,6 +192,55 @@ Search for text within file contents.
 | `isRegex`       | boolean | No       | `false` | Treat pattern as a regular expression. |
 | `includeHidden` | boolean | No       | `false` | Include hidden files.                  |
 
+#### `calculate_hash`
+
+Compute a SHA-256 hash for a file.
+
+| Parameter | Type   | Required | Default | Description            |
+| :-------- | :----- | :------- | :------ | :--------------------- |
+| `path`    | string | Yes      | -       | Absolute path to file. |
+
+#### `diff_files`
+
+Generate a unified diff between two files.
+
+| Parameter          | Type    | Required | Default | Description                                        |
+| :----------------- | :------ | :------- | :------ | :------------------------------------------------- |
+| `original`         | string  | Yes      | -       | Path to original file.                             |
+| `modified`         | string  | Yes      | -       | Path to modified file.                             |
+| `context`          | number  | No       | -       | Lines of context to include in the diff.           |
+| `ignoreWhitespace` | boolean | No       | `false` | Ignore leading/trailing whitespace in comparisons. |
+| `stripTrailingCr`  | boolean | No       | `false` | Strip trailing carriage returns before diffing.    |
+
+#### `apply_patch`
+
+Apply a unified patch to a file.
+
+| Parameter                | Type    | Required | Default | Description                                    |
+| :----------------------- | :------ | :------- | :------ | :--------------------------------------------- |
+| `path`                   | string  | Yes      | -       | Path to file to patch.                         |
+| `patch`                  | string  | Yes      | -       | Unified diff content.                          |
+| `fuzzy`                  | boolean | No       | `false` | Allow fuzzy patching (compatibility flag).     |
+| `fuzzFactor`             | number  | No       | -       | Maximum fuzzy mismatches per hunk.             |
+| `autoConvertLineEndings` | boolean | No       | `true`  | Auto-convert patch line endings to match file. |
+| `dryRun`                 | boolean | No       | `false` | Check only, no writes.                         |
+
+#### `search_and_replace`
+
+Search and replace text across multiple files.
+
+Response includes `failedFiles` and a sample `failures` list when some files cannot be processed.
+
+| Parameter         | Type    | Required | Default | Description                       |
+| :---------------- | :------ | :------- | :------ | :-------------------------------- |
+| `path`            | string  | No       | (root)  | Base directory for the operation. |
+| `filePattern`     | string  | Yes      | -       | Glob pattern (e.g., `**/*.ts`).   |
+| `excludePatterns` | array   | No       | `[]`    | Glob patterns to exclude.         |
+| `searchPattern`   | string  | Yes      | -       | Text or regex pattern to replace. |
+| `replacement`     | string  | Yes      | -       | Replacement text.                 |
+| `isRegex`         | boolean | No       | `false` | Treat search pattern as regex.    |
+| `dryRun`          | boolean | No       | `false` | Check only, no writes.            |
+
 #### `mkdir`
 
 Create a new directory (recursive).
@@ -231,6 +294,18 @@ Delete a file or directory.
 | `internal://instructions`  | Server Instructions |
 | `fs-context://result/{id}` | Cached Tool Result  |
 
+Tool responses may include a `resource_link` or a `resourceUri` when output is too large to inline. Fetch the full payload with `resources/read` using the provided URI. Cached results are ephemeral and may not appear in `resources/list`.
+
+### Prompts
+
+| Prompt     | Description                                          |
+| :--------- | :--------------------------------------------------- |
+| `get-help` | Returns the server instructions for quick reference. |
+
+### Tasks
+
+Long-running tools (`grep`, `find`, `search_and_replace`) support task-augmented calls. When `task` is provided to `tools/call`, the server returns a task id that can be polled with `tasks/get` and resolved via `tasks/result`. Include `_meta.progressToken` on requests to receive `notifications/progress` updates. Task data is stored in memory and is cleared when the server restarts.
+
 ## Client Configuration Examples
 
 <details>

package/dist/index.js

@@ -14,9 +14,9 @@ async function shutdown(reason, exitCode = 0) {
     shutdownStarted = true;
     process.exitCode = exitCode;
     const timer = setTimeout(() => {
+        console.error(`Shutdown timed out (${reason}), forcing exit.`);
         process.exit(exitCode);
     }, SHUTDOWN_TIMEOUT_MS);
-    timer.unref();
     try {
         if (activeServer) {
             await activeServer.close();

package/dist/instructions.md

@@ -8,7 +8,32 @@ These instructions are available as a resource (internal://instructions) or prom
 
 - Domain: Filesystem operations via an MCP server, enabling LLMs to interact with the filesystem securely and efficiently.
 - Primary Resources: Files, Directories, Search Results, File Metadata.
-- Tools: `ls`, `roots`, `find`, `tree`, `read`, `read_many`, `stat`, `stat_many`, `grep` (READ); `mkdir`, `write`, `edit`, `mv`, `rm` (WRITE).
+- Tools: `ls`, `roots`, `find`, `tree`, `read`, `read_many`, `stat`, `stat_many`, `grep`, `calculate_hash`, `diff_files` (READ); `mkdir`, `write`, `edit`, `mv`, `rm`, `apply_patch`, `search_and_replace` (WRITE).
+
+---
+
+## PROMPTS
+
+- `get-help`: Returns these instructions for quick recall.
+
+---
+
+## RESOURCES & RESOURCE LINKS
+
+- `internal://instructions`: This document.
+- `fs-context://result/{id}`: Cached large output (ephemeral).
+- If a tool response includes a `resourceUri` or `resource_link`, call `resources/read` with the URI to fetch the full payload.
+
+---
+
+## PROGRESS & TASKS
+
+- Include `_meta.progressToken` in requests to receive `notifications/progress` updates for long-running tools.
+- Task-augmented tool calls are supported for `grep`, `find`, and `search_and_replace`:
+  - Send `tools/call` with `task` to get a task id.
+  - Poll `tasks/get` and fetch results via `tasks/result`.
+  - Use `tasks/cancel` to abort.
+  - Task data is stored in memory and cleared on restart.
 
 ---
 
@@ -64,6 +89,28 @@ These instructions are available as a resource (internal://instructions) or prom
 - Input: `path`, `head` (lines), `startLine`/`endLine`.
 - Gotcha: Large files return `resourceUri`; read it or use pagination.
 
+`calculate_hash`
+
+- Purpose: Compute a SHA-256 hash for a file.
+- Input: `path` (file).
+
+`diff_files`
+
+- Purpose: Create a unified diff between two files.
+- Input: `original`, `modified`, optional `context`, `ignoreWhitespace`, `stripTrailingCr`.
+- Gotcha: Large diffs may be returned via `resourceUri`.
+
+`apply_patch`
+
+- Purpose: Apply a unified diff patch to a file.
+- Input: `path`, `patch`, optional `fuzzy`/`fuzzFactor`, `autoConvertLineEndings`, `dryRun`.
+
+`search_and_replace`
+
+- Purpose: Replace text across files matching a glob.
+- Input: `filePattern`, `searchPattern`, `replacement`, optional `isRegex`, `dryRun`.
+- Gotcha: Review `failedFiles` and `failures` for partial errors.
+
 `edit`
 
 - Purpose: Sequential string replacement.
@@ -80,8 +127,3 @@ These instructions are available as a resource (internal://instructions) or prom
 - `E_INVALID_PATTERN`: Fix glob/regex syntax.
 
 ---
-
-## RESOURCES
-
-- `internal://instructions`: This document.
-- `fs-context://result/{id}`: Cached large output (ephemeral).

package/dist/lib/constants.js

@@ -43,7 +43,7 @@ export const PARALLEL_CONCURRENCY = getOptimalParallelism();
 export const MAX_SEARCHABLE_FILE_SIZE = parseEnvInt('MAX_SEARCH_SIZE', 1024 * 1024, 100 * 1024, 10 * 1024 * 1024);
 export const MAX_TEXT_FILE_SIZE = parseEnvInt('MAX_FILE_SIZE', 10 * 1024 * 1024, 1024 * 1024, 100 * 1024 * 1024);
 export const DEFAULT_READ_MANY_MAX_TOTAL_SIZE = parseEnvInt('MAX_READ_MANY_TOTAL_SIZE', 512 * 1024, 10 * 1024, 100 * 1024 * 1024);
-export const DEFAULT_SEARCH_TIMEOUT_MS = parseEnvInt('DEFAULT_SEARCH_TIMEOUT', 30000, 100, 3600000);
+export const DEFAULT_SEARCH_TIMEOUT_MS = parseEnvInt('DEFAULT_SEARCH_TIMEOUT', 5000, 100, 60000);
 const ALLOW_SENSITIVE_FILES = parseEnvBool('FS_CONTEXT_ALLOW_SENSITIVE', false);
 const ENV_DENYLIST = parseEnvList('FS_CONTEXT_DENYLIST');
 const ENV_ALLOWLIST = parseEnvList('FS_CONTEXT_ALLOWLIST');

package/dist/lib/file-operations/search-content.js

@@ -82,10 +82,19 @@ function validatePattern(pattern, options) {
     }
 }
 function buildLiteralMatcher(pattern, options) {
-    // Optimization (RT-001): Use Regex for case-insensitive search to avoid O(N*L) allocations (toLowerCase)
     if (!options.caseSensitive) {
         const final = escapeLiteral(pattern);
-        return buildRegexMatcher(final, false);
+        const regex = new RegExp(final, 'gi');
+        return (line) => {
+            regex.lastIndex = 0;
+            let count = 0;
+            while (regex.exec(line) !== null) {
+                count++;
+                if (regex.lastIndex === 0)
+                    regex.lastIndex++;
+            }
+            return count;
+        };
     }
     // Fast path for case-sensitive literal
     const needle = pattern;
@@ -164,15 +173,26 @@ class ContextBuffer {
     snapshotBefore() {
         if (this.size === 0)
             return [];
+        const result = [];
         if (this.size < this.capacity) {
-            return this.buffer.slice(0, this.size);
+            for (let i = 0; i < this.size; i++) {
+                const item = this.buffer[i];
+                if (item !== undefined)
+                    result.push(item);
+            }
+            return result;
+        }
+        for (let i = this.head; i < this.capacity; i++) {
+            const item = this.buffer[i];
+            if (item !== undefined)
+                result.push(item);
+        }
+        for (let i = 0; i < this.head; i++) {
+            const item = this.buffer[i];
+            if (item !== undefined)
+                result.push(item);
         }
-        // Full buffer: return ordered from oldest to newest
-        // Oldest is at 'head', newest is at 'head - 1'
-        return [
-            ...this.buffer.slice(this.head, this.capacity),
-            ...this.buffer.slice(0, this.head),
-        ];
+        return result;
     }
     scheduleAfter() {
         if (this.capacity === 0)

package/dist/lib/file-operations/search-files.js

@@ -125,6 +125,9 @@ async function collectFromStream(stream, root, gitignoreMatcher, normalized, nee
             continue;
         }
         const entryType = resolveEntryType(entry.dirent);
+        if (!shouldIncludeEntry(entryType, normalized)) {
+            continue;
+        }
         const isAccessible = await isEntryAccessible(entry, entryType, root, signal);
         if (!isAccessible) {
             state.skippedInaccessible++;

package/dist/lib/observability.d.ts

@@ -5,6 +5,12 @@ interface OpsTraceContext {
     path?: string | undefined;
     [key: string]: unknown;
 }
+export interface ToolMetrics {
+    calls: number;
+    errors: number;
+    totalDurationMs: number;
+}
+export declare function getToolMetrics(): Record<string, ToolMetrics>;
 export declare function shouldPublishOpsTrace(): boolean;
 export declare function publishOpsTraceStart(context: OpsTraceContext): void;
 export declare function publishOpsTraceEnd(context: OpsTraceContext): void;

package/dist/lib/observability.js

@@ -22,6 +22,22 @@ function parseDetail(val) {
         return 1;
     return 0;
 }
+const globalMetrics = new Map();
+export function getToolMetrics() {
+    return Object.fromEntries(globalMetrics);
+}
+function updateMetrics(tool, ok, durationMs) {
+    const current = globalMetrics.get(tool) ?? {
+        calls: 0,
+        errors: 0,
+        totalDurationMs: 0,
+    };
+    current.calls++;
+    if (!ok)
+        current.errors++;
+    current.totalDurationMs += durationMs;
+    globalMetrics.set(tool, current);
+}
 // --- Channels & Observability State ---
 const CHANNELS = {
     tool: channel('fs-context:tool'),
@@ -245,6 +261,7 @@ async function runAndObserve(tool, run, pubTool, pubPerf, logErrors, pathVal) {
             publishPerfEnd(tool, durationMs, eluStart, loopMonitor);
         if (pubTool)
             publishToolEnd(tool, ok, durationMs, errorMsg);
+        updateMetrics(tool, ok, durationMs);
         if (logErrors && !ok)
             logError(tool, durationMs, errorMsg);
     }
@@ -276,8 +293,21 @@ export async function withToolDiagnostics(tool, run, options) {
         }
         const pubTool = CHANNELS.tool.hasSubscribers;
         const pubPerf = CHANNELS.perf.hasSubscribers;
-        if (!pubTool && !pubPerf)
-            return await run();
+        if (!pubTool && !pubPerf) {
+            const start = performance.now();
+            try {
+                const res = await run();
+                const duration = performance.now() - start;
+                const { ok } = extractOutcome(res);
+                updateMetrics(tool, ok, duration);
+                return res;
+            }
+            catch (e) {
+                const duration = performance.now() - start;
+                updateMetrics(tool, false, duration);
+                throw e;
+            }
+        }
         return await runAndObserve(tool, run, pubTool, pubPerf, config.logToolErrors, normalizedPath);
     });
 }

package/dist/prompts.d.ts

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

package/dist/prompts.js

@@ -0,0 +1,18 @@
+export function registerGetHelpPrompt(server, instructions) {
+    const description = 'Return the fs-context usage instructions.';
+    server.registerPrompt('get-help', {
+        title: 'Get Help',
+        description,
+    }, () => ({
+        description,
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: instructions,
+                },
+            },
+        ],
+    }));
+}

package/dist/resources.js

@@ -8,6 +8,9 @@ export function registerInstructionResource(server, instructions, iconInfo) {
         title: 'Server Instructions',
         description: 'Guidance for using the fs-context MCP tools effectively.',
         mimeType: 'text/markdown',
+        annotations: {
+            audience: ['assistant'],
+        },
         ...(iconInfo
             ? {
                 icons: [
@@ -33,6 +36,9 @@ export function registerResultResources(server, store, iconInfo) {
         title: 'Cached Tool Result',
         description: 'Ephemeral cached tool output exposed as an MCP resource. Not guaranteed to be listed via resources/list.',
         mimeType: 'text/plain',
+        annotations: {
+            audience: ['assistant'],
+        },
         ...(iconInfo
             ? {
                 icons: [

package/dist/schemas.d.ts

@@ -336,4 +336,82 @@ export declare const DeleteFileOutputSchema: z.ZodObject<{
         suggestion: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+export declare const CalculateHashInputSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strict>;
+export declare const CalculateHashOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    path: z.ZodOptional<z.ZodString>;
+    hash: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const DiffFilesInputSchema: z.ZodObject<{
+    original: z.ZodString;
+    modified: z.ZodString;
+    context: z.ZodOptional<z.ZodNumber>;
+    ignoreWhitespace: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    stripTrailingCr: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strict>;
+export declare const DiffFilesOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    diff: z.ZodOptional<z.ZodString>;
+    truncated: z.ZodOptional<z.ZodBoolean>;
+    resourceUri: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const ApplyPatchInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    patch: z.ZodString;
+    fuzzy: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    fuzzFactor: z.ZodOptional<z.ZodNumber>;
+    autoConvertLineEndings: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strict>;
+export declare const ApplyPatchOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    path: z.ZodOptional<z.ZodString>;
+    applied: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SearchAndReplaceInputSchema: z.ZodObject<{
+    path: z.ZodOptional<z.ZodString>;
+    filePattern: z.ZodString;
+    excludePatterns: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodString>>>;
+    searchPattern: z.ZodString;
+    replacement: z.ZodString;
+    isRegex: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strict>;
+export declare const SearchAndReplaceOutputSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    matches: z.ZodOptional<z.ZodNumber>;
+    filesChanged: z.ZodOptional<z.ZodNumber>;
+    failedFiles: z.ZodOptional<z.ZodNumber>;
+    failures: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strip>>>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        path: z.ZodOptional<z.ZodString>;
+        suggestion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
 export {};