@j0hanz/filesystem-mcp 1.2.3 → 1.3.0

package/dist/tools/task-support.d.ts

@@ -18,8 +18,10 @@ export declare function tryRegisterToolTask<Args extends ZodRawShapeCompat | Any
 export declare function registerToolTaskIfAvailable<Args extends ZodRawShapeCompat | AnySchema | undefined, Result>(server: McpServer, toolName: string, toolDef: object, run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, iconInfo: IconInfo | undefined, guard?: () => boolean): boolean;
 export declare function createToolTaskHandler<Result>(run: (args: undefined, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: {
     guard?: () => boolean;
+    toolName?: string;
 }): ToolTaskHandler;
 export declare function createToolTaskHandler<Args extends ZodRawShapeCompat | AnySchema, Result>(run: (args: ToolArgs<Args>, extra: TaskToolExtra) => Promise<ToolResult<Result>>, options?: {
     guard?: () => boolean;
+    toolName?: string;
 }): ToolTaskHandler<Args>;
 export {};

package/dist/tools/task-support.js

@@ -1,3 +1,4 @@
+import { channel } from 'node:diagnostics_channel';
 import { CallToolResultSchema } from '@modelcontextprotocol/sdk/types.js';
 import { ErrorCode, McpError } from '../lib/errors.js';
 import { isRecord } from '../lib/type-guards.js';
@@ -43,6 +44,12 @@ function hasTaskToolCapability(server) {
 }
 const RELATED_TASK_META_KEY = 'io.modelcontextprotocol/related-task';
 const TASK_STATUS_NOTIFICATION_METHOD = 'notifications/tasks/status';
+const TASK_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:tasks');
+function publishTaskDiagnostics(event) {
+    if (!TASK_DIAGNOSTICS_CHANNEL.hasSubscribers)
+        return;
+    TASK_DIAGNOSTICS_CHANNEL.publish(event);
+}
 function isRequestTaskStore(value) {
     if (!isRecord(value))
         return false;
@@ -174,7 +181,7 @@ function buildTaskStatusNotificationParams(task) {
         params.statusMessage = task.statusMessage;
     return params;
 }
-async function notifyTaskStatusIfPossible(extra, taskStore, taskId) {
+async function notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName) {
     const { sendNotification } = extra;
     if (typeof sendNotification !== 'function')
         return;
@@ -186,8 +193,19 @@ async function notifyTaskStatusIfPossible(extra, taskStore, taskId) {
             method: TASK_STATUS_NOTIFICATION_METHOD,
             params: buildTaskStatusNotificationParams(normalized),
         });
+        publishTaskDiagnostics({
+            phase: 'task_status_notified',
+            taskId,
+            status: normalized.status,
+            ...(toolName !== undefined ? { toolName } : {}),
+        });
     }
     catch {
+        publishTaskDiagnostics({
+            phase: 'task_status_notify_failed',
+            taskId,
+            ...(toolName !== undefined ? { toolName } : {}),
+        });
         // Never fail task execution because status notifications are optional.
     }
 }
@@ -234,18 +252,30 @@ async function tryStoreTaskResult(taskStore, taskId, status, result) {
         throw error;
     }
 }
