@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/tools/create.js

@@ -0,0 +1,142 @@
+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 { formatBytes, joinRoster } from '../core/fmt.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'),
+});
+function buildSummary(results, failCount) {
+    if (results.length === 1 && failCount === 0) {
+        const result = results[0];
+        if (result) {
+            return [
+                `create: ${basename(result.path)}`,
+                formatBytes(result.size),
+                `${String(result.lineCount)} lines`,
+            ].join(' \u00b7 ');
+        }
+    }
+    // Name what was written. "create: 3 files" made the caller open
+    // structuredContent to learn which three \u2014 every other write tool answers
+    // with its roster.
+    const names = joinRoster(results.map((r) => basename(r.path)));
+    const parts = [`create: ${names || 'nothing'}`];
+    if (failCount > 0)
+        parts.push(`${String(failCount)} failed`);
+    return parts.join(' \u00b7 ');
+}
+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 } : {}),
+        };
+        const summary = buildSummary(results, failures.length);
+        if (links.length > 0) {
+            return { structured, text: summary, resources: links };
+        }
+        return { structured, text: summary };
+    },
+    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":"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","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 { formatBytes, joinRoster } from '../core/fmt.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\nfunction buildSummary(results: readonly CreateFileResult[], failCount: number): string {\n  if (results.length === 1 && failCount === 0) {\n    const result = results[0];\n    if (result) {\n      return [\n        `create: ${basename(result.path)}`,\n        formatBytes(result.size),\n        `${String(result.lineCount)} lines`,\n      ].join(' \\u00b7 ');\n    }\n  }\n  // Name what was written. \"create: 3 files\" made the caller open\n  // structuredContent to learn which three \\u2014 every other write tool answers\n  // with its roster.\n  const names = joinRoster(results.map((r) => basename(r.path)));\n  const parts = [`create: ${names || 'nothing'}`];\n  if (failCount > 0) parts.push(`${String(failCount)} failed`);\n  return parts.join(' \\u00b7 ');\n}\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    const summary = buildSummary(results, failures.length);\n\n    if (links.length > 0) {\n      return { structured, text: summary, resources: links };\n    }\n\n    return { structured, text: summary };\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,110 @@
+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[];
+    /**
+     * Publish `output` as the tool's wire `outputSchema`. Off by default: the
+     * spec makes the field optional and it costs more than every other part of
+     * a tool entry combined. Turn it on only where the shape is not inferable —
+     * a discriminated per-path union, or a field that appears under one flag and
+     * not another. The Zod object still validates every result either way.
+     */
+    readonly publishOutputSchema?: boolean;
+    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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"}