@j0hanz/filesystem-mcp 1.6.0 → 1.6.2

package/README.md

@@ -565,6 +565,7 @@ Set `FS_CONTEXT_STRIP_STRUCTURED=1` to strip `structuredContent` from tool resul
 - **Input limits**: Paths are bounded to 4,096 characters; patterns to 1,000 characters.
 - **Atomic writes**: File writes use an atomic write-then-rename strategy to prevent partial writes.
 - **Docker**: The container runs as a non-root user (`mcp`).
+- **HTTP host binding**: The HTTP transport binds to `127.0.0.1` by default. Setting `FILESYSTEM_MCP_HTTP_HOST=0.0.0.0` binds to all network interfaces and exposes the server externally — only do this behind a trusted reverse proxy with `FILESYSTEM_MCP_AUTH_TOKEN` configured.
 
 > [!IMPORTANT]
 > All diagnostic output goes to `stderr`. Tool handlers must never write to `stdout`, as doing so would corrupt the stdio transport.
@@ -623,6 +624,21 @@ The [Glama](https://glama.ai/mcp/servers/j0hanz/filesystem-mcp) listing requires
 docker build -t filesystem-mcp .
 ```
 
+## HTTP Conformance Notes
+
+For Streamable HTTP clients, this server enforces the following behavior:
+
+- Session-bound requests must include `MCP-Protocol-Version: 2025-11-25`; missing or unsupported values return `400`.
+- Requests with invalid or expired `mcp-session-id` return `404`.
+- Initialize requests continue to be accepted without a session ID.
+
+## Backlog Hardening (Planned)
+
+The following hardening items are intentionally tracked as follow-up work:
+
+- Add a TTL-evicting task store for long-lived HTTP deployments to bound memory usage.
+- Add an optional per-session roots isolation mode for multi-tenant HTTP deployments.
+
 ## Troubleshooting
 
 **No directories configured**

package/dist/completions.js

@@ -6,8 +6,18 @@ import { getAllowedDirectories, isPathWithinDirectories, normalizePath, } from '
 import { isRecord } from './lib/type-guards.js';
 const MAX_COMPLETION_ITEMS = 100;
 const COMPLETION_RATE_LIMIT_MS = 100;
-const completionLastCallMs = new Map();
-const completionLastResult = new Map();
+// WeakMap keyed by McpServer instance so that each HTTP session gets isolated
+// rate-limit state. In stdio mode there is a single server; in HTTP mode every
+// session creates its own McpServer, so cross-session cache pollution is avoided.
+const completionState = new WeakMap();
+function getCompletionState(server) {
+    let state = completionState.get(server);
+    if (state === undefined) {
+        state = { lastCallMs: new Map(), lastResult: new Map() };
+        completionState.set(server, state);
+    }
+    return state;
+}
 function extractTopicCompletions(instructions) {
     const headers = [];
     for (const line of instructions.split('\n')) {
@@ -393,9 +403,10 @@ export function registerCompletions(server, instructions = '') {
             return { completion: { values: [], total: 0, hasMore: false } };
         }
         const now = Date.now();
-        const lastCallMs = completionLastCallMs.get(argName) ?? 0;
+        const sessionState = getCompletionState(server);
+        const lastCallMs = sessionState.lastCallMs.get(argName) ?? 0;
         if (now - lastCallMs < COMPLETION_RATE_LIMIT_MS) {
-            const lastResult = completionLastResult.get(argName);
+            const lastResult = sessionState.lastResult.get(argName);
             if (lastResult) {
                 return {
                     completion: {
@@ -407,14 +418,14 @@ export function registerCompletions(server, instructions = '') {
             }
             return { completion: { values: [], total: 0, hasMore: false } };
         }
-        completionLastCallMs.set(argName, now);
+        sessionState.lastCallMs.set(argName, now);
         const contextArguments = extractContextArguments(params.context);
         const { value } = argument;
         const completions = await getPathCompletions(value, {
             argumentName: argName,
             ...(contextArguments ? { contextArguments } : {}),
         });
-        completionLastResult.set(argName, completions);
+        sessionState.lastResult.set(argName, completions);
         return {
             completion: {
                 values: completions.values,

package/dist/lib/constants.d.ts

@@ -1,5 +1,6 @@
 export declare function parseTrueEnvFlag(value: string | undefined): boolean;
 export declare const DEFAULT_LOG_LEVEL: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
+export declare const REQUIRED_MCP_PROTOCOL_VERSION = "2025-11-25";
 export declare const PARALLEL_CONCURRENCY: number;
 export declare const MAX_SEARCHABLE_FILE_SIZE: number;
 export declare const MAX_TEXT_FILE_SIZE: number;

package/dist/lib/constants.js

@@ -69,7 +69,8 @@ function parseEnvLogLevel(envVar, defaultValue) {
     console.error(`[WARNING] Invalid ${envVar} value: ${value} (must be ${VALID_LOG_LEVELS.join('|')}). Using default: ${defaultValue}`);
     return defaultValue;
 }
-export const DEFAULT_LOG_LEVEL = parseEnvLogLevel('FILESYSTEM_MCP_LOG_LEVEL', 'debug');
+export const DEFAULT_LOG_LEVEL = parseEnvLogLevel('FILESYSTEM_MCP_LOG_LEVEL', 'info');
+export const REQUIRED_MCP_PROTOCOL_VERSION = '2025-11-25';
 // Auto-tuned parallelism based on CPU cores (no env override)
 const BYTES_PER_PARALLEL_TASK = 64 * MIB;
 const BYTES_PER_SEARCH_WORKER = 128 * MIB;

package/dist/lib/path-validation.js

@@ -108,7 +108,13 @@ function normalizeAllowedDirectories(dirs) {
     // Preserve first-seen order while deduping.
     return dedupePreserveOrder(normalized);
 }
-// Cached module state (configured roots).
+// Process-global singleton state for allowed directory roots.
+//
+// These are set once at startup (via setAllowedDirectoriesResolved) and
+// mutated only through setAllowedDirectoriesState. In stdio mode there is a
+// single MCP session per process, so this is safe. In HTTP mode all HTTP
+// sessions within the same process share one policy — multi-tenant isolation
+// (different roots per session) requires separate server processes.
 let allowedDirectoriesExpanded = [];
 let allowedDirectoriesPrimary = [];
 function setAllowedDirectoriesState(primary, expanded) {

package/dist/prompts.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
 const HELP_PROMPT_TITLE = 'Get Help';
-const HELP_PROMPT_DESCRIPTION = 'Return the filesystem-mcp usage instructions.';
+const HELP_PROMPT_DESCRIPTION = 'Retrieve the full filesystem-mcp XML usage guide.';
 function filterInstructionsByTopic(instructions, topic) {
     const normalized = topic.trim().toLowerCase();
     if (!normalized)

package/dist/resources/generated-instructions.js

@@ -1,46 +1,44 @@
 import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
 import { buildCoreContextPack, getSharedConstraints, getToolContracts, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
-const INSTRUCTIONS_HEADER = `# FILESYSTEM-MCP
-
-Operate ONLY within allowed roots. Always discover before acting — never guess paths.
-
-## TOOLS
+const INSTRUCTIONS_HEADER = `<role>
+Expert filesystem agent. Operate ONLY within allowed roots. Always discover before acting — never guess paths.
+</role>
 
+<tools_overview>
 | Category | Tools |
 |----------|-------|
 | Navigate | \`roots\`, \`ls\`, \`tree\`, \`find\` |
 | Inspect  | \`stat\`, \`stat_many\`, \`grep\`, \`calculate_hash\` |
 | Read     | \`read\`, \`read_many\`, \`diff_files\` |
 | Write    | \`mkdir\`, \`write\`, \`edit\`, \`mv\`, \`rm\`, \`apply_patch\`, \`search_and_replace\` |
+</tools_overview>
 
-## RESOURCES
-
-- \`filesystem-mcp://result/{id}\`: Large output is cached here. **If a response includes \`resourceUri\`, call \`resources/read\` immediately — results expire on process restart.**
-- \`filesystem-mcp://metrics\`: Live per-tool call/error stats.
-
-## TASK PROTOCOL
+<resources>
+- \`filesystem-mcp://result/{id}\`: Large output cache. Call \`resources/read\` immediately if \`resourceUri\` is returned.
+- \`filesystem-mcp://metrics\`: Live per-tool stats.
+</resources>
 
-Long-running tools support async execution: provide \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, then call \`tasks/result\`.
+<task_protocol>
+Async execution: provide \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, call \`tasks/result\`.
 Task-capable: \`find\`, \`tree\`, \`read\`, \`read_many\`, \`stat_many\`, \`grep\`, \`mkdir\`, \`write\`, \`mv\`, \`rm\`, \`calculate_hash\`, \`apply_patch\`, \`search_and_replace\`.
-
+</task_protocol>
 `;
-const INSTRUCTIONS_FOOTER = `
-## CONSTRAINTS
-
+const INSTRUCTIONS_FOOTER = `<constraints>
 ${getSharedConstraints()
     .map((c) => `- ${c}`)
     .join('\n')}
+</constraints>
 
-## ERROR HANDLING
-
+<error_handling>
 - \`E_ACCESS_DENIED\` → Call \`roots\`; use allowed path.
 - \`E_NOT_FOUND\`     → Call \`ls\`/\`find\`; verify spelling.
 - \`E_TOO_LARGE\`     → Use range/head or \`read_many\`.
 - \`E_TIMEOUT\`       → Reduce scope or result limits.
+</error_handling>
 `;
 function formatToolSection(tool) {
-    const parts = [`${tool.name}: ${tool.description}`];
+    const parts = [`### ${tool.name}\n${tool.description}`];
     if (tool.nuances && tool.nuances.length > 0) {
         parts.push(...tool.nuances.map((n) => `» ${n}`));
     }
@@ -57,13 +55,12 @@ export function buildServerInstructions() {
         '',
         buildToolCatalogDetailsOnly(),
         '',
-        '## TOOL REFERENCE',
-        '',
+        '<tool_reference>',
         toolSections,
+        '</tool_reference>',
         '',
         buildWorkflowGuide(),
         '',
-        '---',
         INSTRUCTIONS_FOOTER,
     ].join('\n');
 }

package/dist/resources/tool-catalog.js

@@ -1,6 +1,5 @@
 import { buildCoreContextPack } from './tool-info.js';
-const CATALOG_GUIDE = `## Tool Selection Guide
-
+const CATALOG_GUIDE = `<tool_selection_guide>
 ## Cross-Tool Data Flow
 
 \`\`\`
@@ -25,6 +24,7 @@ diff_files (patch text) -> apply_patch.patch
 - Always generate a patch with \`diff_files\` first.
 - Always use \`dryRun: true\` with \`apply_patch\` to verify changes.
 - \`apply_patch\` works on unified diff format.
+</tool_selection_guide>
 `;
 export function buildToolCatalog() {
     return `${buildCoreContextPack()}\n\n${CATALOG_GUIDE}`;

package/dist/resources/tool-info.d.ts

@@ -2,3 +2,4 @@ import type { ToolContract } from '../tools/contract.js';
 export declare function getToolContracts(): ToolContract[];
 export declare function buildCoreContextPack(): string;
 export declare function getSharedConstraints(): string[];
+export declare function buildToolInfo(name: string): string | undefined;

package/dist/resources/tool-info.js

@@ -33,7 +33,7 @@ export function buildCoreContextPack() {
         const annotations = e.annotations ? ` ${e.annotations.join(' ')}` : '';
         return `| \`${e.name}\` | ${e.description}${annotations} |`;
     });
-    return `## Core Context Pack\n\n| Tool | Purpose |\n|------|---------|\n${rows.join('\n')}`;
+    return `<core_context>\n| Tool | Purpose |\n|------|---------|\n${rows.join('\n')}\n</core_context>`;
 }
 export function getSharedConstraints() {
     return [
@@ -43,3 +43,25 @@ export function getSharedConstraints() {
         'If a response includes `resourceUri`, call `resources/read` immediately — results expire on process restart.',
     ];
 }
+export function buildToolInfo(name) {
+    const entry = ENTRIES[name];
+    if (!entry)
+        return undefined;
+    const lines = [`## ${entry.name}`, '', entry.description];
+    if (entry.annotations && entry.annotations.length > 0) {
+        lines.push('', `**Annotations:** ${entry.annotations.join(', ')}`);
+    }
+    if (entry.nuances && entry.nuances.length > 0) {
+        lines.push('', '**Nuances:**');
+        for (const nuance of entry.nuances) {
+            lines.push(`- ${nuance}`);
+        }
+    }
+    if (entry.gotchas && entry.gotchas.length > 0) {
+        lines.push('', '**Gotchas:**');
+        for (const gotcha of entry.gotchas) {
+            lines.push(`- ${gotcha}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/resources/workflows.js

@@ -1,6 +1,5 @@
 export function buildWorkflowGuide() {
-    return `## Workflow Reference
-
+    return `<workflows>
 ### A: EXPLORE
 Use when: navigating an unfamiliar directory or reading file content.
 1. \`roots\` (List allowed paths).
@@ -30,5 +29,5 @@ Use when: applying structured diffs produced by \`diff_files\`.
 2. \`apply_patch\` (dryRun: true).
 3. \`apply_patch\` (dryRun: false).
    > **Tip:** Pass \`diff_files\` output directly into \`apply_patch\`.
-`;
+</workflows>`;
 }

package/dist/resources.d.ts

@@ -5,4 +5,5 @@ export declare function registerInstructionResource(server: McpServer, instructi
 export declare function registerToolCatalogResource(server: McpServer, iconInfo?: IconInfo): void;
 export declare function registerWorkflowGuideResource(server: McpServer, iconInfo?: IconInfo): void;
 export declare function registerResultResources(server: McpServer, store: ResourceStore, iconInfo?: IconInfo): void;
+export declare function registerToolInfoResource(server: McpServer, iconInfo?: IconInfo): void;
 export declare function registerMetricsResource(server: McpServer, iconInfo?: IconInfo): void;

package/dist/resources.js

@@ -2,14 +2,26 @@ import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from './lib/errors.js';
 import { globalMetrics } from './lib/observability.js';
 import { buildToolCatalog } from './resources/tool-catalog.js';
+import { buildToolInfo, getToolContracts } from './resources/tool-info.js';
 import { buildWorkflowGuide } from './resources/workflows.js';
 import { withDefaultIcons } from './tools/shared.js';
 const RESULT_TEMPLATE = new ResourceTemplate('filesystem-mcp://result/{id}', {
     list: undefined,
 });
+const TOOL_INFO_TEMPLATE = new ResourceTemplate('internal://tool-info/{name}', {
+    list: () => ({
+        resources: getToolContracts().map((contract) => ({
+            uri: `internal://tool-info/${contract.name}`,
+            name: contract.name,
+            mimeType: 'text/markdown',
+        })),
+    }),
+});
+const TOOL_INFO_RESOURCE_NAME = 'filesystem-mcp-tool-info';
+const TOOL_INFO_RESOURCE_DESCRIPTION = 'Per-tool contract details, nuances, and gotchas. Read internal://tool-info/{name} with a tool name such as "read", "ls", or "grep".';
 const INSTRUCTIONS_RESOURCE_NAME = 'filesystem-mcp-instructions';
 const INSTRUCTIONS_RESOURCE_URI = 'internal://instructions';
