@j0hanz/filesystem-mcp 1.13.2 → 1.14.1

package/dist/resources/tool-catalog.js

@@ -15,27 +15,16 @@ function buildCrossToolDataFlow() {
 }
 function buildCatalogGuide() {
     const taskCapable = getTaskCapableToolNames();
-    return (`<tool_selection_guide>
+    return `# Tool Selection Guide
+
 ## Primitive Routing
 
-- ` +
-        '`tools`' +
-        `: model-controlled operations that inspect or mutate the allowed filesystem.
-- ` +
-        '`resources`' +
-        `: application-driven context such as ` +
-        '`internal://instructions`' +
-        `, ` +
-        '`internal://tool-info/{name}`' +
-        `, and cached ` +
-        '`filesystem-mcp://result/{id}`' +
-        ` output.
-- ` +
-        '`prompts`' +
-        `: user-controlled workflow templates for help, comparison, and guided inspection.
-- ` +
-        '`completion`' +
-        `: argument suggestions for prompts and resource templates; not a discovery mechanism.
+| Primitive      | Purpose                                                                                                                            |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| \`tools\`      | Model-controlled operations that inspect or mutate the filesystem within allowed roots.                                            |
+| \`resources\`  | Application-driven context: \`internal://instructions\`, \`internal://tool-info/{name}\`, cached \`filesystem-mcp://result/{id}\`. |
+| \`prompts\`    | User-controlled workflow templates for help, comparison, and guided inspection.                                                    |
+| \`completion\` | Argument suggestions for prompts and resource templates (not a discovery mechanism).                                               |
 
 ## Cross-Tool Data Flow
 
@@ -45,55 +34,41 @@ ${buildCrossToolDataFlow()}
 
 ## Result Contract
 
-- Successful tools return ` +
-        '`content`' +
-        ` and usually ` +
-        '`structuredContent`' +
-        `.
-- Tool/business failures return ` +
-        '`isError: true`' +
-        ` inside the tool result, not a JSON-RPC protocol error.
-- When a tool returns ` +
-        '`resourceUri`' +
-        ` or a ` +
-        '`resource_link`' +
-        `, follow it with ` +
-        '`resources/read`' +
-        ` immediately.
+- Success: returns both \`content\` (JSON text) and \`structuredContent\` (when \`outputSchema\` is declared).
+- Error: \`isError: true\` in tool result, \`structuredContent\` omitted. Parse \`content\` text for error details.
+- Tool/business failures use \`isError: true\` inside the tool result, not JSON-RPC protocol errors.
+- When a response includes \`resourceUri\` or \`resource_link\`, follow up with \`resources/read\` immediately.
+
+## Task Mode
 
-## Task Mode Routing
+Use inline execution by default. Add task mode only when the caller needs durable polling, deferred retrieval, or cancellation.
 
-- Inline first for fast operations.
-- Add task mode only when the caller needs durable polling, deferred retrieval, or cancellation after the initial response.
-- Task-capable tools: ${taskCapable.length > 0 ? taskCapable.map((name) => `\`${name}\``).join(', ') : 'none'}.
+Task-capable tools: ${taskCapable.length > 0 ? taskCapable.map((name) => `\`${name}\``).join(', ') : 'none'}.
 
 ## Search Strategy
 
