@j0hanz/filesystem-mcp 1.13.1 → 1.14.0

package/dist/tools/shared.js

@@ -6,6 +6,7 @@ import { createDetailedError, ErrorCode, formatDetailedError, getSuggestion, Mcp
 import { createTimedAbortSignal } from '../lib/fs-helpers.js';
 import { withToolDiagnostics } from '../lib/observability.js';
 import { getAllowedDirectories } from '../lib/paths.js';
+import { createBase64JsonCodec } from '../lib/zod-codecs.js';
 export {} from './contract.js';
 const MAX_INLINE_CONTENT_CHARS = parseInt(process.env['FS_CONTEXT_MAX_INLINE_CHARS'] ?? '', 10) || 20_000;
 const MAX_INLINE_PREVIEW_CHARS = 4_000;
@@ -64,7 +65,7 @@ function normalizeToolExecution(tool) {
     }
     return normalized;
 }
-export function shouldStripStructuredOutput() {
+function shouldStripStructuredOutput() {
     return parseTrueEnvFlag(process.env['FS_CONTEXT_STRIP_STRUCTURED']);
 }
 export function maybeStripStructuredContentFromResult(result) {
@@ -133,19 +134,48 @@ function resolveDetailedError(error, defaultCode, path) {
     }
     return detailed;
 }
+export function buildStructuredError(error, defaultCode, path) {
+    const detailed = resolveDetailedError(error, defaultCode, path);
+    return {
+        code: detailed.code,
+        message: detailed.message,
+        ...(detailed.path !== undefined ? { path: detailed.path } : {}),
+        ...(detailed.suggestion !== undefined
+            ? { suggestion: detailed.suggestion }
+            : {}),
+    };
+}
 export function buildToolResponse(text, structuredContent, extraContent = []) {
     return {
         content: [{ type: 'text', text }, ...extraContent],
         structuredContent,
     };
 }
+function validateStructuredContent(toolName, outputSchema, structuredContent) {
+    const parsed = outputSchema.safeParse(structuredContent);
+    if (parsed.success) {
+        return parsed.data;
+    }
+    throw new McpError(ErrorCode.E_UNKNOWN, `Tool "${toolName}" returned invalid structuredContent.`, undefined, { errors: z.treeifyError(parsed.error) });
+}
+function validateToolResponse(toolName, result, outputSchema) {
+    if (!outputSchema)
+        return result;
+    if (!Object.hasOwn(result, 'structuredContent')) {
+        throw new McpError(ErrorCode.E_UNKNOWN, `Tool "${toolName}" returned success without structuredContent.`);
+    }
+    return {
+        ...result,
+        structuredContent: validateStructuredContent(toolName, outputSchema, result.structuredContent),
+    };
+}
 function parseToolArgs(schema, args) {
     const candidate = args === undefined ? {} : args;
     const parsed = schema.safeParse(candidate);
     if (parsed.success) {
         return parsed.data;
     }
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid tool arguments: ${parsed.error.message}`, undefined, { errors: z.treeifyError(parsed.error) });
+    throw new McpError(ErrorCode.E_INVALID_INPUT, `Invalid tool arguments:\n${z.prettifyError(parsed.error)}`, undefined, { errors: z.treeifyError(parsed.error) });
 }
 export function withValidatedArgs(schema, handler) {
     return async (args, extra) => {
@@ -222,7 +252,7 @@ export async function executeToolWithDiagnostics(options) {
     return withToolDiagnostics(options.toolName, () => withToolErrorHandling(async () => {
         const { signal, cleanup } = getToolSignal(options.extra.signal, options.timedSignal);
         try {
-            return await options.run(signal);
+            return validateToolResponse(options.toolName, await options.run(signal), options.outputSchema);
         }
         finally {
             cleanup();
@@ -461,19 +491,16 @@ export function resolvePathOrRoot(pathValue) {
     }
     return root;
 }
+const OffsetCursorSchema = z.strictObject({
+    offset: z.int().min(0),
+});
+const OffsetCursorCodec = createBase64JsonCodec(OffsetCursorSchema);
 export function encodeOffsetCursor(offset) {
-    return Buffer.from(JSON.stringify({ offset })).toString('base64url');
+    return z.encode(OffsetCursorCodec, { offset });
 }
 export function decodeOffsetCursor(cursor) {
     try {
-        const parsed = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf-8'));
-        if (typeof parsed === 'object' &&
-            parsed !== null &&
-            typeof parsed.offset === 'number') {
-            const { offset } = parsed;
-            if (Number.isInteger(offset) && offset >= 0)
-                return offset;
-        }
+        return OffsetCursorCodec.parse(cursor).offset;
     }
     catch {
         // fall through to throw
@@ -488,6 +515,20 @@ export function buildBatchPathContext(paths, unitLabel = 'paths') {
         : '';
     return `${paths.length} ${normalizedLabel} [${first}${extraPaths}]`;
 }
+export function truncateProgressPattern(pattern, maxLength = 40) {
+    if (pattern.length <= maxLength)
+        return pattern;
+    if (pattern.includes('|')) {
+        const segments = pattern.split('|');
+        const first = segments[0] ?? '';
+        const second = segments[1];
+        const preview = second !== undefined ? `${first}|${second}` : first;
+        return preview.length <= maxLength
+            ? `${preview}…`
+            : `${preview.slice(0, maxLength)}…`;
+    }
+    return `${pattern.slice(0, maxLength)}…`;
+}
 export function buildBatchCompletionSuffix(summary, successWord, singularWord) {
     const total = summary?.total ?? 0;
     const failed = summary?.failed ?? 0;

package/dist/tools/stat-many.js

@@ -3,7 +3,7 @@ import { ErrorCode } from '../lib/errors.js';
 import { getMultipleFileInfo } from '../lib/file-operations/metadata.js';
 import { formatBytes, joinLines } from '../config.js';
 import { GetMultipleFileInfoInputSchema, GetMultipleFileInfoOutputSchema, } from '../schemas.js';
-import { buildBatchCompletionSuffix, buildBatchPathContext, buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
+import { buildBatchCompletionSuffix, buildBatchPathContext, buildFileInfoPayload, buildStructuredError, buildToolErrorResponse, buildToolResponse, createBatchProgressCallbacks, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolveFinalProgressCurrent, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
 export const GET_MULTIPLE_FILE_INFO_TOOL = {
     name: 'stat_many',
@@ -14,7 +14,6 @@ export const GET_MULTIPLE_FILE_INFO_TOOL = {
     outputSchema: GetMultipleFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     taskSupport: 'optional',
-    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetail(info) {
     const lines = [
@@ -38,11 +37,13 @@ async function handleGetMultipleFileInfo(args, signal, onProgress) {
     const structuredResults = result.results.map((entry) => ({
         path: entry.path,
         info: entry.info ? buildFileInfoPayload(entry.info) : undefined,
-        error: entry.error,
+        error: entry.error
+            ? buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path)
+            : undefined,
     }));
     const text = result.results
         .map((entry) => entry.error
-        ? `${entry.path}: ${entry.error}`
+        ? `${entry.path}: ${buildStructuredError(entry.error, ErrorCode.E_NOT_FOUND, entry.path).message}`
         : entry.info
             ? formatFileInfoDetail(entry.info)
             : entry.path)
@@ -64,6 +65,7 @@ export function registerGetMultipleFileInfoTool(server, options = {}) {
         return executeToolWithDiagnostics({
             toolName: 'stat_many',
             extra,
+            outputSchema: GetMultipleFileInfoOutputSchema,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: primaryPath },
             run: async (signal) => {

package/dist/tools/stat.js

@@ -15,7 +15,6 @@ export const GET_FILE_INFO_TOOL = {
     outputSchema: GetFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     taskSupport: 'forbidden',
-    nuances: ['Use before read/search when file size/type uncertainty exists.'],
 };
 function formatFileInfoDetails(info) {
     const lines = [
@@ -45,6 +44,7 @@ export function registerGetFileInfoTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'stat',
         extra,
+        outputSchema: GetFileInfoOutputSchema,
         timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
         context: { path: args.path },
         run: (signal) => handleGetFileInfo(args, signal),
@@ -58,7 +58,7 @@ export function registerGetFileInfoTool(server, options = {}) {
             if (result.isError)
                 return `🕮 stat: ${name} • failed`;
             const sc = result.structuredContent;
-            if (!sc.ok || !sc.info)
+            if (!sc.info)
                 return `🕮 stat: ${name} • failed`;
             return `🕮 stat: ${sc.info.name} • ${sc.info.type}, ${formatBytes(sc.info.size)}`;
         },

package/dist/tools/task-support.d.ts

@@ -1,15 +1,8 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
 import type { ToolTaskHandler } from '@modelcontextprotocol/sdk/experimental/tasks/interfaces.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AnySchema, SchemaOutput, ShapeOutput, ZodRawShapeCompat } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import type { RequestTaskStore } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { IconInfo, ToolExtra, ToolResult } from './shared.js';
-export interface TaskContext {
-    taskId: string;
-    toolName?: string | undefined;
-    startTime: number;
-}
-export declare const taskContext: AsyncLocalStorage<TaskContext>;
 type TaskToolExtra = ToolExtra & {
     taskId?: string;
     taskStore?: RequestTaskStore;

package/dist/tools/task-support.js

@@ -7,13 +7,16 @@ import { DEFAULT_TASK_TTL_MS, MAX_CONCURRENT_TASKS, MAX_TASK_TTL_MS, } from '../
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { isRecord } from '../lib/utils.js';
 import { buildToolErrorResponse, maybeStripStructuredContentFromResult, withDefaultIcons, } from './shared.js';
-export const taskContext = new AsyncLocalStorage();
+const taskContext = new AsyncLocalStorage();
 const TASK_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:tasks');
 function publishTaskDiagnostics(event) {
     if (TASK_DIAGNOSTICS_CHANNEL.hasSubscribers) {
         TASK_DIAGNOSTICS_CHANNEL.publish(event);
     }
 }
+function getDynamicProperty(target, key) {
+    return Reflect.get(target, key);
+}
 // --- Type Guards & Helpers ---
 function isExperimentalTaskRegistration(value) {
     if (!isRecord(value))
@@ -22,8 +25,7 @@ function isExperimentalTaskRegistration(value) {
     return (registerToolTask === undefined || typeof registerToolTask === 'function');
 }
 function getExperimentalTaskRegistration(server) {
-    const serverWithExperimental = server;
-    const { experimental } = serverWithExperimental;
+    const experimental = getDynamicProperty(server, 'experimental');
     if (!isRecord(experimental))
         return undefined;
     const { tasks } = experimental;
@@ -32,11 +34,10 @@ function getExperimentalTaskRegistration(server) {
     return tasks;
 }
 function hasTaskToolCapability(server) {
-    const serverRecord = server;
-    const { server: serverRuntime } = serverRecord;
+    const serverRuntime = getDynamicProperty(server, 'server');
     if (!isRecord(serverRuntime))
         return true; // Assume capability if runtime structure is opaque
-    const { getCapabilities } = serverRuntime;
+    const getCapabilities = getDynamicProperty(serverRuntime, 'getCapabilities');
     if (typeof getCapabilities !== 'function')
         return true;
     const capabilities = getCapabilities.call(serverRuntime);

package/dist/tools/tree.js

@@ -14,7 +14,6 @@ export const TREE_TOOL = {
     outputSchema: TreeOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
     taskSupport: 'optional',
-    gotchas: ['`maxDepth=0` returns only the root node.'],
 };
 async function handleTree(args, signal, onProgress) {
     const basePath = resolvePathOrRoot(args.path);
@@ -45,6 +44,7 @@ export function registerTreeTool(server, options = {}) {
         return executeToolWithDiagnostics({
             toolName: 'tree',
             extra,
+            outputSchema: TreeOutputSchema,
             timedSignal: { timeoutMs: DEFAULT_SEARCH_TIMEOUT_MS },
             context: { path: targetPath },
             run: async (signal) => {

package/dist/tools/write-file.js

@@ -14,9 +14,6 @@ export const WRITE_FILE_TOOL = {
     inputSchema: WriteFileInputSchema,
     outputSchema: WriteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
-    gotchas: [
-        '`write` replaces ALL existing content — use `edit` for partial updates.',
-    ],
     taskSupport: 'forbidden',
 };
 async function handleWriteFile(args, signal) {
@@ -35,6 +32,7 @@ export function registerWriteFileTool(server, options = {}) {
     const handler = (args, extra) => executeToolWithDiagnostics({
         toolName: 'write',
         extra,
+        outputSchema: WriteFileOutputSchema,
         timedSignal: {},
         context: { path: args.path },
         run: (signal) => handleWriteFile(args, signal),
@@ -48,8 +46,6 @@ export function registerWriteFileTool(server, options = {}) {
             if (result.isError)
                 return `🛠 write: ${name} • failed`;
             const sc = result.structuredContent;
-            if (!sc.ok)
-                return `🛠 write: ${name} • failed`;
             return `🛠 write: ${name} • ${formatBytes(sc.bytesWritten ?? 0)}`;
         },
     });

package/dist/tools.d.ts

@@ -1,6 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type ToolContract } from './tools/contract.js';
 import type { ToolRegistrationOptions } from './tools/shared.js';
-export { buildToolErrorResponse, buildToolResponse } from './tools/shared.js';
 export declare const ALL_TOOLS: ToolContract[];
 export declare function registerAllTools(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools.js

@@ -17,7 +17,6 @@ import { GET_MULTIPLE_FILE_INFO_TOOL, registerGetMultipleFileInfoTool, } from '.
 import { GET_FILE_INFO_TOOL, registerGetFileInfoTool } from './tools/stat.js';
 import { registerTreeTool, TREE_TOOL } from './tools/tree.js';
 import { registerWriteFileTool, WRITE_FILE_TOOL } from './tools/write-file.js';
-export { buildToolErrorResponse, buildToolResponse } from './tools/shared.js';
 const TOOL_ENTRIES = [
     {
         contract: LIST_ALLOWED_DIRECTORIES_TOOL,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "A local filesystem MCP server that lets LLMs and AI agents read, write, search, diff, patch, and manage files safely and efficiently. Built for reliable, structured, and controlled filesystem interaction.",
   "type": "module",
@@ -40,6 +40,7 @@
     "test": "node scripts/tasks.mjs test",
     "test:fast": "node --test --import tsx/esm src/__tests__/**/*.test.ts node-tests/**/*.test.ts",
     "test:coverage": "node scripts/tasks.mjs test --coverage",
+    "inspector:smoke": "node scripts/inspector-smoke.mjs",
     "knip": "knip",
     "knip:fix": "knip --fix",
     "inspector": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder}",
@@ -86,17 +87,16 @@
     "@eslint/js": "^10.0.1",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/node": "^24",
-    "eslint": "^10.0.2",
+    "eslint": "^10.0.3",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-de-morgan": "^2.1.1",
     "eslint-plugin-depend": "^1.5.0",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "jscpd": "^4.0.8",
-    "knip": "^5.85.0",
+    "knip": "^5.86.0",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.56.1"
+    "typescript-eslint": "^8.57.0"
   },
   "engines": {
     "node": ">=24"