@j0hanz/filesystem-mcp 1.19.1 → 2.0.0

package/dist/lib/resource-store.js

@@ -1,195 +0,0 @@
-import { hash, randomUUID } from 'node:crypto';
-import { channel } from 'node:diagnostics_channel';
-import { ErrorCode, McpError } from './errors.js';
-const DEFAULT_RESOURCE_STORE_OPTIONS = {
-    maxEntries: 64,
-    maxTotalBytes: 25 * 1024 * 1024,
-    maxEntryBytes: 10 * 1024 * 1024,
-    entryTtlMs: 30 * 60 * 1000, // 30 minutes
-};
-const RESOURCE_STORE_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:resource-store');
-function publishResourceStoreDiagnostics(event) {
-    if (!RESOURCE_STORE_DIAGNOSTICS_CHANNEL.hasSubscribers)
-        return;
-    RESOURCE_STORE_DIAGNOSTICS_CHANNEL.publish(event);
-}
-function estimateBytes(text) {
-    return Buffer.byteLength(text, 'utf8');
-}
-function computeSha256(text) {
-    return hash('sha256', text, 'hex');
-}
-function buildIndexKey(mimeType, contentHash) {
-    return `${mimeType}:${contentHash}`;
-}
-function isExpired(entry, now = Date.now()) {
-    const expiresAt = Date.parse(entry.expiresAt);
-    return Number.isFinite(expiresAt) && expiresAt <= now;
-}
-function createTextEntry(params) {
-    const storedAt = new Date();
-    return {
-        uri: params.uri,
-        name: params.name,
-        mimeType: params.mimeType,
-        text: params.text,
-        hash: computeSha256(params.text),
-        size: estimateBytes(params.text),
-        storedAt: storedAt.toISOString(),
-        expiresAt: new Date(storedAt.getTime() + params.ttlMs).toISOString(),
-    };
-}
-export function createInMemoryResourceStore(options = {}) {
-    const resolved = {
-        ...DEFAULT_RESOURCE_STORE_OPTIONS,
-        ...options,
-    };
-    const byUri = new Map();
-    const byHashIndex = new Map(); // mimeType:sha256hex -> uri
-    let totalBytes = 0;
-    function removeEntry(uri, reason) {
-        const existing = byUri.get(uri);
-        if (!existing)
-            return;
-        totalBytes -= existing.size;
-        byUri.delete(uri);
-        byHashIndex.delete(buildIndexKey(existing.mimeType, existing.hash));
-        publishResourceStoreDiagnostics({
-            phase: 'cache_evict',
-            uri,
-            name: existing.name,
-            bytes: existing.size,
-            ...(reason !== undefined ? { reason } : {}),
-        });
-    }
-    function evictOldest() {
-        const first = byUri.keys().next();
-        if (first.done)
-            return;
-        removeEntry(first.value);
-    }
-    function pruneExpiredEntries(now = Date.now()) {
-        for (const [uri, entry] of byUri) {
-            if (isExpired(entry, now)) {
-                removeEntry(uri, 'expired');
-            }
-        }
-    }
-    function enforceLimits() {
-        while (byUri.size > resolved.maxEntries)
-            evictOldest();
-        while (totalBytes > resolved.maxTotalBytes) {
-            if (byUri.size === 0)
-                break;
-            evictOldest();
-        }
-    }
-    function putText(params) {
-        pruneExpiredEntries();
-        const mimeType = params.mimeType ?? 'text/plain';
-        const entryBytes = estimateBytes(params.text);
-        if (entryBytes > resolved.maxEntryBytes) {
-            publishResourceStoreDiagnostics({
-                phase: 'cache_reject',
-                bytes: entryBytes,
-                reason: 'entry_too_large',
-            });
-            throw new McpError(ErrorCode.TOO_LARGE, `Resource too large to cache (${entryBytes} bytes).`);
-        }
-        const contentHash = computeSha256(params.text);
-        const indexKey = buildIndexKey(mimeType, contentHash);
-        const existingUri = byHashIndex.get(indexKey);
-        if (existingUri !== undefined) {
-            const cached = byUri.get(existingUri);
-            if (cached !== undefined) {
-                if (isExpired(cached)) {
-                    removeEntry(existingUri, 'expired');
-                }
-                else {
-                    publishResourceStoreDiagnostics({
-                        phase: 'cache_hit',
-                        uri: cached.uri,
-                        name: cached.name,
-                        bytes: cached.size,
-                    });
-                    return cached;
-                }
-            }
-            else {
-                byHashIndex.delete(indexKey);
-            }
-        }
-        const id = randomUUID();
-        const uri = `filesystem-mcp://result/${id}`;
-        const entry = createTextEntry({
-            uri,
-            name: params.name,
-            mimeType,
-            text: params.text,
-            ttlMs: resolved.entryTtlMs,
-        });
-        byUri.set(uri, entry);
-        byHashIndex.set(indexKey, uri);
-        totalBytes += entryBytes;
-        publishResourceStoreDiagnostics({
-            phase: 'cache_store',
-            uri: entry.uri,
-            name: entry.name,
-            bytes: entry.size,
-        });
-        enforceLimits();
-        if (!byUri.has(uri)) {
-            publishResourceStoreDiagnostics({
-                phase: 'cache_reject',
-                uri,
-                name: entry.name,
-                bytes: entry.size,
-                reason: 'evicted_immediately',
-            });
-            throw new McpError(ErrorCode.TOO_LARGE, 'Cache full: entry evicted.');
-        }
-        return entry;
-    }
-    function getText(uri) {
-        const existing = byUri.get(uri);
-        if (!existing) {
-            publishResourceStoreDiagnostics({
-                phase: 'cache_miss',
-                uri,
-                reason: 'not_found',
-            });
-            throw new McpError(ErrorCode.NOT_FOUND, `Resource not found: ${uri}. Re-run the tool to regenerate.`);
-        }
-        if (isExpired(existing)) {
-            removeEntry(uri, 'expired');
-            publishResourceStoreDiagnostics({
-                phase: 'cache_miss',
-                uri,
-                reason: 'expired',
-            });
-            throw new McpError(ErrorCode.NOT_FOUND, `Resource expired: ${uri}. Re-run the tool to regenerate.`);
-        }
-        publishResourceStoreDiagnostics({
-            phase: 'cache_hit',
-            uri: existing.uri,
-            name: existing.name,
-            bytes: existing.size,
-        });
-        return existing;
-    }
-    function clear() {
-        const bytesBeforeClear = totalBytes;
-        byUri.clear();
-        byHashIndex.clear();
-        totalBytes = 0;
-        publishResourceStoreDiagnostics({
-            phase: 'cache_clear',
-            bytes: bytesBeforeClear,
-        });
-    }
-    function keys() {
-        pruneExpiredEntries();
-        return Array.from(byUri.keys());
-    }
-    return { putText, getText, clear, keys };
-}

