@j0hanz/filesystem-mcp 1.13.2 → 1.14.1

package/dist/lib/paths.js

@@ -1,12 +1,12 @@
-import * as fs from 'node:fs/promises';
-import * as os from 'node:os';
-import * as path from 'node:path';
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { platform } from 'node:os';
+import { realpath, stat } from 'node:fs/promises';
+import { homedir, platform } from 'node:os';
+import { dirname, isAbsolute, join, normalize, parse, posix, relative, resolve, sep, win32, } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { assertNotAborted, withAbort } from './abort.js';
 import { SENSITIVE_FILE_ALLOWLIST, SENSITIVE_FILE_DENYLIST, } from './constants.js';
 import { ErrorCode, isAbortError, isNodeError, McpError } from './errors.js';
-import { assertNotAborted, withAbort } from './fs-helpers.js';
+import { Logger } from './logger.js';
 const WINDOWS_PATH_SEPARATOR = '\\';
 const POSIX_PATH_SEPARATOR = '/';
 export function toPosixPath(value) {
@@ -20,7 +20,7 @@ const HOME_PREFIX_LENGTH = 2;
 const CHAR_CODE_SPACE = 32;
 const CHAR_CODE_DOT = 46;
 function normalizePathForMatch(input) {
-    return toPosixPath(path.normalize(input));
+    return toPosixPath(normalize(input));
 }
 function normalizeForMatch(input) {
     const normalized = normalizePathForMatch(input);
@@ -84,7 +84,7 @@ function matchesAnyGlobs(globs, candidates) {
         return false;
     for (const candidate of candidates) {
         for (const glob of globs) {
-            if (path.posix.matchesGlob(candidate, glob))
+            if (posix.matchesGlob(candidate, glob))
                 return true;
         }
     }
@@ -100,7 +100,7 @@ export function isSensitivePath(requestedPath, resolvedPath) {
         ? normalizeForMatch(resolvedPath)
         : undefined;
     const pathCandidates = uniquePair(normalizedRequested, normalizedResolved);
-    const nameCandidates = uniquePair(path.posix.basename(normalizedRequested), normalizedResolved ? path.posix.basename(normalizedResolved) : undefined);
+    const nameCandidates = uniquePair(posix.basename(normalizedRequested), normalizedResolved ? posix.basename(normalizedResolved) : undefined);
     if (matchesAnyGlobs(ALLOW_PATTERNS.pathGlobs, pathCandidates) ||
         matchesAnyGlobs(ALLOW_PATTERNS.nameGlobs, nameCandidates)) {
         return false;
@@ -111,11 +111,11 @@ export function isSensitivePath(requestedPath, resolvedPath) {
 export function assertAllowedFileAccess(requestedPath, resolvedPath) {
     if (!isSensitivePath(requestedPath, resolvedPath))
         return;
-    throw new McpError(ErrorCode.E_ACCESS_DENIED, `Access denied: sensitive file blocked by policy (${requestedPath}). ` +
-        'Set FS_CONTEXT_ALLOW_SENSITIVE=1 or use FS_CONTEXT_ALLOWLIST to override.', requestedPath);
+    Logger.warn(`Access denied: sensitive file blocked by policy (${requestedPath})`);
+    throw new McpError(ErrorCode.ACCESS_DENIED, 'Sensitive file blocked. Set FS_CONTEXT_ALLOW_SENSITIVE=1 to override.', requestedPath);
 }
-const HOMEDIR = os.homedir();
-const PATH_SEPARATOR = path.sep;
+const HOMEDIR = homedir();
+const PATH_SEPARATOR = sep;
 const DRIVE_LETTER_REGEX = /^[A-Za-z]:/;
 const WINDOWS_DRIVE_REL_REGEX = /^[A-Za-z]:$/u;
 const LEADING_SEPARATORS_RE = /^[/\\]+/;
@@ -160,11 +160,11 @@ function expandHome(filepath) {
         return HOMEDIR;
     // Accept both "~/" and "~\\" for cross-platform UX.
     if (filepath.startsWith('~/') || filepath.startsWith('~\\')) {
-        // Avoid `path.join(HOMEDIR, "/foo")` resetting to the filesystem root.
+        // Avoid `join(HOMEDIR, "/foo")` resetting to the filesystem root.
         const rest = filepath
             .slice(HOME_PREFIX_LENGTH)
             .replace(LEADING_SEPARATORS_RE, '');
-        return rest.length === 0 ? HOMEDIR : path.join(HOMEDIR, rest);
+        return rest.length === 0 ? HOMEDIR : join(HOMEDIR, rest);
     }
     return filepath;
 }
@@ -175,7 +175,7 @@ function expandHome(filepath) {
  * - Lowercases Windows drive letter for stable comparisons.
  */
 export function normalizePath(p) {
-    const resolved = path.resolve(expandHome(p));
+    const resolved = resolve(expandHome(p));
     if (IS_WINDOWS && DRIVE_LETTER_REGEX.test(resolved)) {
         return resolved.charAt(0).toLowerCase() + resolved.slice(1);
     }
@@ -194,8 +194,8 @@ function rethrowIfAborted(error) {
 function isSamePath(left, right) {
     if (left === right)
         return true;
-    const leftResolved = normalizeCaseForComparison(path.resolve(left));
-    const rightResolved = normalizeCaseForComparison(path.resolve(right));
+    const leftResolved = normalizeCaseForComparison(resolve(left));
+    const rightResolved = normalizeCaseForComparison(resolve(right));
     return leftResolved === rightResolved;
 }
 function stripTrailingSeparator(normalized) {
@@ -211,7 +211,7 @@ function normalizeAllowedDirectory(dir) {
     if (trimmed.length === 0)
         return '';
     const normalized = normalizePath(trimmed);
-    const { root } = path.parse(normalized);
+    const { root } = parse(normalized);
     // Keep filesystem roots as-is ("/", "c:\\", "\\\\server\\share\\").
     if (isFileSystemRootPath(normalized, root)) {
         return root;
@@ -274,14 +274,12 @@ function isPathInsideDirectory(normalizedDirectory, normalizedCandidate) {
     const candidate = normalizeForComparison(normalizedCandidate);
     if (root === candidate)
         return true;
-    const relative = path.relative(root, candidate);
-    if (relative.length === 0)
+    const rel = relative(root, candidate);
+    if (rel.length === 0)
         return true;
-    if (relative === '..')
+    if (rel === '..')
         return false;
-    return (!relative.startsWith('..\\') &&
-        !relative.startsWith('../') &&
-        !path.isAbsolute(relative));
+    return !rel.startsWith('..\\') && !rel.startsWith('../') && !isAbsolute(rel);
 }
 export function isPathWithinDirectories(normalizedPath, allowedDirs) {
     for (const allowedDir of allowedDirs) {
@@ -293,7 +291,7 @@ export function isPathWithinDirectories(normalizedPath, allowedDirs) {
 async function resolveRealPath(normalized, signal) {
     try {
         assertNotAborted(signal);
-        const realPath = await withAbort(fs.realpath(normalized), signal);
+        const realPath = await withAbort(realpath(normalized), signal);
         return normalizeAllowedDirectory(realPath);
     }
     catch (error) {
@@ -327,12 +325,12 @@ export async function setAllowedDirectoriesResolved(dirs, signal) {
 }
 function ensureNonEmptyPath(requestedPath) {
     if (!requestedPath || requestedPath.trim().length === 0) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Path cannot be empty or whitespace', requestedPath);
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Path cannot be empty or whitespace', requestedPath);
     }
 }
 function ensureNoNullBytes(requestedPath) {
     if (requestedPath.includes('\0')) {
-        throw new McpError(ErrorCode.E_INVALID_INPUT, 'Path contains null bytes', requestedPath);
+        throw new McpError(ErrorCode.INVALID_INPUT, 'Path contains null bytes', requestedPath);
     }
 }
 function getReservedDeviceName(segment) {
@@ -371,31 +369,31 @@ function ensureNoReservedWindowsNames(requestedPath) {
     const reserved = getReservedDeviceNameForPath(requestedPath);
     if (!reserved)
         return;
-    throw new McpError(ErrorCode.E_INVALID_INPUT, `Windows reserved device name not allowed: ${reserved}`, requestedPath);
+    throw new McpError(ErrorCode.INVALID_INPUT, `Windows reserved device name not allowed: ${reserved}`, requestedPath);
 }
 export function isWindowsDriveRelativePath(requestedPath) {
     if (!IS_WINDOWS)
         return false;
-    const parsed = path.win32.parse(requestedPath);
+    const parsed = win32.parse(requestedPath);
     if (!WINDOWS_DRIVE_REL_REGEX.test(parsed.root))
         return false;
-    return !path.win32.isAbsolute(requestedPath);
+    return !win32.isAbsolute(requestedPath);
 }
 function ensureNoWindowsDriveRelativePath(requestedPath) {
     if (!isWindowsDriveRelativePath(requestedPath))
         return;
-    throw new McpError(ErrorCode.E_INVALID_INPUT, 'Windows drive-relative paths are not allowed. Use C:\\path or C:/path instead of C:path.', requestedPath);
+    throw new McpError(ErrorCode.INVALID_INPUT, 'Drive-relative path not allowed. Use C:\\path instead of C:path.', requestedPath);
 }
 function resolveRequestedPath(requestedPath) {
     const expanded = expandHome(requestedPath);
-    if (!path.isAbsolute(expanded)) {
+    if (!isAbsolute(expanded)) {
         const roots = getAllowedDirectoriesForRelativeResolution();
         if (roots.length > 1) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, 'Relative paths are ambiguous when multiple roots are configured. Provide an absolute path or specify the full root path.', requestedPath);
+            throw new McpError(ErrorCode.INVALID_INPUT, 'Ambiguous relative path with multiple roots. Use an absolute path.', requestedPath);
         }
         const baseDir = roots[0];
         if (baseDir) {
-            return normalizePath(path.resolve(baseDir, expanded));
+            return normalizePath(resolve(baseDir, expanded));
         }
     }
     return normalizePath(expanded);
@@ -409,24 +407,24 @@ function validateRequestedPath(requestedPath) {
 }
 const NODE_ERROR_MAP = {
     ENOENT: {
-        code: ErrorCode.E_NOT_FOUND,
-        message: (requestedPath) => `Path does not exist: ${requestedPath}`,
+        code: ErrorCode.NOT_FOUND,
+        message: () => 'Path does not exist',
     },
     EACCES: {
-        code: ErrorCode.E_PERMISSION_DENIED,
-        message: (requestedPath) => `Permission denied accessing path: ${requestedPath}`,
+        code: ErrorCode.PERMISSION_DENIED,
+        message: () => 'Permission denied',
     },
     EPERM: {
-        code: ErrorCode.E_PERMISSION_DENIED,
-        message: (requestedPath) => `Permission denied accessing path: ${requestedPath}`,
+        code: ErrorCode.PERMISSION_DENIED,
+        message: () => 'Permission denied',
     },
     ELOOP: {
-        code: ErrorCode.E_SYMLINK_NOT_ALLOWED,
-        message: (requestedPath) => `Too many symbolic links in path (possible circular reference): ${requestedPath}`,
+        code: ErrorCode.SYMLINK_NOT_ALLOWED,
+        message: () => 'Too many symbolic links (circular reference)',
     },
     ENAMETOOLONG: {
-        code: ErrorCode.E_INVALID_INPUT,
-        message: (requestedPath) => `Path name too long: ${requestedPath}`,
+        code: ErrorCode.INVALID_INPUT,
+        message: () => 'Path name too long',
     },
 };
 function buildAllowedDirectoriesHint() {
@@ -448,26 +446,28 @@ function toMcpError(requestedPath, error) {
     else if (typeof error === 'string') {
         originalMessage = error;
     }
-    return new McpError(ErrorCode.E_NOT_FOUND, `Path is not accessible: ${requestedPath}`, requestedPath, { originalCode: code, originalMessage }, error);
+    return new McpError(ErrorCode.NOT_FOUND, 'Path is not accessible', requestedPath, { originalCode: code, originalMessage }, error);
 }
 function toAccessDeniedWithHint(requestedPath, resolvedPath, normalizedResolved) {
     const suggestion = buildAllowedDirectoriesHint();
-    return new McpError(ErrorCode.E_ACCESS_DENIED, `Access denied: Path '${requestedPath}' is outside allowed directories.\n${suggestion}`, requestedPath, { resolvedPath, normalizedResolvedPath: normalizedResolved });
+    return new McpError(ErrorCode.ACCESS_DENIED, `Outside allowed directories. ${suggestion}`, requestedPath, { resolvedPath, normalizedResolvedPath: normalizedResolved });
 }
 function ensureWithinAllowedDirectories(options) {
     const { normalizedPath, requestedPath, allowedDirs, details } = options;
     if (isPathWithinDirectories(normalizedPath, allowedDirs))
         return;
     if (allowedDirs.length === 0) {
-        throw new McpError(ErrorCode.E_ACCESS_DENIED, 'Access denied: No allowed directories configured. Use --allow-cwd or configure roots via the MCP Roots protocol.', requestedPath, details);
+        Logger.warn('Access denied: no allowed directories configured');
+        throw new McpError(ErrorCode.ACCESS_DENIED, 'No allowed directories configured. Use --allow-cwd or configure roots.', requestedPath, details);
     }
-    throw new McpError(ErrorCode.E_ACCESS_DENIED, `Access denied: Path '${requestedPath}' is outside allowed directories`, requestedPath, details);
+    Logger.warn(`Access denied: path outside allowed directories (${requestedPath})`);
+    throw new McpError(ErrorCode.ACCESS_DENIED, 'Outside allowed directories', requestedPath, details);
 }
 async function resolveRealPathOrThrow(options) {
     const { requestedPath, normalizedRequested, signal } = options;
     try {
         assertNotAborted(signal);
-        return await withAbort(fs.realpath(normalizedRequested), signal);
+        return await withAbort(realpath(normalizedRequested), signal);
     }
     catch (error) {
         rethrowIfAborted(error);
@@ -494,7 +494,7 @@ function ensureResolvedPathAllowed(options) {
 async function statPathOrThrow(requestedPath, resolvedPath, signal) {
     try {
         assertNotAborted(signal);
-        return await withAbort(fs.stat(resolvedPath), signal);
+        return await withAbort(stat(resolvedPath), signal);
     }
     catch (error) {
         rethrowIfAborted(error);
@@ -507,7 +507,7 @@ async function resolveNearestExistingRealPathOrThrow(options) {
     for (;;) {
         try {
             assertNotAborted(signal);
-            return await withAbort(fs.realpath(current), signal);
+            return await withAbort(realpath(current), signal);
         }
         catch (error) {
             rethrowIfAborted(error);
@@ -515,7 +515,7 @@ async function resolveNearestExistingRealPathOrThrow(options) {
             if (code !== 'ENOENT') {
                 throw toMcpError(requestedPath, error);
             }
-            const parent = path.dirname(current);
+            const parent = dirname(current);
             if (parent === current) {
                 throw toMcpError(requestedPath, error);
             }
@@ -554,7 +554,7 @@ export async function validateExistingDirectory(requestedPath, signal) {
     const details = await validateExistingPathDetailsInternal(requestedPath, signal);
     const stats = await statPathOrThrow(requestedPath, details.resolvedPath, signal);
     if (!stats.isDirectory()) {
-        throw new McpError(ErrorCode.E_NOT_DIRECTORY, `Not a directory: ${requestedPath}`, requestedPath);
+        throw new McpError(ErrorCode.NOT_DIRECTORY, 'Not a directory', requestedPath);
     }
     return details.resolvedPath;
 }
@@ -581,7 +581,7 @@ function isFileRoot(root) {
 async function maybeAddRealPath(normalizedPath, validDirs, signal) {
     try {
         assertNotAborted(signal);
-        const realPath = await withAbort(fs.realpath(normalizedPath), signal);
+        const realPath = await withAbort(realpath(normalizedPath), signal);
         const normalizedReal = normalizePath(realPath);
         if (!isSamePath(normalizedReal, normalizedPath)) {
             validDirs.push(normalizedReal);
@@ -596,7 +596,7 @@ async function resolveRootDirectory(root, signal) {
         const dirPath = fileURLToPath(root.uri);
         const normalizedPath = normalizePath(dirPath);
         assertNotAborted(signal);
-        const stats = await withAbort(fs.stat(normalizedPath), signal);
+        const stats = await withAbort(stat(normalizedPath), signal);
         if (!stats.isDirectory())
             return null;
         return normalizedPath;

package/dist/lib/resource-store.js

@@ -94,7 +94,7 @@ export function createInMemoryResourceStore(options = {}) {
                 bytes: entryBytes,
                 reason: 'entry_too_large',
             });
-            throw new McpError(ErrorCode.E_TOO_LARGE, `Resource too large to cache (${entryBytes} bytes)`);
+            throw new McpError(ErrorCode.TOO_LARGE, `Resource too large to cache (${entryBytes} bytes).`);
         }
         const contentHash = computeSha256(params.text);
         const indexKey = buildIndexKey(mimeType, contentHash);
@@ -146,7 +146,7 @@ export function createInMemoryResourceStore(options = {}) {
                 bytes: entry.size,
                 reason: 'evicted_immediately',
             });
-            throw new McpError(ErrorCode.E_TOO_LARGE, 'Resource cache full: entry evicted immediately');
+            throw new McpError(ErrorCode.TOO_LARGE, 'Cache full: entry evicted.');
         }
         return entry;
     }
@@ -158,7 +158,7 @@ export function createInMemoryResourceStore(options = {}) {
                 uri,
                 reason: 'not_found',
             });
-            throw new McpError(ErrorCode.E_NOT_FOUND, `Resource not found: ${uri}. The cached result may have been evicted. Re-run the originating tool to regenerate.`);
+            throw new McpError(ErrorCode.NOT_FOUND, `Resource not found: ${uri}. Re-run the tool to regenerate.`);
         }
         if (isExpired(existing)) {
             removeEntry(uri, 'expired');
@@ -167,7 +167,7 @@ export function createInMemoryResourceStore(options = {}) {
                 uri,
                 reason: 'expired',
             });
-            throw new McpError(ErrorCode.E_NOT_FOUND, `Resource expired: ${uri}. Re-run the originating tool to regenerate.`);
+            throw new McpError(ErrorCode.NOT_FOUND, `Resource expired: ${uri}. Re-run the tool to regenerate.`);
         }
         publishResourceStoreDiagnostics({
             phase: 'cache_hit',

package/dist/lib/utils.d.ts

@@ -5,15 +5,3 @@ export declare function debounce<Args extends unknown[]>(func: (...args: Args) =
 };
 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>;
-interface ProgressPayload {
-    current: number;
-    total?: number;
-}
-type ProgressCallback = ((progress: ProgressPayload) => void) | undefined;
-interface PeriodicProgressOptions {
-    total?: number;
-    throttleModulo?: number;
-    force?: boolean;
-}
-export declare function reportPeriodicProgress(onProgress: ProgressCallback, current: number, options?: PeriodicProgressOptions): void;
-export {};

package/dist/lib/utils.js

@@ -35,16 +35,3 @@ export function omitOptionKeys(input, keys) {
     }
     return output;
 }
-export function reportPeriodicProgress(onProgress, current, options = {}) {
-    if (!onProgress || current === 0)
-        return;
-    const throttleModulo = options.throttleModulo ?? 1;
-    const force = options.force ?? false;
-    if (!force && throttleModulo > 1 && current % throttleModulo !== 0) {
-        return;
-    }
-    onProgress({
-        current,
-        ...(options.total !== undefined ? { total: options.total } : {}),
-    });
-}

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

@@ -0,0 +1,2 @@
+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

@@ -0,0 +1,18 @@
+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,4 +1,5 @@
 export declare const pkgInfo: {
+    [x: string]: unknown;
     name: string;
     version: string;
     description?: string | undefined;

package/dist/pkg-info.js

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

package/dist/prompts.js

@@ -1,5 +1,5 @@
+import { ErrorCode as SdkErrorCode, McpError as SdkMcpError, } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { ErrorCode, McpError } from './lib/errors.js';
 import { buildToolInfo, getSortedToolContracts, } from './resources/tool-info.js';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
@@ -123,11 +123,11 @@ export function registerGetToolHelpPrompt(server, iconInfo) {
     }, ({ name }) => {
         const toolName = findKnownToolName(name);
         if (!toolName) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, `Unknown tool: ${name}`);
+            throw new SdkMcpError(SdkErrorCode.InvalidParams, `Unknown tool: ${name}`);
         }
         const toolInfo = buildToolInfo(toolName);
         if (!toolInfo) {
-            throw new McpError(ErrorCode.E_INVALID_INPUT, `Unknown tool: ${toolName}`);
+            throw new SdkMcpError(SdkErrorCode.InvalidParams, `Unknown tool: ${toolName}`);
         }
         return {
             description: GET_TOOL_HELP_PROMPT_DESCRIPTION,

package/dist/resources/generated-instructions.js

@@ -1,9 +1,6 @@
 import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
-import { buildCoreContextPack, formatToolNameList, getSharedConstraints, getTaskCapableToolNames, getTaskToolNamesBySupport, getToolContracts, pickAvailableToolNames, } from './tool-info.js';
+import { buildCoreContextPack, formatToolNameList, getSharedConstraints, getToolContracts, pickAvailableToolNames, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
-function formatTaskModeLine(label, names) {
-    return `${label}: ${names.length > 0 ? formatToolNameList(names) : 'none'}.`;
-}
 function buildToolsOverview() {
     const rows = [
         ['Navigate', pickAvailableToolNames(['roots', 'ls', 'tree', 'find'])],
@@ -31,58 +28,61 @@ function buildToolsOverview() {
         .join('\n');
 }
 function buildInstructionsHeader() {
-    const taskCapable = formatToolNameList(getTaskCapableToolNames());
-    const optionalTaskTools = getTaskToolNamesBySupport('optional');
-    const requiredTaskTools = getTaskToolNamesBySupport('required');
-    return `<role>
-Filesystem agent. Scope: allowed roots only. Discover paths before acting — never guess.
-</role>
+    return `## Role
+
+Secure filesystem agent. Operate strictly within allowed roots. Resolve paths before acting — never assume.
+
+## Tools Overview
 
-<tools_overview>
 | Category | Tools |
-|----------|-------|
+| -------- | ----- |
+
 ${buildToolsOverview()}
-</tools_overview>
 
-<resources>
-- \`internal://instructions\`: Full usage reference.
-- \`internal://tool-catalog\`: Tool routing and data flow.
-- \`internal://workflows\`: Standard execution sequences.
-- \`internal://tool-info/{name}\`: Per-tool nuances (e.g. \`internal://tool-info/read\`).
-- \`filesystem-mcp://result/{id}\`: Cached large output — call \`resources/read\` immediately when \`resourceUri\` is returned.
-- \`filesystem-mcp://metrics\`: Per-tool runtime metrics.
-</resources>
+## 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>
-Task execution: Call task-capable tools inline by default; add \`task\` only when durable polling or deferred results are needed.
-Task results: When a task is requested, poll via \`tasks/get\`, then retrieve the final payload via \`tasks/result\`.
-Progress: Pass \`_meta.progressToken\` in \`tools/call\` to receive \`notifications/progress\`.
-Task-capable: ${taskCapable || 'none'}.
-${formatTaskModeLine('Optional task mode', optionalTaskTools)}
-${formatTaskModeLine('Required task mode', requiredTaskTools)}
-</task_protocol>
+## 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>
+const INSTRUCTIONS_FOOTER = `## Constraints
+
 ${getSharedConstraints()
     .map((c) => `- ${c}`)
     .join('\n')}
-</constraints>
 
-<error_handling>
-- \`E_ACCESS_DENIED\` => call \`roots\`, use an allowed path.
-- \`E_NOT_FOUND\` => call \`ls\` or \`find\`, verify spelling.
-- \`E_TOO_LARGE\` => use \`head\`, line ranges, or \`read_many\`.
-- \`E_TIMEOUT\` => reduce scope or result limits.
-</error_handling>
+## 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) => `- Nuance: ${n}`));
+        parts.push(...tool.nuances.map((n) => `- ${n}`));
     }
     if (tool.gotchas && tool.gotchas.length > 0) {
-        parts.push(...tool.gotchas.map((g) => `- Gotcha: ${g}`));
+        parts.push(...tool.gotchas.map((g) => `- ⚠ ${g}`));
     }
     return parts.join('\n');
 }
@@ -94,9 +94,9 @@ export function buildServerInstructions() {
         '',
         buildToolCatalogDetailsOnly(),
         '',
-        '<tool_reference>',
+        '## Tool Reference',
+        '',
         toolSections,
-        '</tool_reference>',
         '',
         buildWorkflowGuide(),
         '',