-- \`find\`: glob file discovery.
-- \`grep\`: text content search.
-- \`search_and_replace\`: replacement only, not discovery.
+| Goal                    | Tool                                       |
+| ----------------------- | ------------------------------------------ |
+| Find files by name/glob | \`find\`                                   |
+| Search file contents    | \`grep\`                                   |
+| Replace across files    | \`search_and_replace\` (not for discovery) |
 
 ## Write Strategy
 
-- \`edit\`: precise first-occurrence replacements.
-- \`write\`: create files or overwrite full contents.
-- \`search_and_replace\`: bulk multi-file replacements.
-
-### edit vs write vs search_and_replace Decision
-
-1. **Single file, targeted change?** -> \`edit\` (match exact text, replace first occurrence)
-2. **Single file, full rewrite?** -> \`write\` (overwrite entire content)
-3. **Multiple files, same change?** -> \`search_and_replace\` (glob + pattern across files)
-4. **Not sure what to change?** -> \`grep\` first, then decide
+| Scenario                    | Tool                                                  |
+| --------------------------- | ----------------------------------------------------- |
+| Single file, targeted edit  | \`edit\` — match exact text, replace first occurrence |
+| Single file, full rewrite   | \`write\` — overwrite entire content                  |
+| Multiple files, same change | \`search_and_replace\` — glob + pattern across files  |
+| Unsure what to change       | \`grep\` first, then decide                           |
 
-## Patch Management
+## Patch Strategy
 
-- Generate patches with \`diff_files\` first.
-- Validate with \`apply_patch(dryRun:true)\` before writing.
-- \`apply_patch\` accepts unified diffs - single-file or multi-file.
-- Multi-file: \`path\` is base directory; each file is best-effort with per-file \`results[]\`.
-</tool_selection_guide>
-`);
+1. Generate with \`diff_files\`.
+2. Validate with \`apply_patch(dryRun: true)\` before writing.
+3. Apply with \`apply_patch\`.
+4. Multi-file patches: set \`path\` to the base directory; results are per-file.
+`;
 }
 export function buildToolCatalog() {
     return `${buildCoreContextPack()}\n\n${buildCatalogGuide()}`;

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

@@ -4,7 +4,6 @@ export declare function getSortedToolContracts(): ToolContract[];
 export declare function pickAvailableToolNames(names: readonly string[]): string[];
 export declare function formatToolNameList(names: readonly string[]): string;
 export declare function getTaskCapableToolNames(): string[];
-export declare function getTaskToolNamesBySupport(taskSupport: Extract<ToolContract['taskSupport'], 'optional' | 'required'>): string[];
 export declare function buildCoreContextPack(): string;
 export declare function getSharedConstraints(): string[];
 export declare function buildToolInfo(name: string): string | undefined;

package/dist/resources/tool-info.js

@@ -55,11 +55,6 @@ export function getTaskCapableToolNames() {
         contract.taskSupport === 'required')
         .map((contract) => contract.name);
 }
