@j0hanz/filesystem-mcp 1.5.4 → 1.6.1

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

@@ -9,6 +9,7 @@ interface DetailedError {
 }
 export declare function isNodeError(error: unknown): error is NodeJS.ErrnoException;
 export declare function formatUnknownErrorMessage(error: unknown): string;
+export declare function normalizeUnknownError(error: unknown): Error;
 export declare function isAbortError(error: unknown): boolean;
 export declare function isTimeoutLikeError(error: unknown): boolean;
 export declare class McpError extends Error {

package/dist/lib/errors.js

@@ -94,6 +94,11 @@ export function formatUnknownErrorMessage(error) {
         return String(error);
     }
 }
+export function normalizeUnknownError(error) {
+    return error instanceof Error
+        ? error
+        : new Error(formatUnknownErrorMessage(error));
+}
 const NODE_ERROR_CODE_MAP = {
     ENOENT: ErrorCode.E_NOT_FOUND,
     EACCES: ErrorCode.E_PERMISSION_DENIED,

package/dist/lib/fs-helpers.js

@@ -5,7 +5,7 @@ import { randomUUID } from 'node:crypto';
 import { Writable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { BINARY_CHECK_BUFFER_SIZE, KNOWN_BINARY_EXTENSIONS, MAX_TEXT_FILE_SIZE, PARALLEL_CONCURRENCY, } from './constants.js';
-import { ErrorCode, formatUnknownErrorMessage, McpError } from './errors.js';
+import { ErrorCode, McpError, normalizeUnknownError } from './errors.js';
 import { assertAllowedFileAccess } from './path-policy.js';
 import { validateExistingPath } from './path-validation.js';
 function createAbortError(message = 'Operation aborted') {
@@ -20,11 +20,6 @@ function normalizeAbortReason(reason, message) {
 function isFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value);
 }
-function normalizeUnknownError(error) {
-    return error instanceof Error
-        ? error
-        : new Error(formatUnknownErrorMessage(error));
-}
 export function assertNotAborted(signal, message) {
     if (!signal)
         return;

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/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

@@ -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.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,11 +2,23 @@ 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.';
@@ -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/schemas.d.ts

@@ -33,6 +33,8 @@ export declare const ToolErrorResponseSchema: z.ZodObject<{
         suggestion: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+declare const HeadLinesSchema: z.ZodOptional<z.ZodInt>;
+declare const LineNumberSchema: z.ZodNumber;
 export declare const ListDirectoryInputSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
     includeHidden: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -85,16 +87,16 @@ export declare const SearchContentInputSchema: z.ZodObject<{
     includeIgnored: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strict>;
 export declare const ReadFileInputSchema: z.ZodObject<{
+    head: typeof HeadLinesSchema;
+    startLine: z.ZodOptional<typeof LineNumberSchema>;
+    endLine: z.ZodOptional<typeof LineNumberSchema>;
     path: z.ZodString;
-    head: z.ZodOptional<z.ZodInt>;
-    startLine: z.ZodOptional<z.ZodNumber>;
-    endLine: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const ReadMultipleFilesInputSchema: z.ZodObject<{
+    head: typeof HeadLinesSchema;
+    startLine: z.ZodOptional<typeof LineNumberSchema>;
+    endLine: z.ZodOptional<typeof LineNumberSchema>;
     paths: z.ZodArray<z.ZodString>;
-    head: z.ZodOptional<z.ZodInt>;
-    startLine: z.ZodOptional<z.ZodNumber>;
-    endLine: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export declare const GetFileInfoInputSchema: z.ZodObject<{
     path: z.ZodString;
@@ -472,11 +474,13 @@ export declare const GetMultipleFileInfoOutputSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const CreateDirectoryInputSchema: z.ZodObject<{
-    path: z.ZodString;
+    path: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 export declare const CreateDirectoryOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     path: z.ZodOptional<z.ZodString>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodEnum<{
             readonly E_ACCESS_DENIED: "E_ACCESS_DENIED";
@@ -532,6 +536,7 @@ export declare const EditFileInputSchema: z.ZodObject<{
         newText: z.ZodString;
     }, z.core.$strict>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    ignoreWhitespace: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strict>;
 export declare const EditFileOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;
@@ -560,13 +565,19 @@ export declare const EditFileOutputSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const MoveFileInputSchema: z.ZodObject<{
-    source: z.ZodString;
+    source: z.ZodOptional<z.ZodString>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
     destination: z.ZodString;
 }, z.core.$strict>;
 export declare const MoveFileOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     source: z.ZodOptional<z.ZodString>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
     destination: z.ZodOptional<z.ZodString>;
+    failed: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strict>>>;
     error: z.ZodOptional<z.ZodObject<{
         code: z.ZodEnum<{
             readonly E_ACCESS_DENIED: "E_ACCESS_DENIED";
@@ -717,6 +728,7 @@ export declare const SearchAndReplaceInputSchema: z.ZodObject<{
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeHidden: z.ZodOptional<z.ZodBoolean>;
     includeIgnored: z.ZodOptional<z.ZodBoolean>;
+    returnDiff: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 export declare const SearchAndReplaceOutputSchema: z.ZodObject<{
     ok: z.ZodBoolean;

package/dist/schemas.js

@@ -81,6 +81,13 @@ const validateReadRange = (value, ctx) => {
         addReadRangeIssue(ctx, 'endLine', "'endLine' must be >= 'startLine'");
     }
 };
+function createReadRangeInputFields(descriptions) {
+    return {
+        head: HeadLinesSchema.describe(descriptions.head),
+        startLine: LineNumberSchema.optional().describe(descriptions.startLine),
+        endLine: LineNumberSchema.optional().describe(descriptions.endLine),
+    };
+}
 const FileInfoSchema = z.strictObject({
     name: z.string().describe('Name'),
     path: z.string().describe('Absolute path'),
@@ -280,9 +287,11 @@ export const SearchContentInputSchema = z.strictObject({
 export const ReadFileInputSchema = z
     .strictObject({
     path: RequiredPathSchema.describe(DESC_PATH_REQUIRED),
-    head: HeadLinesSchema.describe('Read first N lines (preview)'),
-    startLine: LineNumberSchema.optional().describe('Start line (1-based, inclusive)'),
-    endLine: LineNumberSchema.optional().describe('End line (1-based, inclusive). Requires startLine.'),
+    ...createReadRangeInputFields({
+        head: 'Read first N lines (preview)',
+        startLine: 'Start line (1-based, inclusive)',
+        endLine: 'End line (1-based, inclusive). Requires startLine.',
+    }),
 })
     .superRefine(validateReadRange);
 export const ReadMultipleFilesInputSchema = z
@@ -292,9 +301,11 @@ export const ReadMultipleFilesInputSchema = z
         .min(1, 'Min 1 path required')
         .max(100, 'Max 100 files')
         .describe('Files to read. e.g. ["src/index.ts"]'),
-    head: HeadLinesSchema.describe('Read first N lines of each file'),
-    startLine: LineNumberSchema.optional().describe('Start line (1-based, inclusive) per file'),
-    endLine: LineNumberSchema.optional().describe('End line (1-based, inclusive) per file. Requires startLine.'),
+    ...createReadRangeInputFields({
+        head: 'Read first N lines of each file',
+        startLine: 'Start line (1-based, inclusive) per file',
+        endLine: 'End line (1-based, inclusive) per file. Requires startLine.',
+    }),
 })
     .superRefine(validateReadRange);
 export const GetFileInfoInputSchema = z.strictObject({
@@ -459,12 +470,22 @@ export const GetMultipleFileInfoOutputSchema = z.strictObject({
     summary: OperationSummarySchema.optional(),
     error: ErrorSchema.optional(),
 });
-export const CreateDirectoryInputSchema = z.strictObject({
-    path: RequiredPathSchema.describe(DESC_PATH_REQUIRED),
+export const CreateDirectoryInputSchema = z
+    .strictObject({
+    path: RequiredPathSchema.optional().describe(DESC_PATH_REQUIRED),
+    paths: z
+        .array(RequiredPathSchema)
+        .optional()
+        .describe('Absolute paths to directories to create'),
+})
+    .refine((data) => data.path !== undefined || data.paths !== undefined, {
+    message: "Either 'path' or 'paths' must be provided",
+    path: ['path'],
 });
 export const CreateDirectoryOutputSchema = z.strictObject({
     ok: z.boolean(),
     path: z.string().optional(),
+    paths: z.array(z.string()).optional(),
     error: ErrorSchema.optional(),
 });
 export const WriteFileInputSchema = z.strictObject({
@@ -495,6 +516,11 @@ export const EditFileInputSchema = z.strictObject({
         .optional()
         .default(false)
         .describe('Preview edits without writing. Check unmatchedEdits in the response to verify all oldText values were found.'),
+    ignoreWhitespace: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe('Ignore leading/trailing whitespace and treat all whitespace sequences as equivalent when matching oldText.'),
 });
 export const EditFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -510,14 +536,28 @@ export const EditFileOutputSchema = z.strictObject({
         .describe('Edits that could not be applied'),
     error: ErrorSchema.optional(),
 });
-export const MoveFileInputSchema = z.strictObject({
-    source: RequiredPathSchema.describe('Path to move'),
+export const MoveFileInputSchema = z
+    .strictObject({
+    source: RequiredPathSchema.optional().describe('Path to move (deprecated: use sources)'),
+    sources: z.array(RequiredPathSchema).optional().describe('Paths to move'),
     destination: RequiredPathSchema.describe('New path'),
+})
+    .refine((data) => (data.source ?? data.sources) !== undefined, {
+    message: "Either 'source' or 'sources' must be provided",
+    path: ['source'],
 });
 export const MoveFileOutputSchema = z.strictObject({
     ok: z.boolean(),
     source: z.string().optional(),
+    sources: z.array(z.string()).optional(),
     destination: z.string().optional(),
+    failed: z
+        .array(z.strictObject({
+        source: z.string().describe('Source path'),
+        error: z.string().describe('Error message'),
+    }))
+        .optional()
+        .describe('List of files that failed to move'),
     error: ErrorSchema.optional(),
 });
 export const DeleteFileInputSchema = z.strictObject({
@@ -643,6 +683,10 @@ export const SearchAndReplaceInputSchema = z.strictObject({
         .boolean()
         .optional()
         .describe('Include files and directories ignored by .gitignore rules (e.g. node_modules, dist). Default: false.'),
+    returnDiff: z
+        .boolean()
+        .optional()
+        .describe('Return unified diff of changes even if dryRun is false. Default: false.'),
 });
 export const SearchAndReplaceOutputSchema = z.strictObject({
     ok: z.boolean(),

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,9 @@ 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.
         serverConfig.taskStore = new InMemoryTaskStore();
         serverConfig.taskMessageQueue = new InMemoryTaskMessageQueue();
     }
@@ -85,6 +88,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);
@@ -198,11 +202,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 +268,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

@@ -27,6 +27,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/tools/create-directory.d.ts

@@ -1,4 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { CreateDirectoryInputSchema, CreateDirectoryOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const CREATE_DIRECTORY_TOOL: ToolContract;
+export declare function handleCreateDirectory(args: z.infer<typeof CreateDirectoryInputSchema>, signal?: AbortSignal): Promise<ToolResponse<z.infer<typeof CreateDirectoryOutputSchema>>>;
 export declare function registerCreateDirectoryTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/create-directory.js

@@ -1,6 +1,5 @@
 import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { ErrorCode } from '../lib/errors.js';
+import { ErrorCode, McpError } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
 import { validatePathForWrite } from '../lib/path-validation.js';
 import { CreateDirectoryInputSchema, CreateDirectoryOutputSchema, } from '../schemas.js';
@@ -15,12 +14,20 @@ export const CREATE_DIRECTORY_TOOL = {
     annotations: IDEMPOTENT_WRITE_TOOL_ANNOTATIONS,
     nuances: ['Succeeds silently if the directory already exists (idempotent).'],
 };
-async function handleCreateDirectory(args, signal) {
-    const validPath = await validatePathForWrite(args.path, signal);
-    await withAbort(fs.mkdir(validPath, { recursive: true }), signal);
-    return buildToolResponse(`Successfully created directory: ${args.path}`, {
+export async function handleCreateDirectory(args, signal) {
+    const allPaths = [];
+    if (args.path)
+        allPaths.push(args.path);
+    if (args.paths)
+        allPaths.push(...args.paths);
+    if (allPaths.length === 0) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'No paths provided to create.');
+    }
+    const validPaths = await Promise.all(allPaths.map((p) => validatePathForWrite(p, signal)));
+    await Promise.all(validPaths.map((p) => withAbort(fs.mkdir(p, { recursive: true }), signal)));
+    return buildToolResponse(`Successfully created ${validPaths.length} director${validPaths.length === 1 ? 'y' : 'ies'}`, {
         ok: true,
-        path: validPath,
+        paths: validPaths,
     });
 }
 export function registerCreateDirectoryTool(server, options = {}) {
@@ -28,21 +35,21 @@ export function registerCreateDirectoryTool(server, options = {}) {
         toolName: 'mkdir',
         extra,
         timedSignal: {},
-        context: { path: args.path },
+        context: { path: args.path ?? args.paths?.[0] },
         run: (signal) => handleCreateDirectory(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path ?? args.paths?.[0]),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
-            const name = path.basename(args.path) || '.';
-            return `🛠 mkdir: ${name}`;
+            const count = (args.path ? 1 : 0) + (args.paths?.length ?? 0);
+            return `🛠 mkdir: ${count} director${count === 1 ? 'y' : 'ies'}`;
         },
         completionMessage: (args, result) => {
-            const name = path.basename(args.path) || '.';
+            const count = (args.path ? 1 : 0) + (args.paths?.length ?? 0);
             if (result.isError)
-                return `🛠 mkdir: ${name} • failed`;
-            return `🛠 mkdir: ${name} • created`;
+                return `🛠 mkdir: ${count} • failed`;
+            return `🛠 mkdir: ${count} • created`;
         },
     });
     const validatedHandler = withValidatedArgs(CreateDirectoryInputSchema, wrappedHandler);

package/dist/tools/edit-file.d.ts

@@ -1,4 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { EditFileInputSchema, EditFileOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const EDIT_FILE_TOOL: ToolContract;
+export declare function handleEditFile(args: z.infer<typeof EditFileInputSchema>, signal?: AbortSignal): Promise<ToolResponse<z.infer<typeof EditFileOutputSchema>>>;
 export declare function registerEditFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

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';
@@ -23,28 +24,57 @@ export const EDIT_FILE_TOOL = {
         '`oldText` must match exactly; unmatched items are reported in `unmatchedEdits`.',
     ],
 };
-function applyEdits(content, edits) {
+function escapeRegExp(string) {
+    return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function applyEdits(content, edits, ignoreWhitespace) {
     let newContent = content;
     let appliedEdits = 0;
     const unmatchedEdits = [];
     let minLine;
     let maxLine;
     for (const edit of edits) {
-        if (!newContent.includes(edit.oldText)) {
-            unmatchedEdits.push(edit.oldText);
-            continue;
+        if (ignoreWhitespace) {
+            const pattern = escapeRegExp(edit.oldText).replace(/\s+/g, '\\s+');
+            const regex = new RE2(pattern);
+            const match = regex.exec(newContent);
+            if (!match) {
+                unmatchedEdits.push(edit.oldText);
+                continue;
+            }
+            const { index } = match;
+            const matchLength = match[0].length;
+            const linesBefore = newContent.slice(0, index).split('\n').length;
+            const newTextLines = edit.newText.split('\n').length;
+            const startLine = linesBefore;
+            const endLine = linesBefore + newTextLines - 1;
+            if (minLine === undefined || startLine < minLine)
+                minLine = startLine;
+            if (maxLine === undefined || endLine > maxLine)
+                maxLine = endLine;
+            newContent =
+                newContent.slice(0, index) +
+                    edit.newText +
+                    newContent.slice(index + matchLength);
+            appliedEdits += 1;
+        }
+        else {
+            if (!newContent.includes(edit.oldText)) {
+                unmatchedEdits.push(edit.oldText);
+                continue;
+            }
+            const index = newContent.indexOf(edit.oldText);
+            const linesBefore = newContent.slice(0, index).split('\n').length;
+            const newTextLines = edit.newText.split('\n').length;
+            const startLine = linesBefore;
+            const endLine = linesBefore + newTextLines - 1;
+            if (minLine === undefined || startLine < minLine)
+                minLine = startLine;
+            if (maxLine === undefined || endLine > maxLine)
+                maxLine = endLine;
+            newContent = newContent.replace(edit.oldText, () => edit.newText);
+            appliedEdits += 1;
         }
-        const index = newContent.indexOf(edit.oldText);
-        const linesBefore = newContent.slice(0, index).split('\n').length;
-        const newTextLines = edit.newText.split('\n').length;
-        const startLine = linesBefore;
-        const endLine = linesBefore + newTextLines - 1;
-        if (minLine === undefined || startLine < minLine)
-            minLine = startLine;
-        if (maxLine === undefined || endLine > maxLine)
-            maxLine = endLine;
-        newContent = newContent.replace(edit.oldText, () => edit.newText);
-        appliedEdits += 1;
     }
     const result = {
         content: newContent,
@@ -56,10 +86,10 @@ function applyEdits(content, edits) {
     }
     return result;
 }
-async function handleEditFile(args, signal) {
+export async function handleEditFile(args, signal) {
     const validPath = await validateExistingPath(args.path, signal);
     const content = await fs.readFile(validPath, { encoding: 'utf-8', signal });
-    const { content: newContent, appliedEdits, unmatchedEdits, lineRange, } = applyEdits(content, args.edits);
+    const { content: newContent, appliedEdits, unmatchedEdits, lineRange, } = applyEdits(content, args.edits, args.ignoreWhitespace);
     const structured = {
         ok: true,
         path: validPath,

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

@@ -1,4 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const MOVE_FILE_TOOL: ToolContract;
+export declare function handleMoveFile(args: z.infer<typeof MoveFileInputSchema>, signal?: AbortSignal): Promise<ToolResponse<z.infer<typeof MoveFileOutputSchema>>>;
 export declare function registerMoveFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/move-file.js

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { ErrorCode, isNodeError } from '../lib/errors.js';
+import { ErrorCode, formatUnknownErrorMessage, isNodeError, McpError, } from '../lib/errors.js';
 import { withAbort } from '../lib/fs-helpers.js';
 import { validateExistingPath, validatePathForWrite, } from '../lib/path-validation.js';
 import { MoveFileInputSchema, MoveFileOutputSchema } from '../schemas.js';
@@ -18,28 +18,95 @@ export const MOVE_FILE_TOOL = {
         'On POSIX, an existing destination is silently overwritten; on Windows, rename fails with EEXIST if destination exists.',
     ],
 };
-async function handleMoveFile(args, signal) {
-    const validSource = await validateExistingPath(args.source, signal);
+export async function handleMoveFile(args, signal) {
+    const sources = args.sources ?? (args.source ? [args.source] : []);
+    if (sources.length === 0) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'No sources provided.');
+    }
     const validDest = await validatePathForWrite(args.destination, signal);
-    // Ensure destination parent directory exists
-    await withAbort(fs.mkdir(path.dirname(validDest), { recursive: true }), signal);
+    // Check if destination exists and is a directory
+    let destIsDirectory = false;
     try {
-        await withAbort(fs.rename(validSource, validDest), signal);
+        const stats = await fs.stat(validDest);
+        destIsDirectory = stats.isDirectory();
     }
     catch (error) {
-        if (isNodeError(error) && error.code === 'EXDEV') {
-            // Cross-device link, fallback to copy + delete
-            await withAbort(fs.cp(validSource, validDest, { recursive: true }), signal);
-            await withAbort(fs.rm(validSource, { recursive: true, force: true }), signal);
-        }
-        else {
+        if (isNodeError(error) && error.code !== 'ENOENT') {
             throw error;
         }
     }
-    return buildToolResponse(`Successfully moved ${args.source} to ${args.destination}`, {
-        ok: true,
-        source: validSource,
+    if (sources.length > 1 && !destIsDirectory) {
+        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Destination must be an existing directory when moving multiple files.');
+    }
+    // Ensure destination parent directory exists if it's not an existing directory
+    if (!destIsDirectory) {
+        await withAbort(fs.mkdir(path.dirname(validDest), { recursive: true }), signal);
+    }
+    const movedSources = [];
+    const failed = [];
+    for (const src of sources) {
+        let validSource;
+        try {
+            validSource = await validateExistingPath(src, signal);
+        }
+        catch (error) {
+            failed.push({
+                source: src,
+                error: formatUnknownErrorMessage(error),
+            });
+            continue;
+        }
+        const targetPath = destIsDirectory
+            ? path.join(validDest, path.basename(validSource))
+            : validDest;
+        // Prevent moving a file onto itself
+        if (path.resolve(validSource) === path.resolve(targetPath)) {
+            continue;
+        }
+        // Prevent moving a directory into its own subdirectory
+        // Fixes "Missing validation for moving directory into its own subdirectory" finding
+        if (path.resolve(targetPath).startsWith(path.resolve(validSource) + path.sep)) {
+            failed.push({
+                source: src,
+                error: `Cannot move directory '${src}' into its own subdirectory '${targetPath}'`,
+            });
+            continue;
+        }
+        try {
+            await withAbort(fs.rename(validSource, targetPath), signal);
+            movedSources.push(validSource);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'EXDEV') {
+                // Cross-device link, fallback to copy + delete
+                try {
+                    await withAbort(fs.cp(validSource, targetPath, { recursive: true }), signal);
+                    await withAbort(fs.rm(validSource, { recursive: true, force: true }), signal);
+                    movedSources.push(validSource);
+                }
+                catch (copyError) {
+                    failed.push({
+                        source: src,
+                        error: formatUnknownErrorMessage(copyError),
+                    });
+                }
+            }
+            else {
+                failed.push({
+                    source: src,
+                    error: formatUnknownErrorMessage(error),
+                });
+            }
+        }
+    }
+    const message = failed.length > 0
+        ? `Moved ${movedSources.length} item${movedSources.length === 1 ? '' : 's'}; failed to move ${failed.length} item${failed.length === 1 ? '' : 's'}`
+        : `Successfully moved ${movedSources.length} item${movedSources.length === 1 ? '' : 's'} to ${args.destination}`;
+    return buildToolResponse(message, {
+        ok: failed.length === 0,
+        sources: movedSources,
         destination: validDest,
+        ...(failed.length > 0 ? { failed } : {}),
     });
 }
 export function registerMoveFileTool(server, options = {}) {
@@ -47,19 +114,23 @@ export function registerMoveFileTool(server, options = {}) {
         toolName: 'mv',
         extra,
         timedSignal: {},
-        context: { path: args.source },
+        context: { path: args.source ?? args.sources?.[0] },
         run: (signal) => handleMoveFile(args, signal),
-        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source),
+        onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.source ?? args.sources?.[0]),
     });
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
-        progressMessage: (args) => `🛠 mv: ${path.basename(args.source)} → ${path.basename(args.destination)}`,
+        progressMessage: (args) => {
+            const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
+            const dest = path.basename(args.destination);
+            return `🛠 mv: ${count} item${count === 1 ? '' : 's'} → ${dest}`;
+        },
         completionMessage: (args, result) => {
-            const src = path.basename(args.source);
-            const dst = path.basename(args.destination);
+            const count = (args.source ? 1 : 0) + (args.sources?.length ?? 0);
+            const dest = path.basename(args.destination);
             if (result.isError)
-                return `🛠 mv: ${src} → ${dst} • failed`;
-            return `🛠 mv: ${src} → ${dst} • moved`;
+                return `🛠 mv: ${count} → ${dest} • failed`;
+            return `🛠 mv: ${count} → ${dest} • moved`;
         },
     });
     const validatedHandler = withValidatedArgs(MoveFileInputSchema, wrappedHandler);

package/dist/tools/replace-in-files.d.ts

@@ -1,4 +1,10 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+import type { z } from 'zod';
+import { SearchAndReplaceInputSchema, SearchAndReplaceOutputSchema } from '../schemas.js';
+import { type ToolContract, type ToolRegistrationOptions, type ToolResponse } from './shared.js';
 export declare const SEARCH_AND_REPLACE_TOOL: ToolContract;
+export declare function handleSearchAndReplace(args: z.infer<typeof SearchAndReplaceInputSchema>, signal?: AbortSignal, onProgress?: (progress: {
+    total?: number;
+    current: number;
+}) => void): Promise<ToolResponse<z.infer<typeof SearchAndReplaceOutputSchema>>>;
 export declare function registerSearchAndReplaceTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/replace-in-files.js

@@ -122,7 +122,8 @@ async function processEntry(entryPath, args, regex, maxFileSize, signal, summary
             else {
                 newContent = content.replaceAll(args.searchPattern, () => args.replacement);
             }
-            if (args.dryRun && summary.diff.length < MAX_DIFF_SIZE) {
+            if ((args.dryRun || args.returnDiff) &&
+                summary.diff.length < MAX_DIFF_SIZE) {
                 const patch = createTwoFilesPatch(path.basename(validPath), path.basename(validPath), content, newContent, 'Original', 'Modified');
                 // Only append if it won't exceed the limit too much
                 if (summary.diff.length + patch.length <= MAX_DIFF_SIZE + 1024) {
@@ -201,7 +202,7 @@ function reportReplaceProgress(onProgress, current, force = false) {
         return;
     onProgress({ current });
 }
-async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
+export async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
     const maxFileSize = MAX_TEXT_FILE_SIZE;
     const root = await resolveSearchRoot(args.path, signal);
     const regex = createReplacementRegex(args);
@@ -240,7 +241,9 @@ async function handleSearchAndReplace(args, signal, onProgress = () => { }) {
             ? { changedFiles: summary.changedFiles }
             : {}),
         ...(summary.changedFilesTruncated ? { changedFilesTruncated: true } : {}),
-        ...(args.dryRun && summary.diff ? { diff: summary.diff } : {}),
+        ...((args.dryRun || args.returnDiff) && summary.diff
+            ? { diff: summary.diff }
+            : {}),
         dryRun: args.dryRun,
     });
 }

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,11 +41,11 @@ 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;
 }
 export type ToolResult<T> = ToolResponse<T> | ToolErrorResponse;

package/dist/tools/shared.js

@@ -89,12 +89,6 @@ export function buildResourceLink(params) {
         ...(params.mimeType ? { mimeType: params.mimeType } : {}),
     };
 }
-function buildContentBlock(text, structuredContent, extraContent = []) {
-    return {
-        content: [{ type: 'text', text }, ...extraContent],
-        structuredContent,
-    };
-}
 function resolveDetailedError(error, defaultCode, path) {
     const detailed = createDetailedError(error, path);
     if (detailed.code === ErrorCode.E_UNKNOWN) {
@@ -104,7 +98,10 @@ function resolveDetailedError(error, defaultCode, path) {
     return detailed;
 }
 export function buildToolResponse(text, structuredContent, extraContent = []) {
-    return buildContentBlock(text, structuredContent, extraContent);
+    return {
+        content: [{ type: 'text', text }, ...extraContent],
+        structuredContent,
+    };
 }
 function parseToolArgs(schema, args) {
     const candidate = args === undefined ? {} : args;
@@ -198,22 +195,8 @@ 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 {
-        ...buildContentBlock(text, structuredContent),
+        content: [{ type: 'text', text }],
         isError: true,
     };
 }

package/dist/tools/task-support.js

@@ -134,14 +134,17 @@ function normalizeCallToolResult(value) {
 function getToolResultErrorCode(result) {
     if (!isRecord(result) || result['isError'] !== true)
         return undefined;
-    const structured = result['structuredContent'];
-    if (!isRecord(structured))
+    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 +225,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) {

package/package.json

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