-async function runTaskInBackground(run, args, extra, taskStore, taskId) {
+async function runTaskInBackground(run, args, extra, taskStore, taskId, toolName) {
     try {
         const result = maybeStripStructuredContentFromResult(await run(args, extra));
         const status = isErrorResult(result) ? 'failed' : 'completed';
         await tryStoreTaskResult(taskStore, taskId, status, result);
-        await notifyTaskStatusIfPossible(extra, taskStore, taskId);
+        publishTaskDiagnostics({
+            phase: 'task_result_stored',
+            taskId,
+            status,
+            ...(toolName !== undefined ? { toolName } : {}),
+        });
+        await notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName);
     }
     catch (error) {
         const fallback = maybeStripStructuredContentFromResult(buildToolErrorResponse(error, ErrorCode.E_UNKNOWN));
         try {
             await tryStoreTaskResult(taskStore, taskId, 'failed', fallback);
-            await notifyTaskStatusIfPossible(extra, taskStore, taskId);
+            publishTaskDiagnostics({
+                phase: 'task_result_stored',
+                taskId,
+                status: 'failed',
+                ...(toolName !== undefined ? { toolName } : {}),
+            });
+            await notifyTaskStatusIfPossible(extra, taskStore, taskId, toolName);
         }
         catch (innerError) {
             console.error(`Failed to store task failure result for task ${taskId}:`, innerError);
@@ -267,7 +297,10 @@ export function tryRegisterToolTask(server, toolName, toolDef, taskHandler, icon
     return true;
 }
 export function registerToolTaskIfAvailable(server, toolName, toolDef, run, iconInfo, guard) {
-    const taskOptions = guard ? { guard } : undefined;
+    const taskOptions = {
+        ...(guard ? { guard } : {}),
+        toolName,
+    };
     return tryRegisterToolTask(server, toolName, toolDef, createToolTaskHandler(run, taskOptions), iconInfo);
 }
 export function createToolTaskHandler(run, options) {
@@ -281,13 +314,21 @@ export function createToolTaskHandler(run, options) {
         const task = await taskStore.createTask({
             ttl: extra.taskRequestedTtl ?? null,
         });
+        publishTaskDiagnostics({
+            phase: 'task_created',
+            taskId: task.taskId,
+            status: task.status,
+            ...(options?.toolName !== undefined
+                ? { toolName: options.toolName }
+                : {}),
+        });
         const taskExtra = {
             ...extra,
             taskStore,
             taskId: task.taskId,
         };
-        void notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId);
-        void runTaskInBackground(run, args, taskExtra, taskStore, task.taskId);
+        void notifyTaskStatusIfPossible(taskExtra, taskStore, task.taskId, options?.toolName);
+        void runTaskInBackground(run, args, taskExtra, taskStore, task.taskId, options?.toolName);
         return { task };
     });
     const getTask = (async (argsOrExtra, maybeExtra) => {

package/dist/tools/tree.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const TREE_TOOL: ToolContract;
 export declare function registerTreeTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/tree.js

@@ -5,7 +5,8 @@ import { formatTreeAscii, treeDirectory } from '../lib/file-operations/tree.js';
 import { TreeInputSchema, TreeOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, executeToolWithDiagnostics, READ_ONLY_TOOL_ANNOTATIONS, resolvePathOrRoot, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const TREE_TOOL = {
+export const TREE_TOOL = {
+    name: 'tree',
     title: 'Tree',
     description: 'Render a directory tree (bounded recursion). ' +
         'Returns an ASCII tree for quick scanning and a structured JSON tree for programmatic use. ' +
@@ -13,6 +14,7 @@ const TREE_TOOL = {
     inputSchema: TreeInputSchema,
     outputSchema: TreeOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,
+    gotchas: ['`maxDepth=0` returns only the root node.'],
 };
 async function handleTree(args, signal) {
     const basePath = resolvePathOrRoot(args.path);
@@ -47,8 +49,7 @@ export function registerTreeTool(server, options = {}) {
             onError: (error) => buildToolErrorResponse(error, ErrorCode.E_NOT_DIRECTORY, targetPath),
         });
     };
-    const validatedHandler = withValidatedArgs(TreeInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
             if (args.path) {
@@ -69,7 +70,8 @@ export function registerTreeTool(server, options = {}) {
             return `≣ tree: ${base} • ${count} ${count === 1 ? 'entry' : 'entries'}`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'tree', TREE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(TreeInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'tree', TREE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('tree', withDefaultIcons({ ...TREE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('tree', withDefaultIcons({ ...TREE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools/write-file.d.ts

@@ -1,3 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type ToolRegistrationOptions } from './shared.js';
+import { type ToolContract, type ToolRegistrationOptions } from './shared.js';
+export declare const WRITE_FILE_TOOL: ToolContract;
 export declare function registerWriteFileTool(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools/write-file.js

@@ -6,12 +6,19 @@ import { validatePathForWrite } from '../lib/path-validation.js';
 import { WriteFileInputSchema, WriteFileOutputSchema } from '../schemas.js';
 import { buildToolErrorResponse, buildToolResponse, DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS, executeToolWithDiagnostics, withDefaultIcons, withValidatedArgs, wrapToolHandler, } from './shared.js';
 import { registerToolTaskIfAvailable } from './task-support.js';
-const WRITE_FILE_TOOL = {
+export const WRITE_FILE_TOOL = {
+    name: 'write',
     title: 'Write File',
     description: 'Write content to a file. Creates the file if it does not exist.',
     inputSchema: WriteFileInputSchema,
     outputSchema: WriteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
+    nuances: [
+        'Creates parent directories automatically; overwrites existing content.',
+    ],
+    gotchas: [
+        'Creates parent directories automatically; overwrites existing content.',
+    ],
 };
 async function handleWriteFile(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
@@ -34,8 +41,7 @@ export function registerWriteFileTool(server, options = {}) {
         run: (signal) => handleWriteFile(args, signal),
         onError: (error) => buildToolErrorResponse(error, ErrorCode.E_UNKNOWN, args.path),
     });
-    const validatedHandler = withValidatedArgs(WriteFileInputSchema, handler);
-    const wrappedHandler = wrapToolHandler(validatedHandler, {
+    const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => `🛠 write: ${path.basename(args.path)} [${args.content.length} chars]`,
         completionMessage: (args, result) => {
@@ -48,7 +54,8 @@ export function registerWriteFileTool(server, options = {}) {
             return `🛠 write: ${name} • ${sc.bytesWritten ?? 0} bytes`;
         },
     });
-    if (registerToolTaskIfAvailable(server, 'write', WRITE_FILE_TOOL, wrappedHandler, options.iconInfo, options.isInitialized))
+    const validatedHandler = withValidatedArgs(WriteFileInputSchema, wrappedHandler);
+    if (registerToolTaskIfAvailable(server, 'write', WRITE_FILE_TOOL, validatedHandler, options.iconInfo, options.isInitialized))
         return;
-    server.registerTool('write', withDefaultIcons({ ...WRITE_FILE_TOOL }, options.iconInfo), wrappedHandler);
+    server.registerTool('write', withDefaultIcons({ ...WRITE_FILE_TOOL }, options.iconInfo), validatedHandler);
 }

package/dist/tools.d.ts

@@ -1,4 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ToolContract } from './tools/contract.js';
 import type { ToolRegistrationOptions } from './tools/shared.js';
 export { buildToolErrorResponse, buildToolResponse } from './tools/shared.js';
+export declare const ALL_TOOLS: ToolContract[];
 export declare function registerAllTools(server: McpServer, options?: ToolRegistrationOptions): void;

package/dist/tools.js

@@ -1,22 +1,43 @@
-import { registerApplyPatchTool } from './tools/apply-patch.js';
-import { registerCalculateHashTool } from './tools/calculate-hash.js';
-import { registerCreateDirectoryTool } from './tools/create-directory.js';
-import { registerDeleteFileTool } from './tools/delete-file.js';
-import { registerDiffFilesTool } from './tools/diff-files.js';
-import { registerEditFileTool } from './tools/edit-file.js';
-import { registerListDirectoryTool } from './tools/list-directory.js';
-import { registerMoveFileTool } from './tools/move-file.js';
-import { registerReadMultipleFilesTool } from './tools/read-multiple.js';
-import { registerReadFileTool } from './tools/read.js';
-import { registerSearchAndReplaceTool } from './tools/replace-in-files.js';
-import { registerListAllowedDirectoriesTool } from './tools/roots.js';
-import { registerSearchContentTool } from './tools/search-content.js';
-import { registerSearchFilesTool } from './tools/search-files.js';
-import { registerGetMultipleFileInfoTool } from './tools/stat-many.js';
-import { registerGetFileInfoTool } from './tools/stat.js';
-import { registerTreeTool } from './tools/tree.js';
-import { registerWriteFileTool } from './tools/write-file.js';
+import { APPLY_PATCH_TOOL, registerApplyPatchTool, } from './tools/apply-patch.js';
+import { CALCULATE_HASH_TOOL, registerCalculateHashTool, } from './tools/calculate-hash.js';
+import {} from './tools/contract.js';
+import { CREATE_DIRECTORY_TOOL, registerCreateDirectoryTool, } from './tools/create-directory.js';
+import { DELETE_FILE_TOOL, registerDeleteFileTool, } from './tools/delete-file.js';
+import { DIFF_FILES_TOOL, registerDiffFilesTool } from './tools/diff-files.js';
+import { EDIT_FILE_TOOL, registerEditFileTool } from './tools/edit-file.js';
+import { LIST_DIRECTORY_TOOL, registerListDirectoryTool, } from './tools/list-directory.js';
+import { MOVE_FILE_TOOL, registerMoveFileTool } from './tools/move-file.js';
+import { READ_MULTIPLE_FILES_TOOL, registerReadMultipleFilesTool, } from './tools/read-multiple.js';
+import { READ_FILE_TOOL, registerReadFileTool } from './tools/read.js';
+import { registerSearchAndReplaceTool, SEARCH_AND_REPLACE_TOOL, } from './tools/replace-in-files.js';
+import { LIST_ALLOWED_DIRECTORIES_TOOL, registerListAllowedDirectoriesTool, } from './tools/roots.js';
+import { registerSearchContentTool, SEARCH_CONTENT_TOOL, } from './tools/search-content.js';
+import { registerSearchFilesTool, SEARCH_FILES_TOOL, } from './tools/search-files.js';
+import { GET_MULTIPLE_FILE_INFO_TOOL, registerGetMultipleFileInfoTool, } from './tools/stat-many.js';
+import { GET_FILE_INFO_TOOL, registerGetFileInfoTool } from './tools/stat.js';
+import { registerTreeTool, TREE_TOOL } from './tools/tree.js';
+import { registerWriteFileTool, WRITE_FILE_TOOL } from './tools/write-file.js';
 export { buildToolErrorResponse, buildToolResponse } from './tools/shared.js';
+export const ALL_TOOLS = [
+    LIST_ALLOWED_DIRECTORIES_TOOL,
+    LIST_DIRECTORY_TOOL,
+    SEARCH_FILES_TOOL,
+    TREE_TOOL,
+    READ_FILE_TOOL,
+    READ_MULTIPLE_FILES_TOOL,
+    GET_FILE_INFO_TOOL,
+    GET_MULTIPLE_FILE_INFO_TOOL,
+    SEARCH_CONTENT_TOOL,
+    CREATE_DIRECTORY_TOOL,
+    WRITE_FILE_TOOL,
+    EDIT_FILE_TOOL,
+    MOVE_FILE_TOOL,
+    DELETE_FILE_TOOL,
+    CALCULATE_HASH_TOOL,
+    DIFF_FILES_TOOL,
+    APPLY_PATCH_TOOL,
+    SEARCH_AND_REPLACE_TOOL,
+];
 const TOOL_REGISTRARS = [
     registerListAllowedDirectoriesTool,
     registerListDirectoryTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",
@@ -22,7 +22,6 @@
   ],
   "scripts": {
     "clean": "node scripts/tasks.mjs clean",
-    "validate:instructions": "node scripts/tasks.mjs validate:instructions",
     "build": "node scripts/tasks.mjs build",
     "copy:assets": "node scripts/tasks.mjs copy:assets",
     "prepare": "npm run build",

package/dist/instructions.md

@@ -1,200 +0,0 @@
-# FILESYSTEM-MCP INSTRUCTIONS
-
-These instructions are available as a resource (internal://instructions) or prompt (get-help). Load them when unsure about tool usage.
-
----
-
-## CORE CAPABILITY
-
-- Domain: Filesystem operations via an MCP server for LLM agents that need safe read/search/edit/diff/patch workflows within allowed roots.
-- Primary Resources: Files, directories, metadata, search matches, and ephemeral cached result resources.
-- Tools: READ: `roots`, `ls`, `find`, `tree`, `read`, `read_many`, `stat`, `stat_many`, `grep`, `calculate_hash`, `diff_files`. WRITE: `mkdir`, `write`, `edit`, `mv`, `rm`, `apply_patch`, `search_and_replace`.
-
----
-
-## PROMPTS
-
-- `get-help`: Returns these instructions for quick recall.
-
----
-
-## RESOURCES & RESOURCE LINKS
-
-- `internal://instructions`: This document.
-- `filesystem-mcp://result/{id}`: Ephemeral cached tool output (in-memory); used when payloads are externalized.
-- If a tool response includes a `resourceUri` or `resource_link`, call `resources/read` with that URI to fetch full content.
-
----
-
-## PROGRESS & TASKS
-
-- Include `_meta.progressToken` in requests to receive `notifications/progress` updates for long-running tools.
-- Task-augmented tool calls are supported for `find`, `tree`, `read`, `read_many`, `stat_many`, `grep`, `mkdir`, `write`, `mv`, `rm`, `calculate_hash`, `apply_patch`, and `search_and_replace`:
-  - Send `tools/call` with `task` to create a task.
-  - Poll `tasks/get` and fetch final output with `tasks/result`.
-  - Use `tasks/cancel` to abort.
-  - Task status notifications are emitted via `notifications/tasks/status` when supported.
-
----
-
-## THE "GOLDEN PATH" WORKFLOWS (CRITICAL)
-
-### WORKFLOW A: DISCOVER AND INSPECT
-
-- Call `roots` first to get allowed workspace roots.
-- Call `ls` for non-recursive listing, or `tree` for bounded recursive overview.
-- Call `stat` or `stat_many` to confirm path types/sizes before reading.
-- Call `read` for one file or `read_many` for batches.
-  NOTE: Never guess paths. Resolve from `roots`/`ls`/`find` first.
-
-### WORKFLOW B: SEARCH CONTENT SAFELY
-
-- Call `find` to locate candidate files by glob.
-- Call `grep` with `filePattern` to search content only in relevant file types.
-- If output is truncated or externalized, call `resources/read` on returned `resourceUri`.
-- Call `read` on exact hits to inspect surrounding context.
-  NOTE: `grep` regex uses RE2; do not rely on lookbehind/lookahead/backreferences.
-
-### WORKFLOW C: MODIFY FILES WITH LOW RISK
-
-- Call `mkdir` to prepare directories if needed.
-- Use `edit` for precise first-occurrence replacements in one file.
-- Use `search_and_replace` for bulk replacements across globs.
-- Use `mv` to rename/move paths and `rm` to delete paths.
-  NOTE: Confirm destructive operations (`write`, `mv`, `rm`, bulk replace) with the user before execution.
-
-### WORKFLOW D: DIFF/PATCH LOOP
-
-- Call `diff_files` to generate a unified diff.
-- Call `apply_patch` with `dryRun: true` first.
-- If dry run succeeds, call `apply_patch` again with `dryRun: false`.
-- Call `diff_files` again to verify `isIdentical: true` when expected.
-  NOTE: If patch apply fails, regenerate patch against current file content and retry.
-
----
-
-## TOOL NUANCES & GOTCHAS
-
-`roots`
-
-- Purpose: Enumerate allowed workspace roots.
-- Gotcha: Other tools are constrained to these roots.
-
-`ls`
-
-- Purpose: List directory contents (non-recursive by default).
-- Nuance: `pattern` enables filtered recursive traversal up to `maxDepth`.
-
-`find`
-
-- Purpose: Find files by glob.
-- Output: Returns relative paths plus metadata; may truncate based on limits.
-- Nuance: Respects `.gitignore` unless `includeIgnored=true`.
-
-`tree`
-
-- Purpose: Return both ASCII and JSON tree views.
-- Gotcha: `maxDepth=0` returns only the root node.
-
-`read`
-
-- Purpose: Read a single text file with optional head/range.
-- Gotcha: Large content is externalized to `filesystem-mcp://result/{id}` and preview is returned inline.
-
-`read_many`
-
-- Purpose: Batch read multiple files.
-- Gotcha: Per-file `truncationReason` can be `head`, `range`, or `externalized`.
-- Limits: Total read budget is capped by `MAX_READ_MANY_TOTAL_SIZE`.
-
-`stat` / `stat_many`
-
-- Purpose: Return metadata including token estimate, MIME type, and timestamps.
-- Nuance: Use before read/search when file size/type uncertainty exists.
-
-`grep`
-
-- Purpose: Search file contents by literal or RE2 regex.
-- Gotcha: Inline match rows are capped (first 50); full structured results are externalized via `resourceUri`.
-- Limits: Skips binary and oversized files; reports skips in structured output.
-
-`write`
-
-- Purpose: Create or overwrite a file atomically.
-- Side effects: Creates parent directories automatically; overwrites existing content.
-
-`edit`
-
-- Purpose: Apply sequential literal replacements (first occurrence per edit).
-- Gotcha: `oldText` must match exactly; unmatched items are reported in `unmatchedEdits`.
-
-`mv`
-
-- Purpose: Move or rename file/directory paths.
-- Nuance: Cross-device moves fall back to copy+delete.
-
-`rm`
-
-- Purpose: Delete file/directory paths.
-- Gotcha: Non-empty directory delete requires `recursive=true`; else returns actionable input error.
-
-`calculate_hash`
-
-- Purpose: SHA-256 for files or deterministic composite hash for directories.
-- Nuance: Directory hashing respects root `.gitignore` and sorts paths for stable output.
-
-`diff_files`
-
-- Purpose: Generate unified diff between two files.
-- Gotcha: `isIdentical=true` means no hunks (`@@`) and empty diff.
-
-`apply_patch`
-
-- Purpose: Apply unified diff text to a file.
-- Gotcha: Patch must include valid hunk headers; use `dryRun=true` first.
-
-`search_and_replace`
-
-- Purpose: Replace all matches across files selected by `filePattern`.
-- Gotcha: Literal mode is default; `isRegex=true` enables RE2 + capture replacements (`$1`, `$2`).
-- Limits: Changed-file sample and failure sample are capped/truncated in output.
-
----
-
-## CROSS-FEATURE RELATIONSHIPS
-
-- Use `roots` output to scope all other tool calls.
-- Use `find` → `grep` → `read` as the default search triad.
-- Use `diff_files` output as input to `apply_patch`.
-- Use `resourceUri` from `read`, `read_many`, `grep`, and `diff_files` with `resources/read` for full payload retrieval.
-- Use `stat`/`stat_many` before `read`/`read_many` when size/type may violate limits.
-
----
-
-## CONSTRAINTS & LIMITATIONS
-
-- Access is restricted to allowed roots negotiated from CLI and MCP Roots.
-- If multiple roots are configured and no path is provided, tools requiring base path fail with disambiguation error.
-- Default timeouts and size caps are enforced (`DEFAULT_SEARCH_TIMEOUT`, `MAX_FILE_SIZE`, `MAX_SEARCH_SIZE`, `MAX_READ_MANY_TOTAL_SIZE`).
-- Sensitive files are denylisted by default unless explicitly allowed via environment settings.
-- Binary files are skipped for content search/read workflows where text is required.
-- Externalized resource cache is in-memory, bounded (entry size/count/total bytes), and ephemeral.
-- Regex engine is RE2-based; advanced PCRE features are unsupported.
-
----
-
-## ERROR HANDLING STRATEGY
-
-- `E_ACCESS_DENIED`: Path is outside allowed roots or roots are not configured. → Call `roots`, then retry with an allowed path.
-- `E_NOT_FOUND`: Path or resource does not exist. → Call `ls`/`find` to verify existence and exact spelling.
-- `E_NOT_FILE`: Path points to a directory/non-file for file-only operation. → Call `ls` or switch to directory tool.
-- `E_NOT_DIRECTORY`: Path points to a file for directory operation. → Call `read` for file content or choose a directory path.
-- `E_TOO_LARGE`: File/content exceeds limits. → Narrow scope, use range/head reads, or reduce candidate files.
-- `E_TIMEOUT`: Operation exceeded timeout. → Reduce path scope, lower result limits, or simplify pattern.
-- `E_INVALID_PATTERN`: Glob/regex invalid. → Fix syntax (RE2 for regex) and retry.
-- `E_INVALID_INPUT`: Arguments are invalid for current context (e.g., ambiguous roots, bad patch, missing flags). → Correct parameters and retry.
-- `E_PERMISSION_DENIED`: OS-level permission denied. → Adjust file permissions or choose accessible paths.
-- `E_SYMLINK_NOT_ALLOWED`: Symlink traversal escapes allowed roots. → Use paths within allowed directories.
-- `E_UNKNOWN`: Unclassified failure. → Inspect message details and retry with narrower, validated inputs.
-
----