@j0hanz/filesystem-mcp 1.19.1 → 2.1.0

package/dist/tools/create.js

@@ -0,0 +1,124 @@
+import { basename, dirname } from 'node:path';
+import * as z from 'zod/v4';
+import { ErrorCode } from '../core/errors.js';
+import { buildFileResourceLink, buildFileResourceUri } from '../core/file-uri.js';
+import { detectMimeFromContent } from '../core/mime.js';
+import { countLines } from '../core/read.js';
+import { FileKind, IsoDateTime, NonNegInt, PathFailureSchema, RequiredPath, } from '../core/schema.js';
+import { getMaxTextFileSize } from '../core/util.js';
+import { runOverPaths } from './batch.js';
+import { defineTool } from './define.js';
+const CreateFileItemSchema = z.strictObject({
+    path: RequiredPath.describe('Absolute path where the file will be created'),
+    content: z
+        .string()
+        .refine((val) => val.length <= getMaxTextFileSize(), {
+        message: 'Content exceeds maximum allowed text file size',
+    })
+        .describe('Text content to write, verbatim.'),
+});
+const CreateFileResultSchema = z.strictObject({
+    path: z.string().describe('Resolved absolute path of the created file'),
+    size: NonNegInt.describe('File size in bytes after writing'),
+    lineCount: NonNegInt.describe('Number of lines in the written file'),
+    mimeType: z.string().describe('Detected MIME type of the file'),
+    kind: FileKind.describe('Broad file kind: text, binary, image, audio, or pdf'),
+    resourceUri: z
+        .string()
+        .describe('Resource URI pointing to the created file content in the resource store'),
+    created: IsoDateTime.describe('File creation timestamp (ISO 8601 UTC)'),
+    modified: IsoDateTime.describe('File last-modification timestamp (ISO 8601 UTC)'),
+});
+const CreateInputSchema = z.strictObject({
+    files: z
+        .array(CreateFileItemSchema)
+        .min(1)
+        .max(100)
+        .describe('List of files to create (max 100); each entry requires path and content'),
+});
+const CreateOutputSchema = z.strictObject({
+    files: z.array(CreateFileResultSchema).describe('Successfully created files'),
+    failures: z
+        .array(PathFailureSchema)
+        .optional()
+        .describe('Files that failed to create with per-file error details'),
+});
+export const CREATE = defineTool({
+    name: 'create',
+    title: 'Create Files',
+    description: 'Create one or more files (max 100), writing or overwriting content and creating parent directories as needed. ' +
+        'Pass files: [{ path, content }] — there is no single-path form. ' +
+        'Silently overwrites existing files — read first if you need to preserve existing content.',
+    input: CreateInputSchema,
+    output: CreateOutputSchema,
+    annotations: {
+        readOnlyHint: false,
+        idempotentHint: false,
+        destructiveHint: true,
+        openWorldHint: false,
+    },
+    accessPaths: (args) => args.files.map((f) => f.path),
+    run: async (args, ctx) => {
+        const batch = await runOverPaths({ files: args.files }, ctx, async ({ path, override }) => {
+            const content = override?.content ?? '';
+            await ctx.fs.mkdir(dirname(path), { recursive: true });
+            const { validPath } = await ctx.fs.writeFile(path, content, {
+                encoding: 'utf-8',
+                signal: ctx.signal,
+            });
+            const { stats: fileStats } = await ctx.fs.stat(path, { signal: ctx.signal });
+            const bytesWritten = Buffer.byteLength(content, 'utf-8');
+            const lineCount = countLines(content);
+            const mimeInfo = detectMimeFromContent(validPath, content);
+            const resourceUri = buildFileResourceUri(validPath);
+            const file = {
+                path: validPath,
+                size: bytesWritten,
+                lineCount,
+                mimeType: mimeInfo.mimeType,
+                kind: mimeInfo.kind,
+                resourceUri,
+                created: fileStats.birthtime.toISOString(),
+                modified: fileStats.mtime.toISOString(),
+            };
+            return ctx.resourceStore
+                ? {
+                    file,
+                    resourceLink: buildFileResourceLink(validPath, mimeInfo.mimeType, bytesWritten),
+                }
+                : { file };
+        }, { defaultErrorCode: ErrorCode.UNKNOWN });
+        const results = [];
+        const failures = [];
+        const links = [];
+        for (const r of batch.results) {
+            if ('error' in r) {
+                failures.push({ path: r.path, error: r.error });
+                continue;
+            }
+            results.push(r.value.file);
+            if (r.value.resourceLink)
+                links.push(r.value.resourceLink);
+        }
+        const structured = {
+            files: results,
+            ...(failures.length > 0 ? { failures } : {}),
+        };
+        // No `text` on purpose. The one-line roster this used to build named the
+        // paths and dropped every per-file size, line count and error the caller
+        // asked `create` for. Supplying no text makes this a data tool, so
+        // `define.ts` renders the JSON and keeps it in `structuredContent`.
+        if (links.length > 0) {
+            return { structured, resources: links };
+        }
+        return { structured };
+    },
+    progress: (args) => ({
+        label: 'Create',
+        subject: args.files.length === 1
+            ? basename(args.files[0]?.path ?? '')
+            : `${String(args.files.length)} files`,
+    }),
+    defaultErrorCode: ErrorCode.UNKNOWN,
+});
+//# sourceMappingURL=create.js.map

