@j0hanz/filesystem-mcp 1.13.2 → 1.14.0

package/dist/lib/fs-helpers.js

@@ -287,13 +287,11 @@ function validateReadOptions(options) {
     if (hasTail && (hasHead || hasStart || hasEnd)) {
         throw new McpError(ErrorCode.E_INVALID_INPUT, 'tail cannot be used together with head/startLine/endLine');
     }
-    if (hasEnd && !hasStart) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'endLine requires startLine');
-    }
-    if (options.startLine !== undefined &&
-        options.endLine !== undefined &&
-        options.endLine < options.startLine) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'endLine must be greater than or equal to startLine');
+    {
+        const effectiveStart = options.startLine ?? 1;
+        if (options.endLine !== undefined && options.endLine < effectiveStart) {
+            throw new McpError(ErrorCode.E_INVALID_INPUT, 'endLine must be greater than or equal to startLine (default: 1)');
+        }
     }
 }
 function normalizeOptions(options) {
@@ -309,12 +307,13 @@ function normalizeOptions(options) {
     if (options.tail !== undefined) {
         normalized.tail = options.tail;
     }
-    if (options.startLine !== undefined) {
-        normalized.startLine = options.startLine;
-    }
     if (options.endLine !== undefined) {
+        normalized.startLine = options.startLine ?? 1;
         normalized.endLine = options.endLine;
     }
+    else if (options.startLine !== undefined) {
+        normalized.startLine = options.startLine;
+    }
     if (options.signal) {
         normalized.signal = options.signal;
     }
@@ -340,7 +339,7 @@ function resolveReadMode(options) {
         return 'head';
     if (options.tail !== undefined)
         return 'tail';
-    if (options.startLine !== undefined)
+    if (options.startLine !== undefined || options.endLine !== undefined)
         return 'range';
     return 'full';
 }

package/dist/lib/globs.d.ts

@@ -0,0 +1,2 @@
+export declare function isSafeGlobPattern(value: string): boolean;
+export declare function assertSafeGlobPattern(value: string, message?: string): void;

package/dist/lib/globs.js

@@ -0,0 +1,19 @@
+import { ErrorCode, McpError } from './errors.js';
+const ABSOLUTE_GLOB_RE = /^([/\\]|[A-Za-z]:[/\\]|\\\\)/u;
+const PARENT_SEGMENT_RE = /[\\/]\.\.(?:[/\\]|$)/u;
+export function isSafeGlobPattern(value) {
+    if (value.length === 0)
+        return false;
+    if (value.includes('**/**/**'))
+        return false;
+    if (ABSOLUTE_GLOB_RE.test(value))
+        return false;
+    if (value.startsWith('..') || PARENT_SEGMENT_RE.test(value))
+        return false;
+    return true;
+}
+export function assertSafeGlobPattern(value, message = 'Invalid glob or unsafe path (absolute/.. forbidden)') {
+    if (!isSafeGlobPattern(value)) {
+        throw new McpError(ErrorCode.E_INVALID_PATTERN, message);
+    }
+}

package/dist/lib/zod-codecs.d.ts

@@ -0,0 +1,2 @@
+import { z } from 'zod';
+export declare function createBase64JsonCodec<Schema extends z.ZodType>(schema: Schema): z.ZodCodec<z.ZodString, Schema>;

package/dist/lib/zod-codecs.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+export function createBase64JsonCodec(schema) {
+    return z.codec(z.string(), schema, {
+        decode: (value) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf-8'));
+            }
+            catch (error) {
+                throw new Error('Invalid base64url-encoded JSON payload.', {
+                    cause: error,
+                });
+            }
+            return parsed;
+        },
+        encode: (value) => Buffer.from(JSON.stringify(value)).toString('base64url'),
+    });
+}

package/dist/pkg-info.d.ts