package/dist/lib/utils.d.ts

@@ -1,7 +0,0 @@
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
-export declare function debounce<Args extends unknown[]>(func: (...args: Args) => void, waitMs: number): {
-    (...args: Args): void;
-    cancel: () => void;
-};
-export declare function mergeOptions<T extends object>(defaults: T, overrides: Partial<T>): T;
-export declare function omitOptionKeys<T extends object, K extends keyof T>(input: T, keys: readonly K[]): Omit<T, K>;

package/dist/lib/utils.js

@@ -1,37 +0,0 @@
-// type-guards.ts
-export function isRecord(value) {
-    return value !== null && typeof value === 'object';
-}
-// debounce
-export function debounce(func, waitMs) {
-    let timeoutId;
-    const debounced = (...args) => {
-        if (timeoutId !== undefined) {
-            clearTimeout(timeoutId);
-        }
-        timeoutId = setTimeout(() => {
-            timeoutId = undefined;
-            func(...args);
-        }, waitMs);
-        // Unref if in Node environment to not block process exit
-        timeoutId.unref();
-    };
-    debounced.cancel = () => {
-        if (timeoutId !== undefined) {
-            clearTimeout(timeoutId);
-            timeoutId = undefined;
-        }
-    };
-    return debounced;
-}
-// option-utils.ts
-export function mergeOptions(defaults, overrides) {
-    return { ...defaults, ...overrides };
-}
-export function omitOptionKeys(input, keys) {
-    const output = { ...input };
-    for (const key of keys) {
-        Reflect.deleteProperty(output, key);
-    }
-    return output;
-}

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

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

package/dist/lib/zod-codecs.js

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

package/dist/pkg-info.d.ts

@@ -1,7 +0,0 @@
-export declare const pkgInfo: {
-    [x: string]: unknown;
-    name: string;
-    version: string;
-    description?: string | undefined;
-    homepage?: string | undefined;
-};

package/dist/pkg-info.js

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

package/dist/resources/generated-instructions.d.ts