-const INSTRUCTIONS_RESOURCE_DESCRIPTION = 'Guidance for using the filesystem-mcp MCP tools effectively.';
+const INSTRUCTIONS_RESOURCE_DESCRIPTION = 'Comprehensive rules and guidelines for filesystem-mcp usage.';
 const RESULT_RESOURCE_NAME = 'filesystem-mcp-result';
 const RESULT_RESOURCE_DESCRIPTION = 'Ephemeral cached tool output exposed as an MCP resource. Not guaranteed to be listed via resources/list.';
 const METRICS_RESOURCE_NAME = 'filesystem-mcp-metrics';
@@ -17,10 +29,10 @@ const METRICS_RESOURCE_URI = 'filesystem-mcp://metrics';
 const METRICS_RESOURCE_DESCRIPTION = 'Live per-tool call/error/avgDurationMs metrics snapshot.';
 const CATALOG_RESOURCE_NAME = 'filesystem-mcp-catalog';
 const CATALOG_RESOURCE_URI = 'internal://tool-catalog';
-const CATALOG_RESOURCE_DESCRIPTION = 'Detailed catalog of tools and their inter-dependencies.';
+const CATALOG_RESOURCE_DESCRIPTION = 'Tool selection guide and data flow map.';
 const WORKFLOW_RESOURCE_NAME = 'filesystem-mcp-workflows';
 const WORKFLOW_RESOURCE_URI = 'internal://workflows';
