@j0hanz/filesystem-mcp 1.19.0 → 2.0.0

package/dist/instructions.js

@@ -0,0 +1,71 @@
+import { DEFAULT_SEARCH_CONTENT_RESULTS, getMaxTextFileSize, MAX_SEARCH_RESULTS, } from './core/util.js';
+import { GET_FILE_INFO, LIST, LIST_ALLOWED_DIRECTORIES, MUTATING_TOOL_NAMES, READ_FILE, SEARCH_CONTENT, SEARCH_FILES, } from './tools/index.js';
+function buildToolsOverview(readOnly) {
+    const rows = [
+        ['Navigate', [LIST_ALLOWED_DIRECTORIES.name, LIST.name, SEARCH_FILES.name]],
+        ['Inspect', [GET_FILE_INFO.name, SEARCH_CONTENT.name]],
+        ['Read', [READ_FILE.name]],
+    ];
+    // Under --read-only the mutating tools are never registered, so advertising
+    // them here would point the model at tools that are not there. Drop the row
+    // rather than emit an empty one.
+    if (!readOnly) {
+        rows.push(['Write', [...MUTATING_TOOL_NAMES]]);
+    }
+    const rowLines = rows.map(([cat, names]) => `${cat}: ${names.join(', ')}`);
+    return `\`\`\`\n${rowLines.join('\n')}\n\`\`\``;
+}
+export const INSTRUCTIONS_URI = 'internal://instructions';
+export const NO_POSITIONAL_ROOTS_GUIDANCE = 'No positional directories specified. Configure roots with directory arguments, FS_ALLOWED_DIRS, or --allow-cwd. Modern clients with elicitation can also call a tool with a concrete path and approve the requested grant.';
+/**
+ * The one statement of what this server is and how to approach it. The server's
+ * `instructions`, the `get-help` prompt, and the instructions resource all
+ * describe the same document, and three hand-maintained paraphrases of it drift
+ * against each other and cost the client the same sentence three times.
+ */
+export const INSTRUCTIONS_SUMMARY = 'Navigation guide for filesystem-mcp tools and constraints. ' +
+    'Use list_roots to inspect configured or accepted roots, then list/find_files -> stat -> read. Never guess paths.';
+export function buildSectionsRecord(readOnly) {
+    const maxFileMb = Math.floor(getMaxTextFileSize() / 1024 / 1024);
+    return {
+        guidelines: [
+            'Guidelines:',
+            '```',
+            `root_access: ${LIST_ALLOWED_DIRECTORIES.name} lists configured or accepted roots; every other tool is scoped to them.`,
+            'modern_root_grants: Modern clients do not automatically send workspace roots. Call a tool with a concrete path and approve its grant when elicitation is available.',
+            `path_resolution: Confirm a path with ${LIST.name} or ${SEARCH_FILES.name} before acting on it.`,
+            '```',
+        ].join('\n'),
+        tools_overview: [
+            'Tools Overview:',
+            buildToolsOverview(readOnly),
+            '',
+            'Full schemas, descriptions, and annotations are in `tools/list`.',
+        ].join('\n'),
+        constraints: [
+            'Constraints:',
+            '```',
+            `allowed_roots: Startup roots come from CLI paths, FS_ALLOWED_DIRS, or --allow-cwd; accepted modern grants are additive. Call ${LIST_ALLOWED_DIRECTORIES.name} to read the current set.`,
+            'legacy_roots: Legacy clients may additionally seed roots through the deprecated roots/list flow.',
+            'sensitive_paths: Sensitive file paths (.env, *.pem, *id_rsa*) are denied by default.',
+            `enforced_limits: max file size ${maxFileMb} MB, file search cap ${MAX_SEARCH_RESULTS} results, content search cap ${DEFAULT_SEARCH_CONTENT_RESULTS} matches.`,
+            'ephemeral_results: When a tool returns resourceUri, call resources/read immediately — cached results are ephemeral and expire after ~60 seconds, eviction, or restart.',
+            'pagination: nextCursor is backed by a snapshot on the same ~60s clock. Page through promptly; if a cursor is rejected, start again without one. resourceUri appears on the first page only.',
+            '```',
+        ].join('\n'),
+        error_recovery: [
+            'Error Recovery:',
+            '```',
+            `ACCESS_DENIED: Run ${LIST_ALLOWED_DIRECTORIES.name}; configure a missing startup root or retry a concrete path and approve the grant.`,
+            `NOT_FOUND: Run ${LIST.name} or ${SEARCH_FILES.name} to verify the path.`,
+            `TOO_LARGE: Use ${READ_FILE.name} with head/tail or startLine/endLine, or split across several calls.`,
+            'TIMEOUT: Reduce scope, depth, or maxResults.',
+            'INVALID_INPUT: Re-read the tool schema in tools/list.',
+            '```',
+        ].join('\n'),
+    };
+}
+export function renderSections(sections) {
+    return `\n${Object.values(sections).join('\n\n')}\n`;
+}
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,aAAa,EACb,IAAI,EACJ,wBAAwB,EACxB,mBAAmB,EACnB,SAAS,EACT,cAAc,EACd,YAAY,GACb,MAAM,kBAAkB,CAAC;AAE1B,SAAS,kBAAkB,CAAC,QAAiB;IAC3C,MAAM,IAAI,GAAyB;QACjC,CAAC,UAAU,EAAE,CAAC,wBAAwB,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC;QAC3E,CAAC,SAAS,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC,MAAM,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;KAC3B,CAAC;IAEF,4EAA4E;IAC5E,4EAA4E;IAC5E,iCAAiC;IACjC,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3E,OAAO,WAAW,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC;AAClD,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG,yBAAyB,CAAC;AAC1D,MAAM,CAAC,MAAM,4BAA4B,GACvC,4NAA4N,CAAC;AAE/N;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAC/B,6DAA6D;IAC7D,kHAAkH,CAAC;AAErH,MAAM,UAAU,mBAAmB,CAAC,QAAiB;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC;IACjE,OAAO;QACL,UAAU,EAAE;YACV,aAAa;YACb,KAAK;YACL,gBAAgB,wBAAwB,CAAC,IAAI,0EAA0E;YACvH,qKAAqK;YACrK,wCAAwC,IAAI,CAAC,IAAI,OAAO,YAAY,CAAC,IAAI,uBAAuB;YAChG,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,cAAc,EAAE;YACd,iBAAiB;YACjB,kBAAkB,CAAC,QAAQ,CAAC;YAC5B,EAAE;YACF,kEAAkE;SACnE,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,WAAW,EAAE;YACX,cAAc;YACd,KAAK;YACL,gIAAgI,wBAAwB,CAAC,IAAI,2BAA2B;YACxL,kGAAkG;YAClG,sFAAsF;YACtF,kCAAkC,SAAS,wBAAwB,kBAAkB,gCAAgC,8BAA8B,WAAW;YAC9J,wKAAwK;YACxK,6LAA6L;YAC7L,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,cAAc,EAAE;YACd,iBAAiB;YACjB,KAAK;YACL,sBAAsB,wBAAwB,CAAC,IAAI,oFAAoF;YACvI,kBAAkB,IAAI,CAAC,IAAI,OAAO,YAAY,CAAC,IAAI,sBAAsB;YACzE,kBAAkB,SAAS,CAAC,IAAI,sEAAsE;YACtG,8CAA8C;YAC9C,uDAAuD;YACvD,KAAK;SACN,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgC;IAC7D,OAAO,KAAK,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACvD,CAAC","sourcesContent":["import {\n  DEFAULT_SEARCH_CONTENT_RESULTS,\n  getMaxTextFileSize,\n  MAX_SEARCH_RESULTS,\n} from './core/util.js';\nimport {\n  GET_FILE_INFO,\n  LIST,\n  LIST_ALLOWED_DIRECTORIES,\n  MUTATING_TOOL_NAMES,\n  READ_FILE,\n  SEARCH_CONTENT,\n  SEARCH_FILES,\n} from './tools/index.js';\n\nfunction buildToolsOverview(readOnly: boolean): string {\n  const rows: [string, string[]][] = [\n    ['Navigate', [LIST_ALLOWED_DIRECTORIES.name, LIST.name, SEARCH_FILES.name]],\n    ['Inspect', [GET_FILE_INFO.name, SEARCH_CONTENT.name]],\n    ['Read', [READ_FILE.name]],\n  ];\n\n  // Under --read-only the mutating tools are never registered, so advertising\n  // them here would point the model at tools that are not there. Drop the row\n  // rather than emit an empty one.\n  if (!readOnly) {\n    rows.push(['Write', [...MUTATING_TOOL_NAMES]]);\n  }\n\n  const rowLines = rows.map(([cat, names]) => `${cat}: ${names.join(', ')}`);\n  return `\\`\\`\\`\\n${rowLines.join('\\n')}\\n\\`\\`\\``;\n}\n\nexport const INSTRUCTIONS_URI = 'internal://instructions';\nexport const NO_POSITIONAL_ROOTS_GUIDANCE =\n  'No positional directories specified. Configure roots with directory arguments, FS_ALLOWED_DIRS, or --allow-cwd. Modern clients with elicitation can also call a tool with a concrete path and approve the requested grant.';\n\n/**\n * The one statement of what this server is and how to approach it. The server's\n * `instructions`, the `get-help` prompt, and the instructions resource all\n * describe the same document, and three hand-maintained paraphrases of it drift\n * against each other and cost the client the same sentence three times.\n */\nexport const INSTRUCTIONS_SUMMARY =\n  'Navigation guide for filesystem-mcp tools and constraints. ' +\n  'Use list_roots to inspect configured or accepted roots, then list/find_files -> stat -> read. Never guess paths.';\n\nexport function buildSectionsRecord(readOnly: boolean): Record<string, string> {\n  const maxFileMb = Math.floor(getMaxTextFileSize() / 1024 / 1024);\n  return {\n    guidelines: [\n      'Guidelines:',\n      '```',\n      `root_access: ${LIST_ALLOWED_DIRECTORIES.name} lists configured or accepted roots; every other tool is scoped to them.`,\n      'modern_root_grants: Modern clients do not automatically send workspace roots. Call a tool with a concrete path and approve its grant when elicitation is available.',\n      `path_resolution: Confirm a path with ${LIST.name} or ${SEARCH_FILES.name} before acting on it.`,\n      '```',\n    ].join('\\n'),\n    tools_overview: [\n      'Tools Overview:',\n      buildToolsOverview(readOnly),\n      '',\n      'Full schemas, descriptions, and annotations are in `tools/list`.',\n    ].join('\\n'),\n    constraints: [\n      'Constraints:',\n      '```',\n      `allowed_roots: Startup roots come from CLI paths, FS_ALLOWED_DIRS, or --allow-cwd; accepted modern grants are additive. Call ${LIST_ALLOWED_DIRECTORIES.name} to read the current set.`,\n      'legacy_roots: Legacy clients may additionally seed roots through the deprecated roots/list flow.',\n      'sensitive_paths: Sensitive file paths (.env, *.pem, *id_rsa*) are denied by default.',\n      `enforced_limits: max file size ${maxFileMb} MB, file search cap ${MAX_SEARCH_RESULTS} results, content search cap ${DEFAULT_SEARCH_CONTENT_RESULTS} matches.`,\n      'ephemeral_results: When a tool returns resourceUri, call resources/read immediately — cached results are ephemeral and expire after ~60 seconds, eviction, or restart.',\n      'pagination: nextCursor is backed by a snapshot on the same ~60s clock. Page through promptly; if a cursor is rejected, start again without one. resourceUri appears on the first page only.',\n      '```',\n    ].join('\\n'),\n    error_recovery: [\n      'Error Recovery:',\n      '```',\n      `ACCESS_DENIED: Run ${LIST_ALLOWED_DIRECTORIES.name}; configure a missing startup root or retry a concrete path and approve the grant.`,\n      `NOT_FOUND: Run ${LIST.name} or ${SEARCH_FILES.name} to verify the path.`,\n      `TOO_LARGE: Use ${READ_FILE.name} with head/tail or startLine/endLine, or split across several calls.`,\n      'TIMEOUT: Reduce scope, depth, or maxResults.',\n      'INVALID_INPUT: Re-read the tool schema in tools/list.',\n      '```',\n    ].join('\\n'),\n  };\n}\n\nexport function renderSections(sections: Record<string, string>): string {\n  return `\\n${Object.values(sections).join('\\n\\n')}\\n`;\n}\n"]}

package/dist/prompts.d.ts

@@ -1,6 +1,8 @@
-import { type McpServer } from '@modelcontextprotocol/server';
-import { type IconInfo } from './tools/shared.js';
-export declare function registerGetHelpPrompt(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
-export declare function registerCompareFilesPrompt(server: McpServer, iconInfo?: IconInfo): void;
-export declare function registerAnalyzePathPrompt(server: McpServer, iconInfo?: IconInfo): void;
-export declare function registerGetToolHelpPrompt(server: McpServer, iconInfo?: IconInfo): void;
+import type { McpServer } from '@modelcontextprotocol/server';
+interface PromptRegistrarDeps {
+    readonly server: McpServer;
+    readonly readOnly?: boolean;
+}
+export declare function registerPrompts(deps: PromptRegistrarDeps): void;
+export {};
+//# sourceMappingURL=prompts.d.ts.map

package/dist/prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.d.ts","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,SAAS,EAGV,MAAM,8BAA8B,CAAC;AAkBtC,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AA+DD,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAoC/D"}

package/dist/prompts.js

@@ -1,177 +1,83 @@
-import { ProtocolError, ProtocolErrorCode, } from '@modelcontextprotocol/server';
-import { z } from 'zod';
-import { buildToolInfo, getSortedToolContracts, } from './resources/tool-info.js';
-import { withDefaultIcons } from './tools/shared.js';
-const HELP_PROMPT_NAME = 'get-help';
-const HELP_PROMPT_TITLE = 'Get Help';
-const HELP_PROMPT_DESCRIPTION = 'Return filesystem-mcp usage instructions.';
-const COMPARE_FILES_PROMPT_NAME = 'compare-files';
-const COMPARE_FILES_PROMPT_TITLE = 'Compare Files';
-const COMPARE_FILES_PROMPT_DESCRIPTION = 'Generate a workflow for comparing two files using diff_files.';
-const ANALYZE_PATH_PROMPT_NAME = 'analyze-path';
-const ANALYZE_PATH_PROMPT_TITLE = 'Analyze Path';
-const ANALYZE_PATH_PROMPT_DESCRIPTION = 'Generate a workflow for analyzing a file or directory using stat, read, and tree.';
-const GET_TOOL_HELP_PROMPT_NAME = 'get-tool-help';
-const GET_TOOL_HELP_PROMPT_TITLE = 'Get Tool Help';
-const GET_TOOL_HELP_PROMPT_DESCRIPTION = 'Return a prompt with the authoritative contract for a specific filesystem-mcp tool.';
-function filterInstructionsByTopic(instructions, topic) {
-    const normalized = topic.trim().toLowerCase();
-    if (!normalized)
-        return instructions;
-    const sections = instructions.split(/\n(?=## )/u);
-    const match = sections.find((sec) => sec.toLowerCase().startsWith(`## ${normalized}`));
-    if (match !== undefined)
-        return match;
-    const available = sections
-        .filter((sec) => sec.startsWith('## '))
-        .map((sec) => sec.split('\n')[0]?.replace(/^##\s*/u, '') ?? '')
-        .filter(Boolean)
-        .join(', ');
-    return `Section '${topic}' not found. Available: ${available}\n\n${instructions}`;
-}
-function findKnownToolName(rawName) {
-    const normalized = rawName.trim().toLowerCase();
-    if (!normalized)
-        return undefined;
-    return getSortedToolContracts().find((contract) => contract.name.toLowerCase() === normalized)?.name;
-}
-export function registerGetHelpPrompt(server, instructions, iconInfo) {
-    const baseConfig = withDefaultIcons({ title: HELP_PROMPT_TITLE, description: HELP_PROMPT_DESCRIPTION }, iconInfo);
-    server.registerPrompt(HELP_PROMPT_NAME, {
-        ...baseConfig,
-        argsSchema: z.object({
-            topic: z
-                .string()
-                .optional()
-                .describe('Optional section heading prefix (example: "error handling"). Omit to return full instructions.'),
-        }),
-    }, ({ topic }) => {
-        const text = topic
-            ? filterInstructionsByTopic(instructions, topic)
-            : instructions;
-        return {
-            description: HELP_PROMPT_DESCRIPTION,
-            messages: [
-                {
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text,
-                        annotations: {
-                            audience: ['assistant'],
-                            priority: 1,
-                        },
-                    },
-                },
-            ],
-        };
+import { completable, getDisplayName, ProtocolError } from '@modelcontextprotocol/server';
+import * as z from 'zod/v4';
+import { formatUnknownErrorMessage, fsErrorCode, hasErrorShape } from './core/errors.js';
+import { Logger } from './core/observability.js';
+import { isBlank, SHELL_METACHAR_RE } from './core/schema.js';
+import { buildSectionsRecord, INSTRUCTIONS_SUMMARY, renderSections } from './instructions.js';
+// --- Helpers ---
+function topicArg(topics, description) {
+    return completable(z
+        .string()
+        .min(1, { message: 'Topic required' })
+        .refine((val) => !isBlank(val), {
+        message: 'Topic cannot be empty or whitespace-only',
+    })
+        .refine((val) => !SHELL_METACHAR_RE.test(val), {
+        message: 'Topic contains prohibited characters (newlines or shell metacharacters)',
+    })
+        .describe(description), (value) => {
+        const lower = value.toLowerCase();
+        return lower ? topics.filter((t) => t.startsWith(lower)) : [...topics];
     });
 }
-export function registerCompareFilesPrompt(server, iconInfo) {
-    server.registerPrompt(COMPARE_FILES_PROMPT_NAME, {
-        ...withDefaultIcons({
-            title: COMPARE_FILES_PROMPT_TITLE,
-            description: COMPARE_FILES_PROMPT_DESCRIPTION,
-        }, iconInfo),
-        argsSchema: z.object({
-            original: z.string().describe('Path to the original file.'),
-            modified: z.string().describe('Path to the modified file.'),
-        }),
-    }, ({ original, modified }) => ({
-        description: COMPARE_FILES_PROMPT_DESCRIPTION,
-        messages: [
-            {
-                role: 'user',
-                content: {
-                    type: 'text',
-                    text: `Compare files and explain differences.\n\n1. Call \`diff_files\` with:\n   - original: ${original}\n   - modified: ${modified}\n2. Summarize: additions, deletions, and semantic changes.\n3. Flag any potential issues (conflicts, regressions, breaking changes).`,
-                    annotations: {
-                        audience: ['assistant'],
-                        priority: 1,
-                    },
-                },
-            },
-        ],
-    }));
+function userText(text) {
+    const content = {
+        type: 'text',
+        text,
+        annotations: { audience: ['assistant'], priority: 1 },
+    };
+    return { role: 'user', content };
 }
-export function registerAnalyzePathPrompt(server, iconInfo) {
-    server.registerPrompt(ANALYZE_PATH_PROMPT_NAME, {
-        ...withDefaultIcons({
-            title: ANALYZE_PATH_PROMPT_TITLE,
-            description: ANALYZE_PATH_PROMPT_DESCRIPTION,
-        }, iconInfo),
-        argsSchema: z.object({
-            path: z.string().describe('Absolute path to analyze.'),
-        }),
-    }, ({ path: targetPath }) => ({
-        description: ANALYZE_PATH_PROMPT_DESCRIPTION,
-        messages: [
-            {
-                role: 'user',
-                content: {
-                    type: 'text',
-                    text: `Analyze the path: ${targetPath}\n\n1. Call \`stat\` to determine if it is a file or directory.\n2. If file: call \`read\` with \`includeHash: true\` and summarize contents.\n3. If directory: call \`tree\` (maxDepth: 3) and \`ls\` to summarize structure.\n4. Report: type, size, permissions, key observations.`,
-                    annotations: {
-                        audience: ['assistant'],
-                        priority: 1,
-                    },
-                },
-            },
-        ],
-    }));
+async function wrapHandler(contract, fn) {
+    const displayName = getDisplayName(contract);
+    try {
+        const result = await fn();
+        Logger.debug(`prompt resolved`, { name: contract.name, displayName });
+        return result;
+    }
+    catch (error) {
+        if (hasErrorShape(error, 'ProtocolError'))
+            throw error;
+        const message = formatUnknownErrorMessage(error);
+        Logger.error(`Prompt handler failed: ${message}`, {
+            promptName: contract.name,
+            error,
+        });
+        const protocolError = new ProtocolError(fsErrorCode(error), message);
+        protocolError.cause = error;
+        throw protocolError;
+    }
 }
-export function registerGetToolHelpPrompt(server, iconInfo) {
-    server.registerPrompt(GET_TOOL_HELP_PROMPT_NAME, {
-        ...withDefaultIcons({
-            title: GET_TOOL_HELP_PROMPT_TITLE,
-            description: GET_TOOL_HELP_PROMPT_DESCRIPTION,
-        }, iconInfo),
-        argsSchema: z.object({
-            name: z
-                .string()
-                .min(1)
-                .describe('Tool name from tools/list or internal://tool-info/{name}.'),
+// --- Prompt entries ---
+const GET_HELP = {
+    name: 'get-help',
+    title: 'Get Help',
+    description: INSTRUCTIONS_SUMMARY,
+};
+export function registerPrompts(deps) {
+    const sections = buildSectionsRecord(deps.readOnly ?? false);
+    const instructions = renderSections(sections);
+    const topics = Object.keys(sections);
+    deps.server.registerPrompt(GET_HELP.name, {
+        title: GET_HELP.title,
+        description: GET_HELP.description,
+        argsSchema: z.strictObject({
+            topic: topicArg(topics, `Section key to filter instructions (one of: ${topics.join(', ')}); omit to return all instructions.`).optional(),
         }),
-    }, ({ name }) => {
-        const toolName = findKnownToolName(name);
-        if (!toolName) {
-            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${name}`);
-        }
-        const toolInfo = buildToolInfo(toolName);
-        if (!toolInfo) {
-            throw new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${toolName}`);
+    }, ({ topic }) => wrapHandler(GET_HELP, () => {
+        const lowerTopic = topic?.toLowerCase();
+        const section = lowerTopic && Object.hasOwn(sections, lowerTopic) ? sections[lowerTopic] : undefined;
+        if (topic && !section) {
+            Logger.debug('get-help: unknown topic requested', { topic });
         }
+        const text = section ??
+            (topic
+                ? `Section '${topic}' not found. Available: ${topics.join(', ')}\n\n${instructions}`
+                : instructions);
         return {
-            description: GET_TOOL_HELP_PROMPT_DESCRIPTION,
-            messages: [
-                {
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text: `Use the embedded contract for \`${toolName}\` as the authoritative reference. ` +
-                            'Summarize when to use it, its key constraints, and the safest next action.',
-                        annotations: {
-                            audience: ['assistant'],
-                            priority: 1,
-                        },
-                    },
-                },
-                {
-                    role: 'user',
-                    content: {
-                        type: 'resource',
-                        resource: {
-                            uri: `internal://tool-info/${toolName}`,
-                            mimeType: 'text/markdown',
-                            text: toolInfo,
-                        },
-                        annotations: {
-                            audience: ['assistant'],
-                            priority: 1,
-                        },
-                    },
-                },
-            ],
+            description: GET_HELP.description,
+            messages: [userText(text)],
         };
-    });
+    }));
 }
+//# sourceMappingURL=prompts.js.map

package/dist/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../src/prompts.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  GetPromptResult,\n  McpServer,\n  PromptMessage,\n  TextContent,\n} from '@modelcontextprotocol/server';\nimport { completable, getDisplayName, ProtocolError } from '@modelcontextprotocol/server';\n\nimport * as z from 'zod/v4';\n\nimport { formatUnknownErrorMessage, fsErrorCode, hasErrorShape } from './core/errors.js';\nimport { Logger } from './core/observability.js';\nimport { isBlank, SHELL_METACHAR_RE } from './core/schema.js';\nimport { buildSectionsRecord, INSTRUCTIONS_SUMMARY, renderSections } from './instructions.js';\n\n// --- Types ---\n\ninterface PromptContract {\n  readonly name: string;\n  readonly title: string;\n  readonly description: string;\n}\n\ninterface PromptRegistrarDeps {\n  readonly server: McpServer;\n  readonly readOnly?: boolean;\n}\n\n// --- Helpers ---\n\nfunction topicArg(\n  topics: readonly string[],\n  description: string,\n): ReturnType<typeof completable<z.ZodString>> {\n  return completable(\n    z\n      .string()\n      .min(1, { message: 'Topic required' })\n      .refine((val) => !isBlank(val), {\n        message: 'Topic cannot be empty or whitespace-only',\n      })\n      .refine((val) => !SHELL_METACHAR_RE.test(val), {\n        message: 'Topic contains prohibited characters (newlines or shell metacharacters)',\n      })\n      .describe(description),\n    (value) => {\n      const lower = value.toLowerCase();\n      return lower ? topics.filter((t) => t.startsWith(lower)) : [...topics];\n    },\n  );\n}\n\nfunction userText(text: string): PromptMessage {\n  const content: TextContent = {\n    type: 'text',\n    text,\n    annotations: { audience: ['assistant'], priority: 1 },\n  };\n  return { role: 'user', content };\n}\n\nasync function wrapHandler<T>(contract: PromptContract, fn: () => Promise<T> | T): Promise<T> {\n  const displayName = getDisplayName(contract);\n\n  try {\n    const result = await fn();\n    Logger.debug(`prompt resolved`, { name: contract.name, displayName });\n    return result;\n  } catch (error) {\n    if (hasErrorShape(error, 'ProtocolError')) throw error;\n    const message = formatUnknownErrorMessage(error);\n    Logger.error(`Prompt handler failed: ${message}`, {\n      promptName: contract.name,\n      error,\n    });\n    const protocolError = new ProtocolError(fsErrorCode(error), message);\n    protocolError.cause = error;\n    throw protocolError;\n  }\n}\n\n// --- Prompt entries ---\n\nconst GET_HELP: PromptContract = {\n  name: 'get-help',\n  title: 'Get Help',\n  description: INSTRUCTIONS_SUMMARY,\n};\n\nexport function registerPrompts(deps: PromptRegistrarDeps): void {\n  const sections = buildSectionsRecord(deps.readOnly ?? false);\n  const instructions = renderSections(sections);\n  const topics = Object.keys(sections);\n\n  deps.server.registerPrompt(\n    GET_HELP.name,\n    {\n      title: GET_HELP.title,\n      description: GET_HELP.description,\n      argsSchema: z.strictObject({\n        topic: topicArg(\n          topics,\n          `Section key to filter instructions (one of: ${topics.join(', ')}); omit to return all instructions.`,\n        ).optional(),\n      }),\n    },\n    ({ topic }: { topic?: string | undefined }): GetPromptResult | Promise<GetPromptResult> =>\n      wrapHandler(GET_HELP, () => {\n        const lowerTopic = topic?.toLowerCase();\n        const section =\n          lowerTopic && Object.hasOwn(sections, lowerTopic) ? sections[lowerTopic] : undefined;\n        if (topic && !section) {\n          Logger.debug('get-help: unknown topic requested', { topic });\n        }\n        const text =\n          section ??\n          (topic\n            ? `Section '${topic}' not found. Available: ${topics.join(', ')}\\n\\n${instructions}`\n            : instructions);\n        return {\n          description: GET_HELP.description,\n          messages: [userText(text)],\n        };\n      }),\n  );\n}\n"]}

package/dist/resources.d.ts

@@ -1,9 +1,73 @@
-import { type McpServer } from '@modelcontextprotocol/server';
-import type { ResourceStore } from './lib/resource-store.js';
-import { type IconInfo } from './tools/shared.js';
-export declare function registerInstructionResource(server: McpServer, instructions: string, iconInfo?: IconInfo): void;
-export declare function registerToolCatalogResource(server: McpServer, iconInfo?: IconInfo): void;
-export declare function registerWorkflowGuideResource(server: McpServer, iconInfo?: IconInfo): void;
-export declare function registerResultResources(server: McpServer, store: ResourceStore, iconInfo?: IconInfo): void;
-export declare function registerToolInfoResource(server: McpServer, iconInfo?: IconInfo): void;
-export declare function registerMetricsResource(server: McpServer, iconInfo?: IconInfo): void;
+import type { CacheHint, McpServer, ReadResourceResult, Resource, Role, ServerContext, ServerNotifier } from '@modelcontextprotocol/server';
+import type { PathGuard } from './core/path.js';
+import type { ResourceStore } from './core/store.js';
+import { type WatcherRegistry } from './core/watcher-registry.js';
+export interface ResourceRegistrationOptions {
+    resourceStore: ResourceStore;
+    pathGuard?: PathGuard;
+    /** Mirrors the `--read-only` gate so the instructions match the tools actually registered. */
+    readOnly: boolean;
+    /**
+     * Shared file-watcher registry for the modern (per-request) HTTP leg. When set,
+     * the resource uses this handler-scoped registry instead of creating its own
+     * per-server one, so file-change watchers persist across requests and publish
+     * to the shared ServerEventBus. Omitted (per-server registry) on legacy/stdio.
+     */
+    watcherRegistry?: WatcherRegistry;
+    /** Modern-leg typed notification publisher. */
+    notifier?: ServerNotifier;
+    /** The protocol era this instance serves; omitted where the caller does not know. */
+    era?: 'legacy' | 'modern';
+    /**
+     * Scope for shared-content cache hints. 'private' when the endpoint is
+     * API-key gated, mirroring the list hints in server.ts — a shared cache must
+     * not store an authenticated response body. Defaults to 'public'.
+     */
+    cacheScope?: 'public' | 'private';
+}
+type ResourceRegistrarDeps = Omit<ResourceRegistrationOptions, 'pathGuard' | 'readOnly'> & {
+    readonly server: McpServer;
+    readonly pathGuard: PathGuard;
+    readonly readOnly?: boolean;
+};
+interface BaseResourceContract {
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    cacheHint?: CacheHint;
+    annotations?: {
+        audience?: Role[];
+        priority?: number;
+    };
+    readonly read: (uri: URL, variables: Record<string, string | string[]>, ctx: ServerContext) => Promise<ReadResourceResult> | ReadResourceResult;
+    readonly subscribe?: (uri: string, notify: (uri: string) => void) => Promise<boolean | undefined> | boolean | undefined;
+    readonly unsubscribe?: (uri: string) => void;
+    readonly destroy?: () => void;
+    readonly list?: (ctx: ServerContext) => Promise<{
+        resources: Resource[];
+    }> | {
+        resources: Resource[];
+    };
+}
+/** A resource with a fixed, enumerable URI (e.g. internal://instructions). */
+interface StaticResourceContract extends BaseResourceContract {
+    uri: string;
+    uriTemplate?: never;
+    complete?: never;
+}
+/** A resource identified by a URI template (FILESYSTEM_FILE_URI_TEMPLATE). */
+interface TemplateResourceContract extends BaseResourceContract {
+    uriTemplate: string;
+    uri?: never;
+    complete?: (variable: string, value: string, ctx?: {
+        arguments?: Record<string, string>;
+    }) => Promise<string[]> | string[];
+}
+type ResourceContract = StaticResourceContract | TemplateResourceContract;
+export declare function getResourceContracts(options: ResourceRegistrationOptions): ResourceContract[];
+export declare function registerResources(deps: ResourceRegistrarDeps): {
+    dispose(): void;
+};
+export {};
+//# sourceMappingURL=resources.d.ts.map

package/dist/resources.d.ts.map

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