-export function getTaskToolNamesBySupport(taskSupport) {
-    return getSortedToolContracts()
-        .filter((contract) => contract.taskSupport === taskSupport)
-        .map((contract) => contract.name);
-}
 export function buildCoreContextPack() {
     const rows = getSortedToolContracts().map((contract) => {
         const e = ENTRIES[contract.name];
@@ -68,14 +63,14 @@ export function buildCoreContextPack() {
         const annotations = e.annotations ? ` ${e.annotations.join(' ')}` : '';
         return `| \`${e.name}\` | ${e.description}${annotations} |`;
     });
-    return `<core_context>\n| Tool | Purpose |\n|------|---------|\n${rows.join('\n')}\n</core_context>`;
+    return `## Tool Summary\n\n| Tool | Purpose |\n|------|---------|\n${rows.join('\n')}`;
 }
 export function getSharedConstraints() {
     return [
-        'Use allowed roots only (from CLI negotiation).',
-        'Sensitive paths are denylisted by default.',
-        `Limits enforced: max file size ${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB; search caps ${MAX_SEARCH_RESULTS} files, ${DEFAULT_SEARCH_CONTENT_RESULTS} content matches.`,
-        'If response includes `resourceUri`, call `resources/read` immediately — cached results expire on restart.',
+        'Operate within allowed roots only (negotiated at startup via CLI).',
+        'Sensitive file paths (e.g. .env, *.pem, *id_rsa*) are denied by default.',
+        `Enforced limits: max file size ${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)} MB, file search cap ${MAX_SEARCH_RESULTS} results, content search cap ${DEFAULT_SEARCH_CONTENT_RESULTS} matches.`,
+        'When a response includes `resourceUri`, call `resources/read` immediately — cached results expire on server restart.',
     ];
 }
 function formatTaskSupportLabel(taskSupport) {
@@ -88,12 +83,17 @@ function formatTaskSupportLabel(taskSupport) {
             return 'forbidden';
     }
 }
-function formatAnnotationValue(value) {
-    return value ? 'true' : 'false';
-}
 function toJsonSchemaObject(schema, io = 'output') {
     return z.toJSONSchema(schema, { io });
 }
+function summarizeArrayType(schema) {
+    if (Array.isArray(schema.prefixItems) && schema.prefixItems.length > 0) {
+        const itemTypes = schema.prefixItems.map(summarizeSchemaType).join(', ');
+        return `tuple<${itemTypes}>`;
+    }
+    const itemType = schema.items ? summarizeSchemaType(schema.items) : 'unknown';
+    return `array<${itemType}>`;
+}
 function summarizeSchemaType(schema) {
     if (Array.isArray(schema.enum) && schema.enum.length > 0) {
         return `enum(${schema.enum.map((value) => JSON.stringify(value)).join(', ')})`;
@@ -108,14 +108,7 @@ function summarizeSchemaType(schema) {
         return schema.oneOf.map(summarizeSchemaType).join(' | ');
     }
     if (schema.type === 'array') {
-        if (Array.isArray(schema.prefixItems) && schema.prefixItems.length > 0) {
-            const itemTypes = schema.prefixItems.map(summarizeSchemaType).join(', ');
-            return `tuple<${itemTypes}>`;
-        }
-        const itemType = schema.items
-            ? summarizeSchemaType(schema.items)
-            : 'unknown';
-        return `array<${itemType}>`;
+        return summarizeArrayType(schema);
     }
     if (schema.type === 'object' && schema.additionalProperties === false) {
         return 'object (strict)';
@@ -125,16 +118,23 @@ function summarizeSchemaType(schema) {
     }
     return 'unknown';
 }
+function formatFieldLabel(label) {
+    return label
+        .split('_')
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
 function buildSchemaFieldLines(label, schema) {
+    const heading = `**${formatFieldLabel(label)}:**`;
     if (!schema) {
-        return [`<${label}>`, '- none', `</${label}>`];
+        return [heading, '- none'];
     }
     const io = label === 'input_fields' ? 'input' : 'output';
     const jsonSchema = toJsonSchemaObject(schema, io);
     const properties = jsonSchema.properties ?? {};
     const required = new Set(jsonSchema.required ?? []);
     const fieldNames = Object.keys(properties);
-    const lines = [`<${label}>`];
+    const lines = [heading];
     if (typeof jsonSchema.description === 'string' &&
         jsonSchema.description.length > 0) {
         lines.push(`- Schema constraints: ${jsonSchema.description}`);
@@ -143,7 +143,7 @@ function buildSchemaFieldLines(label, schema) {
         lines.push('- Unknown fields are rejected (`additionalProperties: false`).');
     }
     if (fieldNames.length === 0) {
-        lines.push('- object with no fields', `</${label}>`);
+        lines.push('- object with no fields');
         return lines;
     }
     lines.push(...fieldNames.map((fieldName) => {
@@ -155,75 +155,52 @@ function buildSchemaFieldLines(label, schema) {
             ? fieldSchema.description
             : 'No description.';
         return `- ${fieldName} (${type}, ${requiredLabel}): ${description}`;
-    }), `</${label}>`);
+    }));
     return lines;
 }
-function buildProtocolNotes(contract) {
-    const notes = [
-        '- Protocol failures use JSON-RPC `error`; execution failures use tool result `isError: true`.',
-    ];
-    if (contract.outputSchema) {
-        notes.push('- Successful responses include `structuredContent` that must match the declared output schema.');
-    }
-    if (contract.taskSupport === 'optional') {
-        notes.push('- Supports inline execution by default and task mode when durable polling or deferred results are needed.');
-    }
-    if (contract.taskSupport === 'required') {
-        notes.push('- Must run in task mode; callers should poll `tasks/get` and fetch the payload via `tasks/result`.');
-    }
-    if (contract.taskSupport === 'forbidden') {
-        notes.push('- Runs inline only; task augmentation is not supported for this tool.');
-    }
-    return notes;
-}
 export function buildToolInfo(name) {
     const contract = CONTRACTS_BY_NAME.get(name);
     const entry = ENTRIES[name];
     if (!entry || !contract)
         return undefined;
+    const annotationLines = [];
+    if (contract.annotations?.readOnlyHint)
+        annotationLines.push('- readOnlyHint: true');
+    if (contract.annotations?.idempotentHint)
+        annotationLines.push('- idempotentHint: true');
+    if (contract.annotations?.destructiveHint)
+        annotationLines.push('- destructiveHint: true');
+    if (contract.annotations?.openWorldHint)
+        annotationLines.push('- openWorldHint: true');
     const lines = [
-        `<tool_info name="${entry.name}">`,
-        `## ${entry.name}`,
+        `---`,
+        `# ${entry.name}`,
         '',
-        `Title: ${entry.title}`,
-        `Description: ${entry.description}`,
+        `**Title:** ${entry.title}`,
+        `**Description:** ${entry.description}`,
         '',
-        '<execution>',
+        '**Execution:**',
         `- taskSupport: ${formatTaskSupportLabel(contract.taskSupport)}`,
-        '</execution>',
-        '',
-        '<annotations>',
-        `- readOnlyHint: ${formatAnnotationValue(contract.annotations?.readOnlyHint)}`,
-        `- idempotentHint: ${formatAnnotationValue(contract.annotations?.idempotentHint)}`,
-        `- destructiveHint: ${formatAnnotationValue(contract.annotations?.destructiveHint)}`,
-        `- openWorldHint: ${formatAnnotationValue(contract.annotations?.openWorldHint)}`,
-        '</annotations>',
         '',
         ...buildSchemaFieldLines('input_fields', contract.inputSchema),
         '',
         ...buildSchemaFieldLines('output_fields', contract.outputSchema),
-        '',
-        '<protocol_notes>',
-        ...buildProtocolNotes(contract),
-        '</protocol_notes>',
     ];
-    if (entry.annotations && entry.annotations.length > 0) {
-        lines.push('', `<quick_hints>${entry.annotations.join(' ')}</quick_hints>`);
+    if (annotationLines.length > 0) {
+        lines.push('', '**Behavior:**', ...annotationLines);
     }
     if (entry.nuances && entry.nuances.length > 0) {
-        lines.push('', '<nuances>');
+        lines.push('', '**Usage Notes:**');
         for (const nuance of entry.nuances) {
             lines.push(`- ${nuance}`);
         }
-        lines.push('</nuances>');
     }
     if (entry.gotchas && entry.gotchas.length > 0) {
-        lines.push('', '<gotchas>');
+        lines.push('', '**Warnings:**');
         for (const gotcha of entry.gotchas) {
             lines.push(`- ${gotcha}`);
         }
-        lines.push('</gotchas>');
     }
-    lines.push('</tool_info>');
+    lines.push('---');
     return lines.join('\n');
 }

package/dist/resources/workflows.js

@@ -10,23 +10,51 @@ export function buildWorkflowGuide() {
         'read_many',
     ]));
     const searchTools = formatToolNameList(pickAvailableToolNames(['find', 'grep', 'read']));
-    const editTools = formatToolNameList(pickAvailableToolNames(['edit', 'search_and_replace', 'mv', 'rm', 'mkdir']));
-    return `<workflows>
-### A: EXPLORE — directory layout or file content
-1. ${exploreTools}.
-   > **Strict:** Resolve paths first. Never guess.
-
-### B: SEARCH — files by pattern or content
-1. ${searchTools}.
-   > **Strict:** Content search with \`grep\`, not \`find\`.
-
-### C: EDIT — modify files or layout
-1. ${editTools}.
-2. Use \`edit\` for targeted changes, \`search_and_replace\` for bulk changes, and \`mv\`/\`rm\`/\`mkdir\` for layout updates.
-   > **Strict:** Confirm destructive ops (\`write\`, \`mv\`, \`rm\`, bulk replace).
-
-### D: PATCH — apply unified diffs
-1. \`diff_files\` → \`apply_patch(dryRun:true)\` → \`apply_patch\`.
-   > **Tip:** Feed \`diff_files\` output directly. Multi-file patches: \`path\` = base dir, results per file.
-</workflows>`;
+    const editTools = formatToolNameList(pickAvailableToolNames([
+        'edit',
+        'write',
+        'search_and_replace',
+        'mv',
+        'rm',
+        'mkdir',
+    ]));
+    return `## Workflows
+
+### A: Explore — Discover directory layout or file content
+
+**Tools:** ${exploreTools}
+
+1. Start with \`roots\` to identify allowed directories.
+2. Use \`ls\` or \`tree\` to map structure, then \`stat\` or \`read\` for details.
+
+> Resolve paths before acting. Never assume a path exists.
+
+### B: Search — Find files by name or content
+
+**Tools:** ${searchTools}
+
+1. Use \`find\` for file name/glob matching.
+2. Use \`grep\` for content search (supports regex).
+3. Use \`read\` to inspect matched files.
+
+> Use \`grep\` for content, \`find\` for filenames. Do not conflate them.
+
+### C: Edit — Modify files or directory layout
+
+**Tools:** ${editTools}
+
+1. Use \`edit\` for targeted single-file changes (exact text match → replace).
+2. Use \`search_and_replace\` for bulk changes across multiple files.
+3. Use \`mv\`, \`rm\`, \`mkdir\` for structural changes.
+
+> Confirm destructive operations (\`write\`, \`mv\`, \`rm\`, bulk replace) before executing.
+
+### D: Patch — Generate and apply unified diffs
+
+1. Generate: \`diff_files(original, modified)\`.
+2. Validate: \`apply_patch(patch, dryRun: true)\`.
+3. Apply: \`apply_patch(patch)\`.
+
+> Multi-file patches: set \`path\` to the base directory. Results are reported per file.
+`;
 }

package/dist/resources.d.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ResourceStore } from './lib/resource-store.js';
 import { type IconInfo } from './tools/shared.js';
 export declare function registerInstructionResource(server: McpServer, instructions: string, iconInfo?: IconInfo): void;

package/dist/resources.js

@@ -1,4 +1,4 @@
-import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+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';
@@ -104,7 +104,7 @@ export function registerResultResources(server, store, iconInfo) {
     }, iconInfo), (uri, variables) => {
         const { id } = variables;
         if (typeof id !== 'string' || id.length === 0) {
-            throw new McpError(ErrorCode.E_NOT_FOUND, 'Cached result has expired — re-run the tool to regenerate.');
+            throw new McpError(ErrorCode.NOT_FOUND, 'Cached result expired. Re-run the tool to regenerate.');
         }
         const entry = store.getText(uri.toString());
         return {
@@ -130,11 +130,11 @@ export function registerToolInfoResource(server, iconInfo) {
     }, iconInfo), (uri, variables) => {
         const { name } = variables;
         if (typeof name !== 'string' || name.length === 0) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Tool name is required');
+            throw new McpError(ErrorCode.INVALID_INPUT, 'Tool name is required');
         }
         const content = buildToolInfo(name);
         if (content === undefined) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, `Tool not found: ${name}`);
+            throw new McpError(ErrorCode.INVALID_INPUT, `Tool not found: ${name}`);
         }
         return {
             contents: [