@@ -1 +0,0 @@
-export declare function buildServerInstructions(): string;

package/dist/resources/generated-instructions.js

@@ -1,105 +0,0 @@
-import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
-import { buildCoreContextPack, formatToolNameList, getSharedConstraints, getToolContracts, pickAvailableToolNames, } from './tool-info.js';
-import { buildWorkflowGuide } from './workflows.js';
-function buildToolsOverview() {
-    const rows = [
-        ['Navigate', pickAvailableToolNames(['roots', 'ls', 'tree', 'find'])],
-        [
-            'Inspect',
-            pickAvailableToolNames(['stat', 'stat_many', 'grep', 'calculate_hash']),
-        ],
-        ['Read', pickAvailableToolNames(['read', 'read_many', 'diff_files'])],
-        [
-            'Write',
-            pickAvailableToolNames([
-                'mkdir',
-                'write',
-                'edit',
-                'mv',
-                'rm',
-                'apply_patch',
-                'search_and_replace',
-            ]),
-        ],
-    ];
-    return rows
-        .filter(([, names]) => names.length > 0)
-        .map(([category, names]) => `| ${category} | ${formatToolNameList(names)} |`)
-        .join('\n');
-}
-function buildInstructionsHeader() {
-    return `## Role
-
-Secure filesystem agent. Operate strictly within allowed roots. Resolve paths before acting — never assume.
-
-## Tools Overview
-
-| Category | Tools |
-| -------- | ----- |
-
-${buildToolsOverview()}
-
-## Resources
-
-| URI                              | Purpose                                                        |
-| -------------------------------- | -------------------------------------------------------------- |
-| \`internal://instructions\`      | Full usage reference (this document)                           |
-| \`internal://tool-catalog\`      | Tool routing, data flow, and selection guide                   |
-| \`internal://workflows\`         | Step-by-step execution sequences                               |
-| \`internal://tool-info/{name}\`  | Per-tool contract (e.g. \`internal://tool-info/read\`)         |
-| \`filesystem-mcp://result/{id}\` | Cached large output — fetch via \`resources/read\` immediately |
-| \`filesystem-mcp://metrics\`     | Per-tool call count, error rate, and avg duration              |
-
-## Task Protocol
-
-- Check \`execution.taskSupport\` before sending task metadata.
-  - \`forbidden\` (default): Do not send \`task\`.
-  - \`optional\`: Send \`task\` only when durable polling or deferred retrieval is needed.
-  - \`required\`: Always send \`task\`.
-- Poll status via \`tasks/get\`, retrieve final payload via \`tasks/result\`.
-- Pass \`_meta.progressToken\` in \`tools/call\` to receive \`notifications/progress\`.
-`;
-}
-const INSTRUCTIONS_FOOTER = `## Constraints
-
-${getSharedConstraints()
-    .map((c) => `- ${c}`)
-    .join('\n')}
-
-## Error Recovery
-
-| Error Code          | Action                                                                    |
-| ------------------- | ------------------------------------------------------------------------- |
-| \`ACCESS_DENIED\`   | Run \`roots\` to list allowed directories, retry with a valid path.       |
-| \`NOT_FOUND\`       | Run \`ls\` or \`find\` to verify the path.                                |
-| \`TOO_LARGE\`       | Use \`head\`/\`tail\`, line ranges, or split across \`read_many\`.        |
-| \`TIMEOUT\`         | Reduce scope, depth, or maxResults.                                       |
-| \`INVALID_INPUT\`   | Re-read tool contract via \`internal://tool-info/{name}\`.                |
-`;
-function formatToolSection(tool) {
-    const parts = [`### ${tool.name}\n${tool.description}`];
-    if (tool.nuances && tool.nuances.length > 0) {
-        parts.push(...tool.nuances.map((n) => `- ${n}`));
-    }
-    if (tool.gotchas && tool.gotchas.length > 0) {
-        parts.push(...tool.gotchas.map((g) => `- ⚠ ${g}`));
-    }
-    return parts.join('\n');
-}
-export function buildServerInstructions() {
-    const toolSections = getToolContracts().map(formatToolSection).join('\n\n');
-    return [
-        buildInstructionsHeader(),
-        buildCoreContextPack(),
-        '',
-        buildToolCatalogDetailsOnly(),
-        '',
-        '## Tool Reference',
-        '',
-        toolSections,
-        '',
-        buildWorkflowGuide(),
-        '',
-        INSTRUCTIONS_FOOTER,
-    ].join('\n');
-}