@@ -1,4 +1,5 @@
 export declare const pkgInfo: {
+    [x: string]: unknown;
     name: string;
     version: string;
     description?: string | undefined;

package/dist/pkg-info.js

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import packageJsonRaw from '../package.json' with { type: 'json' };
-const PkgInfoSchema = z.object({
+const PkgInfoSchema = z.looseObject({
     name: z.string(),
     version: z.string(),
     description: z.string().optional(),
-    homepage: z.string().optional(),
+    homepage: z.url().optional(),
 });
 export const pkgInfo = PkgInfoSchema.parse(packageJsonRaw);

package/dist/prompts.js

@@ -1,5 +1,5 @@
+import { ErrorCode as SdkErrorCode, McpError as SdkMcpError, } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { ErrorCode, McpError } from './lib/errors.js';
 import { buildToolInfo, getSortedToolContracts, } from './resources/tool-info.js';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
@@ -123,11 +123,11 @@ export function registerGetToolHelpPrompt(server, iconInfo) {
     }, ({ name }) => {
         const toolName = findKnownToolName(name);
         if (!toolName) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, `Unknown tool: ${name}`);
+            throw new SdkMcpError(SdkErrorCode.InvalidParams, `Unknown tool: ${name}`);
         }
         const toolInfo = buildToolInfo(toolName);
         if (!toolInfo) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, `Unknown tool: ${toolName}`);
+            throw new SdkMcpError(SdkErrorCode.InvalidParams, `Unknown tool: ${toolName}`);
         }
         return {
             description: GET_TOOL_HELP_PROMPT_DESCRIPTION,

package/dist/resources/generated-instructions.js

@@ -1,9 +1,6 @@
 import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
-import { buildCoreContextPack, formatToolNameList, getSharedConstraints, getTaskCapableToolNames, getTaskToolNamesBySupport, getToolContracts, pickAvailableToolNames, } from './tool-info.js';
+import { buildCoreContextPack, formatToolNameList, getSharedConstraints, getToolContracts, pickAvailableToolNames, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
-function formatTaskModeLine(label, names) {
-    return `${label}: ${names.length > 0 ? formatToolNameList(names) : 'none'}.`;
-}
 function buildToolsOverview() {
     const rows = [
         ['Navigate', pickAvailableToolNames(['roots', 'ls', 'tree', 'find'])],
@@ -31,9 +28,6 @@ function buildToolsOverview() {
         .join('\n');
 }
 function buildInstructionsHeader() {
-    const taskCapable = formatToolNameList(getTaskCapableToolNames());
-    const optionalTaskTools = getTaskToolNamesBySupport('optional');
-    const requiredTaskTools = getTaskToolNamesBySupport('required');
     return `<role>
 Filesystem agent. Scope: allowed roots only. Discover paths before acting — never guess.
 </role>
@@ -54,12 +48,9 @@ ${buildToolsOverview()}
 </resources>
 
 <task_protocol>
-Task execution: Call task-capable tools inline by default; add \`task\` only when durable polling or deferred results are needed.
-Task results: When a task is requested, poll via \`tasks/get\`, then retrieve the final payload via \`tasks/result\`.
+Task execution: Check \`execution.taskSupport\` per tool — \`forbidden\` (default): never send \`task\`; \`optional\`: send \`task\` only when durable polling or deferred results are needed; \`required\`: always send \`task\`.
+Task results: Poll via \`tasks/get\`, then retrieve the final payload via \`tasks/result\`.
 Progress: Pass \`_meta.progressToken\` in \`tools/call\` to receive \`notifications/progress\`.
-Task-capable: ${taskCapable || 'none'}.
-${formatTaskModeLine('Optional task mode', optionalTaskTools)}
-${formatTaskModeLine('Required task mode', requiredTaskTools)}
 </task_protocol>
 `;
 }

package/dist/resources/tool-catalog.js

@@ -15,27 +15,13 @@ 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.
+- \`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.
 
 ## Cross-Tool Data Flow
 
@@ -45,21 +31,10 @@ ${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.
+- Successful tools return \`content\` and \`structuredContent\` (when \`outputSchema\` is declared).
+- When \`isError: true\`, \`structuredContent\` is omitted — parse the \`content\` text instead.
+- 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.
 
 ## Task Mode Routing
 
@@ -75,12 +50,6 @@ ${buildCrossToolDataFlow()}
 
 ## 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)
@@ -93,7 +62,7 @@ ${buildCrossToolDataFlow()}
 - \`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>
-`);
+`;
 }
 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];
@@ -88,9 +83,6 @@ function formatTaskSupportLabel(taskSupport) {
             return 'forbidden';
     }
 }
-function formatAnnotationValue(value) {
-    return value ? 'true' : 'false';
-}
 function toJsonSchemaObject(schema, io = 'output') {
     return z.toJSONSchema(schema, { io });
 }
@@ -158,29 +150,20 @@ function buildSchemaFieldLines(label, schema) {
     }), `</${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}`,
@@ -192,23 +175,12 @@ export function buildToolInfo(name) {
         `- 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('', '<annotations>', ...annotationLines, '</annotations>');
     }
     if (entry.nuances && entry.nuances.length > 0) {
         lines.push('', '<nuances>');

package/dist/resources/workflows.js

@@ -10,7 +10,14 @@ export function buildWorkflowGuide() {
         'read_many',
     ]));
     const searchTools = formatToolNameList(pickAvailableToolNames(['find', 'grep', 'read']));
-    const editTools = formatToolNameList(pickAvailableToolNames(['edit', 'search_and_replace', 'mv', 'rm', 'mkdir']));
+    const editTools = formatToolNameList(pickAvailableToolNames([
+        'edit',
+        'write',
+        'search_and_replace',
+        'mv',
+        'rm',
+        'mkdir',
+    ]));
     return `<workflows>
 ### A: EXPLORE — directory layout or file content
 1. ${exploreTools}.