-const WORKFLOW_RESOURCE_DESCRIPTION = 'Recommended workflows for common tasks.';
+const WORKFLOW_RESOURCE_DESCRIPTION = 'Standard operating procedures for exploration, search, edit, and patch.';
 export function registerInstructionResource(server, instructions, iconInfo) {
     server.registerResource(INSTRUCTIONS_RESOURCE_NAME, INSTRUCTIONS_RESOURCE_URI, withDefaultIcons({
         title: 'Server Instructions',
@@ -104,6 +116,35 @@ export function registerResultResources(server, store, iconInfo) {
         };
     });
 }
+export function registerToolInfoResource(server, iconInfo) {
+    server.registerResource(TOOL_INFO_RESOURCE_NAME, TOOL_INFO_TEMPLATE, withDefaultIcons({
+        title: 'Tool Info',
+        description: TOOL_INFO_RESOURCE_DESCRIPTION,
+        mimeType: 'text/markdown',
+        annotations: {
+            audience: ['assistant'],
+            priority: 0.65,
+        },
+    }, iconInfo), (uri, variables) => {
+        const { name } = variables;
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Tool name is required');
+        }
+        const content = buildToolInfo(name);
+        if (content === undefined) {
+            throw new McpError(ErrorCode.E_INVALID_INPUT, `Tool not found: ${name}`);
+        }
+        return {
+            contents: [
+                {
+                    uri: uri.href,
+                    mimeType: 'text/markdown',
+                    text: content,
+                },
+            ],
+        };
+    });
+}
 export function registerMetricsResource(server, iconInfo) {
     server.registerResource(METRICS_RESOURCE_NAME, METRICS_RESOURCE_URI, withDefaultIcons({
         title: 'Tool Metrics',

package/dist/server/bootstrap.js

@@ -7,12 +7,12 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest, SetLevelRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { registerCompletions } from '../completions.js';
-import { DEFAULT_LOG_LEVEL } from '../lib/constants.js';
+import { DEFAULT_LOG_LEVEL, REQUIRED_MCP_PROTOCOL_VERSION, } from '../lib/constants.js';
 import { formatUnknownErrorMessage } from '../lib/errors.js';
 import { createInMemoryResourceStore } from '../lib/resource-store.js';
 import { pkgInfo } from '../pkg-info.js';
 import { registerGetHelpPrompt } from '../prompts.js';
-import { registerInstructionResource, registerMetricsResource, registerResultResources, registerToolCatalogResource, registerWorkflowGuideResource, } from '../resources.js';
+import { registerInstructionResource, registerMetricsResource, registerResultResources, registerToolCatalogResource, registerToolInfoResource, registerWorkflowGuideResource, } from '../resources.js';
 import { buildServerInstructions } from '../resources/generated-instructions.js';
 import { registerAllTools } from '../tools.js';
 import { withDefaultIcons } from '../tools/shared.js';
@@ -59,6 +59,7 @@ export async function createServer(options = {}) {
         }),
     };
     if (taskToolSupport) {
+        // Enabling task tool support requires configuring a task store and message queue on the server config. We use in-memory implementations which are suitable for short-lived stdio sessions. Long-running HTTP servers should replace these with TTL-evicting implementations to avoid unbounded memory growth.
         serverConfig.taskStore = new InMemoryTaskStore();
         serverConfig.taskMessageQueue = new InMemoryTaskMessageQueue();
     }
@@ -85,6 +86,7 @@ export async function createServer(options = {}) {
     registerInstructionResource(server, serverInstructions, localIcon);
     registerToolCatalogResource(server, localIcon);
     registerWorkflowGuideResource(server, localIcon);
+    registerToolInfoResource(server, localIcon);
     registerGetHelpPrompt(server, serverInstructions, localIcon);
     registerResultResources(server, resourceStore, localIcon);
     registerMetricsResource(server, localIcon);
@@ -167,9 +169,6 @@ async function createHttpSession(options, sessions) {
             sessions.set(sessionId, { server: mcpServer, transport });
             rootsManager.logMissingDirectoriesIfNeeded(mcpServer);
         },
-        onsessionclosed: (sessionId) => {
-            sessions.delete(sessionId);
-        },
     });
     transport.onclose = () => {
         const { sessionId } = transport;
@@ -198,11 +197,40 @@ function isAllowedOrigin(origin) {
         return true; // Non-browser clients omit Origin.
     return LOCALHOST_ORIGIN_RE.test(origin);
 }
+function getProtocolVersionHeader(req) {
+    const rawProtocolVersion = req.headers['mcp-protocol-version'];
+    if (typeof rawProtocolVersion === 'string') {
+        return rawProtocolVersion;
+    }
+    if (Array.isArray(rawProtocolVersion)) {
+        return rawProtocolVersion.find((value) => value === REQUIRED_MCP_PROTOCOL_VERSION);
+    }
+    return undefined;
+}
+function ensureProtocolVersionHeader(req, res) {
+    const protocolVersion = getProtocolVersionHeader(req);
+    if (protocolVersion === REQUIRED_MCP_PROTOCOL_VERSION) {
+        return true;
+    }
+    sendJsonRpcError(res, 400, -32000, 'Bad Request: MCP-Protocol-Version header missing or unsupported');
+    return false;
+}
+function discardRequestBody(req) {
+    req.on('error', () => {
+        // Best effort drain to avoid corrupting keep-alive pipelines.
+    });
+    req.resume();
+}
 export async function startHttpServer(port, options) {
     const sessions = new Map();
     async function handleMcpRequest(req, res) {
         const { method } = req;
-        const sessionId = req.headers['mcp-session-id'];
+        const MAX_SESSION_ID_LENGTH = 256;
+        const rawSessionId = req.headers['mcp-session-id'];
+        const sessionId = typeof rawSessionId === 'string' &&
+            rawSessionId.length <= MAX_SESSION_ID_LENGTH
+            ? rawSessionId
+            : undefined;
         const { origin } = req.headers;
         if (!isAllowedOrigin(origin)) {
             sendJsonRpcError(res, 403, -32000, 'Forbidden: disallowed origin');
@@ -235,33 +263,59 @@ export async function startHttpServer(port, options) {
         }
         try {
             if (method === 'POST') {
-                const body = await readRequestBody(req);
-                if (sessionId && sessions.has(sessionId)) {
+                if (sessionId) {
+                    if (!sessions.has(sessionId)) {
+                        sendJsonRpcError(res, 404, -32000, 'Session not found');
+                        discardRequestBody(req);
+                        return;
+                    }
+                    if (!ensureProtocolVersionHeader(req, res)) {
+                        discardRequestBody(req);
+                        return;
+                    }
+                    const body = await readRequestBody(req);
                     const session = sessions.get(sessionId);
                     if (session) {
                         await session.transport.handleRequest(req, res, body);
                     }
+                    else {
+                        sendJsonRpcError(res, 404, -32000, 'Session not found');
+                    }
+                    return;
                 }
-                else if (!sessionId && isInitializeRequest(body)) {
+                const body = await readRequestBody(req);
+                if (isInitializeRequest(body)) {
+                    const maxSessions = parseInt(process.env['FILESYSTEM_MCP_MAX_HTTP_SESSIONS'] ?? '', 10) || 100;
+                    if (sessions.size >= maxSessions) {
+                        sendJsonRpcError(res, 503, -32000, 'Too many sessions');
+                        return;
+                    }
                     const { transport } = await createHttpSession(options, sessions);
                     await transport.handleRequest(req, res, body);
+                    return;
                 }
-                else if (sessionId) {
-                    sendJsonRpcError(res, 400, -32000, 'Bad Request: Session not found');
-                }
-                else {
-                    sendJsonRpcError(res, 400, -32000, 'Bad Request: No valid session ID provided');
-                }
+                sendJsonRpcError(res, 400, -32000, 'Bad Request: No valid session ID provided');
+                discardRequestBody(req);
             }
             else if (method === 'GET' || method === 'DELETE') {
-                if (!sessionId || !sessions.has(sessionId)) {
-                    sendJsonRpcError(res, 400, -32000, 'Bad Request: Invalid or missing session ID');
+                if (!sessionId) {
+                    sendJsonRpcError(res, 400, -32000, 'Bad Request: Missing session ID');
+                    return;
+                }
+                if (!sessions.has(sessionId)) {
+                    sendJsonRpcError(res, 404, -32000, 'Session not found');
+                    return;
+                }
+                if (!ensureProtocolVersionHeader(req, res)) {
                     return;
                 }
                 const session = sessions.get(sessionId);
                 if (session) {
                     await session.transport.handleRequest(req, res);
                 }
+                else {
+                    sendJsonRpcError(res, 404, -32000, 'Session not found');
+                }
             }
             else {
                 res.writeHead(405, { Allow: 'GET, POST, DELETE' });

package/dist/server/capabilities.js

@@ -5,13 +5,16 @@ function detectTaskToolSupport() {
         return cachedTaskToolSupport;
     }
     try {
+        // Instantiate a minimal, unconnected probe server to duck-type check for
+        // task tool support. The probe has no transport or active connections, so
+        // close() only releases in-memory state; fire-and-forget is safe here.
         const probe = new McpServer({
             name: 'filesystem-mcp-capability-probe',
             version: '0.0.0',
         }, { capabilities: { tools: {} } });
         cachedTaskToolSupport =
             typeof probe.experimental.tasks.registerToolTask === 'function';
-        void probe.close().catch(() => { });
+        probe.close().catch(() => { });
     }
     catch {
         cachedTaskToolSupport = false;
@@ -27,6 +30,11 @@ export function buildServerCapabilities(options = {}) {
         completions: {},
     };
     if (options.enableTaskToolRequests) {
+        // NOTE: enabling task tool requests requires the caller to configure
+        // an InMemoryTaskStore and InMemoryTaskMessageQueue on the McpServer.
+        // InMemoryTaskStore accumulates completed task records with no TTL eviction —
+        // suitable for short-lived stdio sessions. Long-running HTTP servers should
+        // replace it with a TTL-evicting store to avoid unbounded memory growth.
         capabilities.tasks = {
             list: {},
             cancel: {},

package/dist/server/roots-manager.d.ts

@@ -5,6 +5,8 @@ export declare class RootsManager {
     private rootsUpdateTimeout;
     private rootDirectories;
     private clientInitialized;
+    private updatingRoots;
+    private pendingRootsUpdate;
     private readonly options;
     readonly loggingState: LoggingState;
     constructor(options: ServerOptions, loggingState: LoggingState);

package/dist/server/roots-manager.js

@@ -84,6 +84,10 @@ export class RootsManager {
     rootsUpdateTimeout;
     rootDirectories = [];
     clientInitialized = false;
+    // Set to true when an update is in progress, to prevent concurrent executions. If a change arrives while true, we queue a single retry after completion to ensure the last-known state is applied. This
+    updatingRoots = false;
+    // If an update is in progress and a change arrives, we set this flag to ensure we run another update after completion to apply the latest state
+    pendingRootsUpdate = false;
     options;
     loggingState;
     constructor(options, loggingState) {
@@ -151,23 +155,37 @@ export class RootsManager {
         logToMcp(server, 'warning', 'No allowed directories specified. Please provide directories as command-line arguments or enable --allow-cwd to use the current working directory.', this.loggingState.minimumLevel);
     }
     async updateRootsFromClient(server) {
+        // Guard against concurrent executions: if one is already running, queue a
+        // single retry so the last-known state is always applied after completion.
+        if (this.updatingRoots) {
+            this.pendingRootsUpdate = true;
+            return;
+        }
+        this.updatingRoots = true;
         try {
             const clientCapabilities = server.server.getClientCapabilities();
             if (!clientCapabilities?.roots) {
                 this.rootDirectories = [];
-                return;
             }
-            const rootsResult = await server.server.listRoots(undefined, {
-                timeout: ROOTS_TIMEOUT_MS,
-            });
-            const roots = extractRoots(rootsResult);
-            this.rootDirectories = await resolveRootDirectories(roots);
+            else {
+                const rootsResult = await server.server.listRoots(undefined, {
+                    timeout: ROOTS_TIMEOUT_MS,
+                });
+                const roots = extractRoots(rootsResult);
+                this.rootDirectories = await resolveRootDirectories(roots);
+            }
         }
         catch (error) {
             logToMcp(server, 'debug', `[DEBUG] MCP Roots protocol unavailable or failed: ${formatUnknownErrorMessage(error)}`, this.loggingState.minimumLevel);
         }
         finally {
             await this.recomputeAllowedDirectories();
+            this.updatingRoots = false;
+            // If a change arrived while we were running, apply it now.
+            if (this.pendingRootsUpdate) {
+                this.pendingRootsUpdate = false;
+                void this.updateRootsFromClient(server);
+            }
         }
     }
 }

package/dist/tools/edit-file.js

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import RE2 from 're2';
 import { ErrorCode } from '../lib/errors.js';
 import { atomicWriteFile } from '../lib/fs-helpers.js';
 import { validateExistingPath } from '../lib/path-validation.js';
@@ -35,7 +36,7 @@ function applyEdits(content, edits, ignoreWhitespace) {
     for (const edit of edits) {
         if (ignoreWhitespace) {
             const pattern = escapeRegExp(edit.oldText).replace(/\s+/g, '\\s+');
-            const regex = new RegExp(pattern);
+            const regex = new RE2(pattern);
             const match = regex.exec(newContent);
             if (!match) {
                 unmatchedEdits.push(edit.oldText);

package/dist/tools/list-directory.js

@@ -17,9 +17,10 @@ export const LIST_DIRECTORY_TOOL = {
     inputSchema: ListDirectoryInputSchema,
     outputSchema: ListDirectoryOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    taskSupport: 'optional',
     nuances: ['`pattern` enables filtered recursive traversal up to `maxDepth`.'],
 };
-function buildListTextResult(result) {
+function buildListTextResult(result, nextCursor) {
     const { entries, summary, path } = result;
     if (entries.length === 0) {
         if (!summary.entriesScanned || summary.entriesScanned === 0) {
@@ -45,7 +46,11 @@ function buildListTextResult(result) {
         truncated: summary.truncated,
         ...(truncatedReason ? { truncatedReason } : {}),
     };
-    return joinLines(lines) + formatOperationSummary(summaryOptions);
+    let text = joinLines(lines) + formatOperationSummary(summaryOptions);
+    if (nextCursor) {
+        text += `\n[Next page available. Use cursor: "${nextCursor}"]`;
+    }
+    return text;
 }
 function buildStructuredListEntry(entry) {
     return {
@@ -115,7 +120,7 @@ async function handleListDirectory(args, signal) {
         ? encodeCursor(cursorOffset + displayEntries.length)
         : undefined;
     const displayResult = { ...result, entries: displayEntries };
-    return buildToolResponse(buildListTextResult(displayResult), buildStructuredListResult(displayResult, nextCursor));
+    return buildToolResponse(buildListTextResult(displayResult, nextCursor), buildStructuredListResult(displayResult, nextCursor));
 }
 export function registerListDirectoryTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({

package/dist/tools/search-content.js

@@ -224,6 +224,11 @@ export function registerSearchContentTool(server, options = {}) {
                 });
             };
             try {
+                if (signal) {
+                    signal.addEventListener('abort', () => {
+                        console.error('searchContent signal aborted!');
+                    });
+                }
                 const result = await handleSearchContent(args, signal, options.resourceStore, progressWithMessage);
                 const sc = result.structuredContent;
                 const count = sc.ok && sc.totalMatches ? sc.totalMatches : 0;

package/dist/tools/search-files.js

@@ -113,7 +113,10 @@ async function handleSearchFiles(args, signal, onProgress) {
             textLines.push(`  ${entry.path}`);
         }
     }
-    const text = joinLines(textLines) + formatOperationSummary(summaryOptions);
+    let text = joinLines(textLines) + formatOperationSummary(summaryOptions);
+    if (nextCursor) {
+        text += `\n[Next page available. Use cursor: "${nextCursor}"]`;
+    }
     return buildToolResponse(text, structured);
 }
 export function registerSearchFilesTool(server, options = {}) {

package/dist/tools/shared.d.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 import type { FileInfo } from '../config.js';
 import { ErrorCode } from '../lib/errors.js';
 import type { ResourceStore } from '../lib/resource-store.js';
-import type { ToolErrorResponseSchema } from '../schemas.js';
 export { type ToolContract } from './contract.js';
 export declare const READ_ONLY_TOOL_ANNOTATIONS: {
     readonly readOnlyHint: true;
@@ -42,12 +41,13 @@ export declare function buildToolResponse<T>(text: string, structuredContent: T,
     content: ContentBlock[];
     structuredContent: T;
 };
-export type ToolResponse<T> = ReturnType<typeof buildToolResponse<T>> & Record<string, unknown>;
-type ToolErrorStructuredContent = z.infer<typeof ToolErrorResponseSchema>;
+export type ToolResponse<T> = ReturnType<typeof buildToolResponse<T>> & {
+    isError?: never;
+} & Record<string, unknown>;
 interface ToolErrorResponse extends Record<string, unknown> {
     content: ContentBlock[];
-    structuredContent: ToolErrorStructuredContent;
     isError: true;
+    errorCode?: string;
 }
 export type ToolResult<T> = ToolResponse<T> | ToolErrorResponse;
 export declare function withValidatedArgs<Args, Result>(schema: z.ZodType<Args>, handler: (args: Args, extra: ToolExtra) => Promise<ToolResult<Result>>): (args: unknown, extra: ToolExtra) => Promise<ToolResult<Result>>;
@@ -117,4 +117,13 @@ export declare function wrapToolHandler<Args, Result>(handler: (args: Args, extr
     progressMessage?: (args: Args) => string;
     completionMessage?: (args: Args, result: ToolResult<Result>) => string | undefined;
 }): (args: Args, extra?: ToolExtra) => Promise<ToolResult<Result>>;
+/**
+ * Returns `pathValue` if non-empty; otherwise resolves to the single allowed
+ * directory from module-level state managed by `RootsManager`. Throws when the
+ * path is ambiguous (multiple roots) or when no roots are configured.
+ *
+ * NOTE: Depends on `getAllowedDirectories()` which reads module-level state
+ * updated by `RootsManager`. Ensure the server is initialized before calling.
+ * See `src/server/roots-manager.ts` for the update lifecycle.
+ */
 export declare function resolvePathOrRoot(pathValue: string | undefined): string;

package/dist/tools/shared.js

@@ -195,24 +195,10 @@ export async function executeToolWithDiagnostics(options) {
 export function buildToolErrorResponse(error, defaultCode, path) {
     const detailed = resolveDetailedError(error, defaultCode, path);
     const text = formatDetailedError(detailed);
-    const errorContent = {
-        code: detailed.code,
-        message: detailed.message,
-    };
-    if (detailed.path !== undefined) {
-        errorContent.path = detailed.path;
-    }
-    if (detailed.suggestion !== undefined) {
-        errorContent.suggestion = detailed.suggestion;
-    }
-    const structuredContent = {
-        ok: false,
-        error: errorContent,
-    };
     return {
         content: [{ type: 'text', text }],
-        structuredContent,
         isError: true,
+        errorCode: detailed.code,
     };
 }
 function buildNotInitializedResult() {
@@ -274,10 +260,11 @@ export function createProgressReporter(extra) {
         // out-of-order progress is undefined in the MCP spec.
         if (current <= lastProgress)
             return;
-        // Enforce rate-limiting to prevent client flooding. Progress updates faster
-        // than PROGRESS_RATE_LIMIT_MS are silently dropped.
+        // Terminal notifications always bypass the rate limit so clients reliably
+        // receive the final state even when updates arrive in quick succession.
+        const isTerminal = total !== undefined && current >= total;
         const now = Date.now();
-        if (now - lastSentMs < PROGRESS_RATE_LIMIT_MS)
+        if (!isTerminal && now - lastSentMs < PROGRESS_RATE_LIMIT_MS)
             return;
         lastProgress = current;
         lastSentMs = now;
@@ -298,11 +285,12 @@ async function withProgress(message, extra, run, getCompletionMessage) {
         return run();
     }
     const total = 1;
-    await reportProgress(extra, {
-        current: 0,
-        total,
-        message,
-    });
+    // Emit the start notification only when a progressToken is present; for
+    // task-only mode the task status is already 'working' — a zero-progress
+    // notification would add unnecessary overhead without client value.
+    if (canSendProgress(extra)) {
+        await reportProgress(extra, { current: 0, total, message });
+    }
     try {
         const result = await run();
         const endMessage = getCompletionMessage?.(result) ?? message;
@@ -341,6 +329,15 @@ export function wrapToolHandler(handler, options) {
         return maybeStripStructuredContentFromResult(result);
     };
 }
+/**
+ * Returns `pathValue` if non-empty; otherwise resolves to the single allowed
+ * directory from module-level state managed by `RootsManager`. Throws when the
+ * path is ambiguous (multiple roots) or when no roots are configured.
+ *
+ * NOTE: Depends on `getAllowedDirectories()` which reads module-level state
+ * updated by `RootsManager`. Ensure the server is initialized before calling.
+ * See `src/server/roots-manager.ts` for the update lifecycle.
+ */
 export function resolvePathOrRoot(pathValue) {
     if (pathValue && pathValue.trim().length > 0)
         return pathValue;

package/dist/tools/task-support.js

@@ -134,14 +134,21 @@ function normalizeCallToolResult(value) {
 function getToolResultErrorCode(result) {
     if (!isRecord(result) || result['isError'] !== true)
         return undefined;
-    const structured = result['structuredContent'];
-    if (!isRecord(structured))
+    // First check for a dedicated errorCode property to avoid regex parsing of the content for structured error results produced by newer code.
+    if (typeof result['errorCode'] === 'string')
+        return result['errorCode'];
+    // Fallback to regex parsing of the human-readable error message for older error results that lack a structured errorCode property.
+    const { content } = result;
+    if (!Array.isArray(content) || content.length === 0)
         return undefined;
-    const { error } = structured;
-    if (!isRecord(error))
+    const first = content[0];
+    if (!isRecord(first) || first['type'] !== 'text')
         return undefined;
-    const { code } = error;
-    return typeof code === 'string' ? code : undefined;
+    const { text } = first;
+    if (typeof text !== 'string')
+        return undefined;
+    const match = /^Error \[([A-Z0-9_]+)\]:/.exec(text);
+    return match ? match[1] : undefined;
 }
 function isCancelledToolResult(result) {
     return getToolResultErrorCode(result) === ErrorCode.E_CANCELLED;
@@ -222,7 +229,7 @@ function getTaskId(extra) {
     return extra.taskId;
 }
 function isErrorResult(result) {
-    return 'isError' in result && result.isError === true;
+    return 'isError' in result && result.isError;
 }
 // Strips structuredContent from a tool result if present, without modifying the original object.  This is used when storing error results as 'completed' to prevent client-side output schema validation errors, while still allowing the human-readable error message in content[0].text to be returned to clients.
 function withoutStructuredContent(result) {
@@ -290,6 +297,21 @@ async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName
         }
         catch (innerError) {
             console.error(`Failed to store task failure result for task ${taskId}:`, innerError);
+            // If storing the failure result also fails, there's not much we can do. The task will remain in 'working' status until it expires, which is not ideal but at least prevents clients from receiving incorrect results or hanging indefinitely waiting for a result that will never arrive. We log the error to aid debugging, and we attempt to notify the client of the failure if possible, but we don't want to throw further errors that could crash the server or cause cascading failures.
+            const syntheticTask = {
+                taskId,
+                status: 'failed',
+                ttl: null,
+                createdAt: new Date().toISOString(),
+                lastUpdatedAt: new Date().toISOString(),
+            };
+            const { sendNotification } = extra;
+            if (typeof sendNotification === 'function') {
+                void sendNotification({
+                    method: TASK_STATUS_NOTIFICATION_METHOD,
+                    params: buildTaskStatusNotificationParams(syntheticTask),
+                });
+            }
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",