package/dist/resources/tool-catalog.d.ts

@@ -1,2 +0,0 @@
-export declare function buildToolCatalog(): string;
-export declare function buildToolCatalogDetailsOnly(): string;

package/dist/resources/tool-catalog.js

@@ -1,78 +0,0 @@
-import { buildCoreContextPack, getTaskCapableToolNames, pickAvailableToolNames, } from './tool-info.js';
-function buildCrossToolDataFlow() {
-    const flows = [];
-    if (pickAvailableToolNames(['find', 'read']).length === 2) {
-        flows.push('find.results[].path -> read.path');
-    }
-    if (pickAvailableToolNames(['grep', 'read']).length === 2) {
-        flows.push('grep.matches[].file -> read.path');
-    }
-    if (pickAvailableToolNames(['diff_files', 'apply_patch']).length === 2) {
-        flows.push('diff_files.diff -> apply_patch.patch');
-    }
-    flows.push('toolResult.resourceUri -> resources/read.uri');
-    return flows.join('\n');
-}
-function buildCatalogGuide() {
-    const taskCapable = getTaskCapableToolNames();
-    return `# Tool Selection Guide
-
-## Primitive Routing
-
-| Primitive      | Purpose                                                                                                                            |
-| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
-| \`tools\`      | Model-controlled operations that inspect or mutate the filesystem within allowed roots.                                            |
-| \`resources\`  | Application-driven context: \`internal://instructions\`, \`internal://tool-info/{name}\`, cached \`filesystem-mcp://result/{id}\`. |
-| \`prompts\`    | User-controlled workflow templates for help, comparison, and guided inspection.                                                    |
-| \`completion\` | Argument suggestions for prompts and resource templates (not a discovery mechanism).                                               |
-
-## Cross-Tool Data Flow
-
-\`\`\`
-${buildCrossToolDataFlow()}
-\`\`\`
-
-## Result Contract
-
-- Success: returns both \`content\` (JSON text) and \`structuredContent\` (when \`outputSchema\` is declared).
-- Error: \`isError: true\` in tool result, \`structuredContent\` omitted. Parse \`content\` text for error details.
-- Tool/business failures use \`isError: true\` inside the tool result, not JSON-RPC protocol errors.
-- When a response includes \`resourceUri\` or \`resource_link\`, follow up with \`resources/read\` immediately.
-
-## Task Mode
-
-Use inline execution by default. Add task mode only when the caller needs durable polling, deferred retrieval, or cancellation.
-
-Task-capable tools: ${taskCapable.length > 0 ? taskCapable.map((name) => `\`${name}\``).join(', ') : 'none'}.
-
-## Search Strategy
-
-| Goal                    | Tool                                       |
-| ----------------------- | ------------------------------------------ |
-| Find files by name/glob | \`find\`                                   |
-| Search file contents    | \`grep\`                                   |
-| Replace across files    | \`search_and_replace\` (not for discovery) |
-
-## Write Strategy
-
-| Scenario                    | Tool                                                  |
-| --------------------------- | ----------------------------------------------------- |
-| Single file, targeted edit  | \`edit\` — match exact text, replace first occurrence |
-| Single file, full rewrite   | \`write\` — overwrite entire content                  |
-| Multiple files, same change | \`search_and_replace\` — glob + pattern across files  |
-| Unsure what to change       | \`grep\` first, then decide                           |
-
-## Patch Strategy
-
-1. Generate with \`diff_files\`.
-2. Validate with \`apply_patch(dryRun: true)\` before writing.
-3. Apply with \`apply_patch\`.
-4. Multi-file patches: set \`path\` to the base directory; results are per-file.
-`;
-}
-export function buildToolCatalog() {
-    return `${buildCoreContextPack()}\n\n${buildCatalogGuide()}`;
-}
-export function buildToolCatalogDetailsOnly() {
-    return buildCatalogGuide();
-}

package/dist/resources/tool-info.d.ts

@@ -1,9 +0,0 @@
-import type { ToolContract } from '../tools/contract.js';
-export declare function getToolContracts(): ToolContract[];
-export declare function getSortedToolContracts(): ToolContract[];
-export declare function pickAvailableToolNames(names: readonly string[]): string[];
-export declare function formatToolNameList(names: readonly string[]): string;
-export declare function getTaskCapableToolNames(): string[];
-export declare function buildCoreContextPack(): string;
-export declare function getSharedConstraints(): string[];
-export declare function buildToolInfo(name: string): string | undefined;