@j0hanz/filesystem-mcp 1.6.1 → 1.6.2

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.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 [

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.js

@@ -21,7 +21,7 @@ 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';
@@ -29,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',

package/dist/server/bootstrap.js

@@ -59,9 +59,7 @@ export async function createServer(options = {}) {
         }),
     };
     if (taskToolSupport) {
-        // Note: InMemoryTaskStore has no TTL — tasks accumulate for the process
-        // lifetime. In HTTP mode this may grow unboundedly for long-lived servers.
-        // Use a custom TaskStore with eviction for production HTTP deployments.
+        // 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();
     }
@@ -171,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;

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;

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/shared.d.ts

@@ -47,6 +47,7 @@ export type ToolResponse<T> = ReturnType<typeof buildToolResponse<T>> & {
 interface ToolErrorResponse extends Record<string, unknown> {
     content: ContentBlock[];
     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>>;
@@ -116,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

@@ -198,6 +198,7 @@ export function buildToolErrorResponse(error, defaultCode, path) {
     return {
         content: [{ type: 'text', text }],
         isError: true,
+        errorCode: detailed.code,
     };
 }
 function buildNotInitializedResult() {
@@ -259,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;
@@ -283,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;
@@ -326,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,6 +134,10 @@ function normalizeCallToolResult(value) {
 function getToolResultErrorCode(result) {
     if (!isRecord(result) || result['isError'] !== true)
         return undefined;
+    // 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;
@@ -293,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.1",
+  "version": "1.6.2",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",