package/dist/tools/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","sourceRoot":"","sources":["../../src/tools/create.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE9C,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAClF,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,QAAQ,EACR,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,oBAAoB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC1C,IAAI,EAAE,YAAY,CAAC,QAAQ,CAAC,8CAA8C,CAAC;IAC3E,OAAO,EAAE,CAAC;SACP,MAAM,EAAE;SACR,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,kBAAkB,EAAE,EAAE;QACnD,OAAO,EAAE,gDAAgD;KAC1D,CAAC;SACD,QAAQ,CAAC,kCAAkC,CAAC;CAChD,CAAC,CAAC;AAEH,MAAM,sBAAsB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4CAA4C,CAAC;IACvE,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,kCAAkC,CAAC;IAC5D,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,qCAAqC,CAAC;IACpE,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;IAC/D,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,qDAAqD,CAAC;IAC9E,WAAW,EAAE,CAAC;SACX,MAAM,EAAE;SACR,QAAQ,CAAC,yEAAyE,CAAC;IACtF,OAAO,EAAE,WAAW,CAAC,QAAQ,CAAC,wCAAwC,CAAC;IACvE,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,iDAAiD,CAAC;CAClF,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,CAAC,CAAC,YAAY,CAAC;IACvC,KAAK,EAAE,CAAC;SACL,KAAK,CAAC,oBAAoB,CAAC;SAC3B,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,GAAG,CAAC;SACR,QAAQ,CAAC,yEAAyE,CAAC;CACvF,CAAC,CAAC;AAIH,MAAM,kBAAkB,GAAG,CAAC,CAAC,YAAY,CAAC;IACxC,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,QAAQ,CAAC,4BAA4B,CAAC;IAC7E,QAAQ,EAAE,CAAC;SACR,KAAK,CAAC,iBAAiB,CAAC;SACxB,QAAQ,EAAE;SACV,QAAQ,CAAC,yDAAyD,CAAC;CACvE,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,MAAM,GAAG,UAAU,CAAC;IAC/B,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,cAAc;IACrB,WAAW,EACT,gHAAgH;QAChH,kEAAkE;QAClE,2FAA2F;IAC7F,KAAK,EAAE,iBAAiB;IACxB,MAAM,EAAE,kBAAkB;IAC1B,WAAW,EAAE;QACX,YAAY,EAAE,KAAK;QACnB,cAAc,EAAE,KAAK;QACrB,eAAe,EAAE,IAAI;QACrB,aAAa,EAAE,KAAK;KACrB;IACD,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACpD,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,KAAK,GAAG,MAAM,YAAY,CAI9B,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,EACrB,GAAG,EACH,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE;YAC3B,MAAM,OAAO,GAAG,QAAQ,EAAE,OAAO,IAAI,EAAE,CAAC;YAExC,MAAM,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAEvD,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE;gBAC1D,QAAQ,EAAE,OAAO;gBACjB,MAAM,EAAE,GAAG,CAAC,MAAM;aACnB,CAAC,CAAC;YAEH,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YAC7E,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACzD,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC;YACtC,MAAM,QAAQ,GAAG,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAE3D,MAAM,WAAW,GAAG,oBAAoB,CAAC,SAAS,CAAC,CAAC;YACpD,MAAM,IAAI,GAAqB;gBAC7B,IAAI,EAAE,SAAS;gBACf,IAAI,EAAE,YAAY;gBAClB,SAAS;gBACT,QAAQ,EAAE,QAAQ,CAAC,QAAQ;gBAC3B,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,WAAW;gBACX,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,WAAW,EAAE;gBAC1C,QAAQ,EAAE,SAAS,CAAC,KAAK,CAAC,WAAW,EAAE;aACxC,CAAC;YAEF,OAAO,GAAG,CAAC,aAAa;gBACtB,CAAC,CAAC;oBACE,IAAI;oBACJ,YAAY,EAAE,qBAAqB,CAAC,SAAS,EAAE,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;iBAChF;gBACH,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QACf,CAAC,EACD,EAAE,gBAAgB,EAAE,SAAS,CAAC,OAAO,EAAE,CACxC,CAAC;QAEF,MAAM,OAAO,GAAuB,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAwB,EAAE,CAAC;QACzC,MAAM,KAAK,GAAmB,EAAE,CAAC;QACjC,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YAC9B,IAAI,OAAO,IAAI,CAAC,EAAE,CAAC;gBACjB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;gBAChD,SAAS;YACX,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3B,IAAI,CAAC,CAAC,KAAK,CAAC,YAAY;gBAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;QAC7D,CAAC;QAED,MAAM,UAAU,GAAG;YACjB,KAAK,EAAE,OAAO;YACd,GAAG,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7C,CAAC;QACF,yEAAyE;QACzE,yEAAyE;QACzE,mEAAmE;QACnE,oEAAoE;QACpE,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;QAC1C,CAAC;QAED,OAAO,EAAE,UAAU,EAAE,CAAC;IACxB,CAAC;IACD,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACnB,KAAK,EAAE,QAAQ;QACf,OAAO,EACL,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YACrB,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC;YACrC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ;KAC3C,CAAC;IACF,gBAAgB,EAAE,SAAS,CAAC,OAAO;CACpC,CAAC,CAAC","sourcesContent":["import type { ContentBlock } from '@modelcontextprotocol/server';\n\nimport { basename, dirname } from 'node:path';\n\nimport * as z from 'zod/v4';\n\nimport { ErrorCode } from '../core/errors.js';\nimport { buildFileResourceLink, buildFileResourceUri } from '../core/file-uri.js';\nimport { detectMimeFromContent } from '../core/mime.js';\nimport { countLines } from '../core/read.js';\nimport {\n  FileKind,\n  IsoDateTime,\n  NonNegInt,\n  PathFailureSchema,\n  RequiredPath,\n} from '../core/schema.js';\nimport { getMaxTextFileSize } from '../core/util.js';\nimport { runOverPaths } from './batch.js';\nimport { defineTool } from './define.js';\n\nconst CreateFileItemSchema = z.strictObject({\n  path: RequiredPath.describe('Absolute path where the file will be created'),\n  content: z\n    .string()\n    .refine((val) => val.length <= getMaxTextFileSize(), {\n      message: 'Content exceeds maximum allowed text file size',\n    })\n    .describe('Text content to write, verbatim.'),\n});\n\nconst CreateFileResultSchema = z.strictObject({\n  path: z.string().describe('Resolved absolute path of the created file'),\n  size: NonNegInt.describe('File size in bytes after writing'),\n  lineCount: NonNegInt.describe('Number of lines in the written file'),\n  mimeType: z.string().describe('Detected MIME type of the file'),\n  kind: FileKind.describe('Broad file kind: text, binary, image, audio, or pdf'),\n  resourceUri: z\n    .string()\n    .describe('Resource URI pointing to the created file content in the resource store'),\n  created: IsoDateTime.describe('File creation timestamp (ISO 8601 UTC)'),\n  modified: IsoDateTime.describe('File last-modification timestamp (ISO 8601 UTC)'),\n});\n\nconst CreateInputSchema = z.strictObject({\n  files: z\n    .array(CreateFileItemSchema)\n    .min(1)\n    .max(100)\n    .describe('List of files to create (max 100); each entry requires path and content'),\n});\n\ntype CreateFailureItem = z.infer<typeof PathFailureSchema>;\n\nconst CreateOutputSchema = z.strictObject({\n  files: z.array(CreateFileResultSchema).describe('Successfully created files'),\n  failures: z\n    .array(PathFailureSchema)\n    .optional()\n    .describe('Files that failed to create with per-file error details'),\n});\n\ntype CreateFileResult = z.infer<typeof CreateFileResultSchema>;\n\nexport const CREATE = defineTool({\n  name: 'create',\n  title: 'Create Files',\n  description:\n    'Create one or more files (max 100), writing or overwriting content and creating parent directories as needed. ' +\n    'Pass files: [{ path, content }] — there is no single-path form. ' +\n    'Silently overwrites existing files — read first if you need to preserve existing content.',\n  input: CreateInputSchema,\n  output: CreateOutputSchema,\n  annotations: {\n    readOnlyHint: false,\n    idempotentHint: false,\n    destructiveHint: true,\n    openWorldHint: false,\n  },\n  accessPaths: (args) => args.files.map((f) => f.path),\n  run: async (args, ctx) => {\n    const batch = await runOverPaths<\n      { content: string },\n      { file: CreateFileResult; resourceLink?: ContentBlock }\n    >(\n      { files: args.files },\n      ctx,\n      async ({ path, override }) => {\n        const content = override?.content ?? '';\n\n        await ctx.fs.mkdir(dirname(path), { recursive: true });\n\n        const { validPath } = await ctx.fs.writeFile(path, content, {\n          encoding: 'utf-8',\n          signal: ctx.signal,\n        });\n\n        const { stats: fileStats } = await ctx.fs.stat(path, { signal: ctx.signal });\n        const bytesWritten = Buffer.byteLength(content, 'utf-8');\n        const lineCount = countLines(content);\n        const mimeInfo = detectMimeFromContent(validPath, content);\n\n        const resourceUri = buildFileResourceUri(validPath);\n        const file: CreateFileResult = {\n          path: validPath,\n          size: bytesWritten,\n          lineCount,\n          mimeType: mimeInfo.mimeType,\n          kind: mimeInfo.kind,\n          resourceUri,\n          created: fileStats.birthtime.toISOString(),\n          modified: fileStats.mtime.toISOString(),\n        };\n\n        return ctx.resourceStore\n          ? {\n              file,\n              resourceLink: buildFileResourceLink(validPath, mimeInfo.mimeType, bytesWritten),\n            }\n          : { file };\n      },\n      { defaultErrorCode: ErrorCode.UNKNOWN },\n    );\n\n    const results: CreateFileResult[] = [];\n    const failures: CreateFailureItem[] = [];\n    const links: ContentBlock[] = [];\n    for (const r of batch.results) {\n      if ('error' in r) {\n        failures.push({ path: r.path, error: r.error });\n        continue;\n      }\n      results.push(r.value.file);\n      if (r.value.resourceLink) links.push(r.value.resourceLink);\n    }\n\n    const structured = {\n      files: results,\n      ...(failures.length > 0 ? { failures } : {}),\n    };\n    // No `text` on purpose. The one-line roster this used to build named the\n    // paths and dropped every per-file size, line count and error the caller\n    // asked `create` for. Supplying no text makes this a data tool, so\n    // `define.ts` renders the JSON and keeps it in `structuredContent`.\n    if (links.length > 0) {\n      return { structured, resources: links };\n    }\n\n    return { structured };\n  },\n  progress: (args) => ({\n    label: 'Create',\n    subject:\n      args.files.length === 1\n        ? basename(args.files[0]?.path ?? '')\n        : `${String(args.files.length)} files`,\n  }),\n  defaultErrorCode: ErrorCode.UNKNOWN,\n});\n"]}

package/dist/tools/define.d.ts

@@ -0,0 +1,102 @@
+import type { AuthInfo, ClientCapabilities, ContentBlock, InputRequiredResult, McpServer, Notification, RegisteredTool, RequestMeta, RequestStateAccessor, ToolAnnotations } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
+import { ErrorCode } from '../core/errors.js';
+import type { ProgressCtx } from '../core/fmt.js';
+import { GuardedFileSystem } from '../core/fs.js';
+import type { LoggingLevel } from '../core/observability.js';
+import type { PageSnapshotStore } from '../core/page-store.js';
+import type { PathGuard } from '../core/path.js';
+import type { ResourceStore } from '../core/store.js';
+export interface ToolCtx {
+    readonly signal: AbortSignal;
+    readonly sessionId?: string;
+    readonly authInfo?: AuthInfo;
+    readonly _meta?: RequestMeta | undefined;
+    readonly fs: GuardedFileSystem;
+    readonly pageStore: PageSnapshotStore;
+    readonly resourceStore: ResourceStore | undefined;
+    /** Emits a log line to stderr via `Logger.emit`, gated by `LOG_LEVEL`. */
+    readonly log?: (level: LoggingLevel, data: unknown, logger?: string) => void;
+    readonly sendNotification?: (notification: Notification) => Promise<void>;
+    readonly onProgress?: (params: {
+        current: number;
+        total?: number;
+    }) => void;
+    /**
+     * Multi-round-trip `inputResponses` carried by a retried `tools/call`
+     * (protocol revision 2026-07-28); `undefined` on the first round. Bare,
+     * unvalidated client values — handlers read them through
+     * `readAcceptedConfirm`.
+     */
+    readonly inputResponses?: Record<string, unknown> | undefined;
+    /**
+     * Reads the verified multi-round-trip `requestState` for the current round:
+     * the decoded `PendingState` the `requestStateCodec` verified, or `undefined`
+     * when the round carried no state (the first round). `undefined` when no
+     * live request context is available.
+     */
+    readonly requestState?: RequestStateAccessor | undefined;
+    /**
+     * What the connected client declared it can do, or `undefined` when this
+     * connection cannot say. Read by the `input_required` flows: an embedded
+     * elicitation sent to a client that never declared `elicitation` is rejected
+     * by the SDK with `-32021` before it reaches the wire, so the handlers check
+     * first and answer with an actionable tool error instead.
+     *
+     * Two sources, because the eras differ: a legacy connection negotiated them
+     * at `initialize` (`Server.getClientCapabilities()`), a modern one carries
+     * them per request in the `_meta` envelope and never runs `initialize` at
+     * all. `undefined` means "cannot tell" — never "no capabilities".
+     */
+    readonly clientCapabilities?: ClientCapabilities | undefined;
+    readonly server?: McpServer;
+}
+interface ToolDeps {
+    readonly server: McpServer;
+    readonly pathGuard: PathGuard;
+    readonly pageStore: PageSnapshotStore;
+    readonly resourceStore: ResourceStore | undefined;
+}
+interface RunResult<T> {
+    readonly structured: T;
+    readonly text?: string;
+    readonly resources?: ContentBlock[];
+}
+/**
+ * `ToolAnnotations` with `readOnlyHint` required. It is optional in the SDK, but
+ * MUTATING_TOOL_NAMES derives the `--read-only` gate from it, so a tool that
+ * forgets it must be a compile error rather than a silent reclassification.
+ */
+type DeclaredAnnotations = ToolAnnotations & {
+    readonly readOnlyHint: boolean;
+};
+export interface ToolDef<I extends z.ZodType, O extends z.ZodType> {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    readonly input: I;
+    readonly output: O;
+    readonly annotations: DeclaredAnnotations;
+    readonly timeoutMs?: number;
+    readonly progress?: (args: z.infer<I>) => ProgressCtx;
+    readonly progressDone?: (args: z.infer<I>, result: z.infer<O>) => Partial<ProgressCtx>;
+    readonly defaultErrorCode?: ErrorCode;
+    /**
+     * The filesystem paths this tool will operate on, extracted from its parsed
+     * args. The executor runs an access-grant pre-check over these BEFORE `run`
+     * (R7): any path outside the granted roots yields an `input_required`
+     * round-trip requesting a grant, and nothing is touched until the client
+     * retries with an accepted grant (R8). Omit for tools that do not operate on
+     * caller-supplied filesystem paths.
+     */
+    readonly accessPaths?: (args: z.infer<I>) => readonly string[];
+    readonly run: (args: z.infer<I>, ctx: ToolCtx) => Promise<RunResult<z.infer<O>> | InputRequiredResult>;
+}
+export interface DefinedTool {
+    readonly name: string;
+    readonly annotations: DeclaredAnnotations;
+    register(deps: ToolDeps): RegisteredTool;
+}
+export declare function defineTool<I extends z.ZodType, O extends z.ZodType>(def: ToolDef<I, O>): DefinedTool;
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/tools/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/tools/define.ts"],"names":[],"mappings":"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"}

package/dist/tools/define.js

@@ -0,0 +1,404 @@
+import { CLIENT_CAPABILITIES_META_KEY, fromJsonSchema, isInputRequiredResult, } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
+import { ErrorCode, formatUnknownErrorMessage, Problem } from '../core/errors.js';
+import { plainMessage } from '../core/fmt.js';
+import { GuardedFileSystem } from '../core/fs.js';
+import { confirmInput, multiSelectInput, pendingRoundTrip, readAcceptedConfirm, readAcceptedMultiChoice, } from '../core/input-required.js';
+import { Logger } from '../core/observability.js';
+import { isSamePath } from '../core/path-utils.js';
+import { McpProgressSink, ProgressSession } from './progress.js';
+function toToolCtx(ctx, deps) {
+    if (!ctx) {
+        const signal = new AbortController().signal;
+        return {
+            signal,
+            fs: new GuardedFileSystem(deps.pathGuard),
+            pageStore: deps.pageStore,
+            resourceStore: deps.resourceStore,
+            server: deps.server,
+        };
+    }
+    // Envelope first, accessor second — the two eras carry this differently.
+    // A modern request states the capabilities in its own `_meta` envelope; a
+    // legacy connection fixed them at `initialize` and has no envelope at all.
+    // The deprecated accessor still answers for both today (the SDK backfills it
+    // per request from the validated envelope on modern instances), but reading
+    // the envelope directly is the supported path, so it leads: when the accessor
+    // goes, legacy degrades to "cannot tell", which fails open to the behavior
+    // that predates this check.
+    //
+    // The cast is the SDK's shipped `RequestMetaEnvelope` declaration collapsing
+    // to `{}` — the reserved keys survive at runtime but not in the .d.ts, so the
+    // key constant cannot index the declared type.
+    const envelope = ctx.mcpReq.envelope;
+    const clientCapabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY] ??
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- the only source of client capabilities on a legacy connection, where no envelope exists.
+        deps.server.server.getClientCapabilities();
+    return {
+        signal: ctx.mcpReq.signal,
+        ...(ctx.sessionId ? { sessionId: ctx.sessionId } : {}),
+        ...(ctx.http?.authInfo ? { authInfo: ctx.http.authInfo } : {}),
+        ...(ctx.mcpReq._meta ? { _meta: ctx.mcpReq._meta } : {}),
+        fs: new GuardedFileSystem(deps.pathGuard),
+        pageStore: deps.pageStore,
+        resourceStore: deps.resourceStore,
+        sendNotification: async (notification) => ctx.mcpReq.notify(notification),
+        inputResponses: ctx.mcpReq.inputResponses,
+        requestState: ctx.mcpReq.requestState,
+        ...(clientCapabilities ? { clientCapabilities } : {}),
+        server: deps.server,
+    };
+}
+function resolveProgressCtx(def, args) {
+    if (!def.progress)
+        return { label: def.title };
+    try {
+        return def.progress(args);
+    }
+    catch (err) {
+        Logger.warn(`resolveProgressCtx: ${def.name}.progress threw: ${String(err)}`);
+        return { label: def.title };
+    }
+}
+function composeSignal(base, timeoutMs) {
+    if (!timeoutMs)
+        return base;
+    return AbortSignal.any([base, AbortSignal.timeout(timeoutMs)]);
+}
+/**
+ * A batch result where every path failed. The call produced no work at all, so
+ * it is a failed call — `isError` must say so. Partial failure is deliberately
+ * NOT an error: the per-path entries carry which paths failed and the succeeded
+ * ones really were done.
+ *
+ * Two result shapes reach here. Most batch tools carry a `summary`. `create` and
+ * `move` do not: they publish `{files|moves, failures, skipped}` (see
+ * create.ts's CreateOutputSchema and move.ts's MoveOutputSchema), so a
+ * summary-only check reported a fully-denied write as a successful call. Both
+ * shapes are handled here rather than by growing the two output schemas, which
+ * are the client-facing contract.
+ */
+function isTotalBatchFailure(structured) {
+    if (typeof structured !== 'object' || structured === null)
+        return false;
+    const result = structured;
+    const { summary } = result;
+    if (typeof summary?.total === 'number') {
+        return summary.total > 0 && summary.failed === summary.total;
+    }
+    const len = (value) => (Array.isArray(value) ? value.length : 0);
+    if (len(result.failures) === 0)
+        return false;
+    // A skipped entry is work the caller asked to skip, not work that failed —
+    // a self-move that was silently dropped means the call did something.
+    return len(result.files) + len(result.moves) + len(result.skipped) === 0;
+}
+/**
+ * Claude Code — and any client that treats `structuredContent` as the canonical
+ * model view — discards the `text` blocks when `structuredContent` is present,
+ * showing the model `JSON.stringify(structuredContent)` instead. A tool that
+ * authored a text result (list's ASCII tree, read's file) meant that text for
+ * the model, so it ships its metadata under `_meta`, which no client renders in
+ * place of the content. Tools with no `text` keep `structuredContent`: the JSON
+ * *is* their model-facing view.
+ */
+function buildSuccessResponse(result) {
+    const hasText = result.text !== undefined;
+    const text = result.text ?? JSON.stringify(result.structured);
+    const content = [{ type: 'text', text }, ...(result.resources ?? [])];
+    return {
+        content,
+        ...(hasText
+            ? // Safe because every `ToolDef.output` is a Zod object schema, so
+                // `structured` is always a plain object. Constraining `O` to prove it
+                // is not worth the cost: the bound has to thread through five generic
+                // sites and still loses to `exactOptionalPropertyTypes` variance on
+                // `RunResult`'s optional fields.
+                { _meta: result.structured }
+            : { structuredContent: result.structured }),
+        ...(isTotalBatchFailure(result.structured) ? { isError: true } : {}),
+    };
+}
+class ToolExecutor {
+    signal;
+    def;
+    parsedArgs;
+    toolCtx;
+    #progressClosed = false;
+    #progressCtx;
+    #mcpSink;
+    #progressSession;
+    constructor(toolName, ctx, def, parsedArgs) {
+        this.def = def;
+        this.parsedArgs = parsedArgs;
+        this.signal = composeSignal(ctx.signal, def.timeoutMs);
+        this.#progressCtx = resolveProgressCtx(def, parsedArgs);
+        const sinks = [];
+        if (ctx._meta?.progressToken !== undefined && ctx.sendNotification !== undefined) {
+            this.#mcpSink = new McpProgressSink(toolName, ctx._meta.progressToken, ctx.sendNotification);
+            sinks.push(this.#mcpSink);
+        }
+        const isTest = process.env['NODE_ENV'] === 'test' || process.execArgv.includes('--test');
+        this.#progressSession = new ProgressSession({
+            label: this.#progressCtx.label,
+            sinks,
+            ...(isTest ? { rateLimitMs: 0 } : {}),
+        });
+        this.toolCtx = {
+            ...ctx,
+            signal: this.signal,
+            log: (level, data, logger) => {
+                const msg = typeof data === 'string' ? data : String(data);
+                const prefix = logger ? `[${logger}] ` : '';
+                Logger.emit(level, `${prefix}${msg}`);
+            },
+            onProgress: (p) => {
+                this.#tick(p);
+            },
+        };
+    }
+    #tick(p) {
+        if (this.#progressClosed)
+            return;
+        const tickCtx = {
+            ...this.#progressCtx,
+            current: p.current,
+            ...(p.total !== undefined ? { total: p.total } : {}),
+        };
+        this.#progressSession.set({ ...p, message: plainMessage('tick', tickCtx) });
+    }
+    async #closeWithDone(message) {
+        this.#progressClosed = true;
+        this.#progressSession.complete(message);
+        if (this.#mcpSink)
+            await this.#mcpSink.flush();
+    }
+    async #closeWithFail(error, message) {
+        this.#progressClosed = true;
+        this.#progressSession.fail(error, message);
+        if (this.#mcpSink)
+            await this.#mcpSink.flush();
+    }
+    async #flushProgress() {
+        if (this.#mcpSink)
+            await this.#mcpSink.flush();
+    }
+    async completeProgress(result) {
+        const doneCtx = this.def.progressDone
+            ? { ...this.#progressCtx, ...this.def.progressDone(this.parsedArgs, result) }
+            : this.#progressCtx;
+        await this.#closeWithDone(plainMessage('done', doneCtx));
+    }
+    async failProgress(error) {
+        const errMsg = formatUnknownErrorMessage(error);
+        const message = plainMessage('fail', { ...this.#progressCtx, error: errMsg });
+        await this.#closeWithFail(error, message);
+        const { text: errorText } = Problem.toText(error, this.def.defaultErrorCode ?? ErrorCode.UNKNOWN);
+        return {
+            content: [{ type: 'text', text: errorText }],
+            isError: true,
+        };
+    }
+    /**
+     * Access-grant pre-check (R7/R8/R9). Before `run` touches the filesystem,
+     * ask PathGuard which of the tool's declared paths are out-of-root and
+     * grantable. If any are and this round carries no verified `requestState`,
+     * return `input_required` (nothing is read or written — R7). On retry, the
+     * verified state must bind this grant set (R9); apply each accepted grant for
+     * the session (R8) and proceed. A declined or ungrantable path is left for
+     * `validateAccess` to fail closed during the operation. Returns `undefined`
+     * when no round-trip is needed and any applicable grants have been applied.
+     */
+    async precheckGrant() {
+        const extract = this.def.accessPaths;
+        if (!extract)
+            return undefined;
+        const paths = extract(this.parsedArgs);
+        if (paths.length === 0)
+            return undefined;
+        const grantDirs = await this.toolCtx.fs.pathGuard.precheckAccess(paths);
+        if (grantDirs.length === 0)
+            return undefined;
+        // One grant dir: a single boolean confirm. Multiple: one multi-select
+        // elicitation so the client picks the subset to allow in one round-trip
+        // (N dirs → 1 round-trip, not N). `pendingRoundTrip` still binds
+        // `paths: grantDirs` sorted, so R9 path-binding is unaffected.
+        const multi = grantDirs.length > 1;
+        const round = await pendingRoundTrip({
+            op: 'grant',
+            pending: grantDirs,
+            requestState: this.toolCtx.requestState,
+            clientCapabilities: this.toolCtx.clientCapabilities,
+            buildInputs: (dirs) => multi
+                ? [
+                    multiSelectInput('grant', 'Grant filesystem access to these directories? Select the ones to allow.', dirs.map((d) => ({ value: d, title: d }))),
+                ]
+                : dirs.map((dir, i) => confirmInput(`confirm_${i}`, `Grant filesystem access to "${dir}"?`)),
+        });
+        if (round !== undefined)
+            return round;
+        // Apply accepted grants for the session (R8). Declined/missing dirs are
+        // skipped here; their paths fail with ACCESS_DENIED during the operation.
+        //
+        // No list-changed notification follows: a grant widens the allowed roots,
+        // and no resource list reads them. The instructions resource has a fixed
+        // URI, the result template lists the ResourceStore, and the file template
+        // lists nothing at all (see resources.ts). Notifying here only bought the
+        // client a round trip to re-fetch a list that could not have changed.
+        //
+        // `readAcceptedMultiChoice` does NOT validate against the offered choices
+        // (attacker-controlled inputResponses on re-entry). Only grant dirs that
+        // were actually offered by precheckAccess — a value outside grantDirs is
+        // ignored and fails closed in validateAccess. The single-select path reads
+        // `confirm_${i}` for `grantDirs[i]`, so the isSamePath filter is a no-op
+        // there; it only bites for the multi-select array.
+        const accepted = multi
+            ? (readAcceptedMultiChoice(this.toolCtx.inputResponses, 'grant') ?? [])
+            : grantDirs.filter((_dir, i) => readAcceptedConfirm(this.toolCtx.inputResponses, `confirm_${i}`));
+        for (const dir of accepted) {
+            if (!grantDirs.some((g) => isSamePath(g, dir)))
+                continue;
+            await this.toolCtx.fs.pathGuard.applyGrant(dir);
+        }
+        return undefined;
+    }
+    async execute() {
+        const runTool = async () => {
+            try {
+                // Access-grant pre-check before any filesystem touch (R7/R8/R9). A
+                // grant input_required short-circuits here (progress paused, not
+                // finished); an R9 mismatch throws, which this catch surfaces as an
+                // isError tool result like every other handler failure — not a raw
+                // JSON-RPC error (GRANT-1 impact #2).
+                const grantRequired = await this.precheckGrant();
+                if (grantRequired !== undefined)
+                    return grantRequired;
+                const result = await this.def.run(this.parsedArgs, this.toolCtx);
+                // input_required is a return value, not a completed call: the client
+                // retries the same tools/call carrying inputResponses, and this
+                // handler re-enters from the top. Skip the progress "done" close and
+                // return it verbatim — progress is paused, not finished.
+                if (isInputRequiredResult(result)) {
+                    return result;
+                }
+                await this.completeProgress(result.structured);
+                return buildSuccessResponse(result);
+            }
+            catch (error) {
+                return await this.failProgress(error);
+            }
+            finally {
+                await this.#flushProgress();
+            }
+        };
+        return runTool();
+    }
+}
+function createServerToolHandler(def, deps) {
+    return async (args, ctx) => new ToolExecutor(def.name, toToolCtx(ctx, deps), def, args).execute();
+}
+/**
+ * Validate with Zod while publishing the precomputed JSON Schema: clients get
+ * draft-2020-12, handlers get Zod's coercions, defaults and error messages.
+ *
+ * Each validator instance is built for exactly one schema and handed straight
+ * to `fromJsonSchema(thatSchema, ...)`, which calls `getValidator` once with
+ * the same schema — so the argument is redundant here and deliberately ignored.
+ * Reusing one instance across schemas would silently validate against `schema`.
+ */
+function zodJsonSchemaValidator(schema) {
+    return {
+        getValidator() {
+            return (input) => {
+                const result = schema.safeParse(input);
+                if (result.success) {
+                    return {
+                        valid: true,
+                        data: result.data,
+                        errorMessage: undefined,
+                    };
+                }
+                return {
+                    valid: false,
+                    data: undefined,
+                    errorMessage: z.prettifyError(result.error),
+                };
+            };
+        },
+    };
+}
+/**
+ * Generate the wire copy of a schema for `tools/list`. The Zod schema keeps
+ * every constraint for runtime validation; the `override` pass only trims what
+ * the wire copy costs every client at session start:
+ *
+ * - `$schema` and `title` carry no information the host uses.
+ * - `maximum: Number.MAX_SAFE_INTEGER` is zod's int() artifact, not a bound.
+ * - `examples` is dropped in both directions: on output it describes a field the
+ *   server itself fills in, and on input every description that carried one
+ *   already spells the same example out inline, so the keyword paid twice.
+ *
+ * Output `description`s are NOT dropped. They were, and the result was a wire
+ * contract the model had to guess at: `delete` returns `path` XOR `paths`,
+ * `edit.diff` appears only under dryRun, `read.value` has no required field at
+ * all. None of that is inferable from types alone.
+ *
+ * No shared subschema carries a `.meta({ id })`, so zod inlines every one of
+ * them and the emitted document has no `$defs`/`$ref` to dereference.
+ */
+function toDraft202012(schema, io) {
+    const generated = z.toJSONSchema(schema, {
+        target: 'draft-2020-12',
+        io,
+        override: ({ jsonSchema }) => {
+            const node = jsonSchema;
+            delete node['title'];
+            if (node['maximum'] === Number.MAX_SAFE_INTEGER)
+                delete node['maximum'];
+            delete node['examples'];
+        },
+    });
+    delete generated['$schema'];
+    return generated;
+}
+export function defineTool(def) {
+    const inputJsonSchema = toDraft202012(def.input, 'input');
+    // Nothing here depends on `deps`, so it is built once per tool definition
+    // rather than once per `register` — the HTTP leg registers every tool afresh
+    // on each request.
+    // Published annotations are derived, not passed through. `readOnlyHint` is
+    // load-bearing (MUTATING_TOOL_NAMES derives the --read-only gate from it) and
+    // `openWorldHint: false` is a real claim for a filesystem server. The other
+    // two describe behavior a read-only tool cannot have, and restate the default
+    // for a mutating one — 29 tokens per tool for nothing a client acts on.
+    const publishedAnnotations = {
+        readOnlyHint: def.annotations.readOnlyHint,
+        openWorldHint: def.annotations.openWorldHint ?? false,
+        ...(def.annotations.readOnlyHint
+            ? {}
+            : { destructiveHint: def.annotations.destructiveHint ?? true }),
+    };
+    const toolDefShape = {
+        title: def.title,
+        description: def.description,
+        inputSchema: fromJsonSchema(inputJsonSchema, zodJsonSchemaValidator(def.input)),
+        // No `outputSchema`, ever. Publishing one obliges the result to carry
+        // `structuredContent` (clients enforce it), and every tool that authors its
+        // own text ships its metadata under `_meta` instead — see
+        // `buildSuccessResponse`. The two cannot both hold, and the text is what
+        // the model reads. `TOOL-SURFACE-001` pins this for the whole surface.
+        //
+        // `def.output` stays: it types `RunResult<z.infer<O>>`, which is what makes
+        // a tool returning the wrong shape a compile error.
+        annotations: publishedAnnotations,
+    };
+    const tool = {
+        name: def.name,
+        annotations: def.annotations,
+        register(deps) {
+            return deps.server.registerTool(def.name, toolDefShape, createServerToolHandler(def, deps));
+        },
+    };
+    return tool;
+}
+//# sourceMappingURL=define.js.map