@j0hanz/filesystem-mcp 1.8.0 → 1.9.1

package/dist/lib/{path-validation.js → paths.js}

@@ -1,10 +1,114 @@
 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 { fileURLToPath } from 'node:url';
+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';
-const IS_WINDOWS = os.platform() === 'win32';
+const WINDOWS_PATH_SEPARATOR = '\\';
+const POSIX_PATH_SEPARATOR = '/';
+export function toPosixPath(value) {
+    return value.includes(WINDOWS_PATH_SEPARATOR)
+        ? value.replace(/\\/gu, POSIX_PATH_SEPARATOR)
+        : value;
+}
+const IS_WINDOWS = platform() === 'win32';
+const WINDOWS_ABSOLUTE_RE = /^[a-z]:\//iu;
+function normalizePathForMatch(input) {
+    return toPosixPath(path.normalize(input));
+}
+function normalizeForMatch(input) {
+    const normalized = normalizePathForMatch(input);
+    return IS_WINDOWS ? normalized.toLowerCase() : normalized;
+}
+function compilePatternGlobs(normalizedPattern) {
+    const globs = new Set([normalizedPattern]);
+    const isWindowsAbsolute = WINDOWS_ABSOLUTE_RE.test(normalizedPattern);
+    if (!normalizedPattern.startsWith('**/') && !isWindowsAbsolute) {
+        const withoutRoot = normalizedPattern.replace(/^\/+/u, '');
+        if (withoutRoot.length > 0) {
+            globs.add(`**/${withoutRoot}`);
+        }
+    }
+    return [...globs];
+}
+function compilePatterns(patterns) {
+    const unique = new Set();
+    for (const pattern of patterns) {
+        const trimmed = pattern.trim();
+        if (trimmed.length > 0) {
+            unique.add(trimmed);
+        }
+    }
+    const compiled = [];
+    for (const pattern of unique) {
+        const normalized = normalizeForMatch(pattern);
+        const matchesPath = normalized.includes('/');
+        compiled.push({
+            globs: matchesPath ? compilePatternGlobs(normalized) : [normalized],
+            matchesPath,
+        });
+    }
+    return compiled;
+}
+function toPatternSet(patterns) {
+    const pathGlobs = new Set();
+    const nameGlobs = new Set();
+    for (const pattern of patterns) {
+        const target = pattern.matchesPath ? pathGlobs : nameGlobs;
+        for (const glob of pattern.globs) {
+            target.add(glob);
+        }
+    }
+    return {
+        pathGlobs: [...pathGlobs],
+        nameGlobs: [...nameGlobs],
+    };
+}
+const DENY_PATTERNS = toPatternSet(compilePatterns(SENSITIVE_FILE_DENYLIST));
+const ALLOW_PATTERNS = toPatternSet(compilePatterns(SENSITIVE_FILE_ALLOWLIST));
+function uniquePair(primary, secondary) {
+    if (!secondary || secondary === primary)
+        return [primary];
+    return [primary, secondary];
+}
+function matchesAnyGlobs(globs, candidates) {
+    if (globs.length === 0 || candidates.length === 0)
+        return false;
+    for (const candidate of candidates) {
+        for (const glob of globs) {
+            if (path.posix.matchesGlob(candidate, glob))
+                return true;
+        }
+    }
+    return false;
+}
+export function isSensitivePath(requestedPath, resolvedPath) {
+    if (DENY_PATTERNS.pathGlobs.length === 0 &&
+        DENY_PATTERNS.nameGlobs.length === 0) {
+        return false;
+    }
+    const normalizedRequested = normalizeForMatch(requestedPath);
+    const normalizedResolved = resolvedPath
+        ? normalizeForMatch(resolvedPath)
+        : undefined;
+    const pathCandidates = uniquePair(normalizedRequested, normalizedResolved);
+    const nameCandidates = uniquePair(path.posix.basename(normalizedRequested), normalizedResolved ? path.posix.basename(normalizedResolved) : undefined);
+    if (matchesAnyGlobs(ALLOW_PATTERNS.pathGlobs, pathCandidates) ||
+        matchesAnyGlobs(ALLOW_PATTERNS.nameGlobs, nameCandidates)) {
+        return false;
+    }
+    return (matchesAnyGlobs(DENY_PATTERNS.pathGlobs, pathCandidates) ||
+        matchesAnyGlobs(DENY_PATTERNS.nameGlobs, nameCandidates));
+}
+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);
+}
 const HOMEDIR = os.homedir();
 const PATH_SEPARATOR = path.sep;
 const DRIVE_LETTER_REGEX = /^[A-Za-z]:/;
@@ -34,9 +138,18 @@ const RESERVED_DEVICE_NAMES = new Set([
     'LPT8',
     'LPT9',
 ]);
+const allowedDirectoriesContext = new AsyncLocalStorage({
+    name: 'filesystem-mcp:allowed-directories',
+});
 function dedupePreserveOrder(items) {
     return [...new Set(items)];
 }
+function cloneAllowedDirectoriesState(state) {
+    return {
+        primary: [...state.primary],
+        expanded: [...state.expanded],
+    };
+}
 function expandHome(filepath) {
     if (filepath === '~')
         return HOMEDIR;
@@ -115,26 +228,41 @@ function normalizeAllowedDirectories(dirs) {
 // single MCP session per process, so this is safe. In HTTP mode all HTTP
 // sessions within the same process share one policy — multi-tenant isolation
 // (different roots per session) requires separate server processes.
-let allowedDirectoriesExpanded = [];
-let allowedDirectoriesPrimary = [];
+let defaultAllowedDirectoriesState = {
+    primary: [],
+    expanded: [],
+};
 function setAllowedDirectoriesState(primary, expanded) {
-    allowedDirectoriesPrimary = dedupePreserveOrder(primary);
-    allowedDirectoriesExpanded = dedupePreserveOrder(expanded);
+    defaultAllowedDirectoriesState = {
+        primary: dedupePreserveOrder(primary),
+        expanded: dedupePreserveOrder(expanded),
+    };
+}
+function getActiveAllowedDirectoriesState() {
+    return allowedDirectoriesContext.getStore() ?? defaultAllowedDirectoriesState;
+}
+export function withAllowedDirectoriesState(state, run) {
+    return allowedDirectoriesContext.run(cloneAllowedDirectoriesState(state), run);
+}
+export function getAllowedDirectoriesState() {
+    return cloneAllowedDirectoriesState(getActiveAllowedDirectoriesState());
+}
+export function setAllowedDirectoriesStateResolved(state) {
+    setAllowedDirectoriesState(state.primary, state.expanded);
 }
 export function getAllowedDirectories() {
-    return [...allowedDirectoriesExpanded];
+    return [...getActiveAllowedDirectoriesState().expanded];
 }
 export function isAllowedDirectoryRoot(normalizedPath) {
-    for (const dir of allowedDirectoriesExpanded) {
+    for (const dir of getActiveAllowedDirectoriesState().expanded) {
         if (isSamePath(normalizedPath, dir))
             return true;
     }
     return false;
 }
 function getAllowedDirectoriesForRelativeResolution() {
-    return allowedDirectoriesPrimary.length > 0
-        ? allowedDirectoriesPrimary
-        : allowedDirectoriesExpanded;
+    const state = getActiveAllowedDirectoriesState();
+    return state.primary.length > 0 ? state.primary : state.expanded;
 }
 function isPathInsideDirectory(normalizedDirectory, normalizedCandidate) {
     const root = normalizeForComparison(normalizedDirectory);
@@ -183,10 +311,14 @@ async function expandAllowedDirectories(primaryDirs, signal) {
     }
     return dedupePreserveOrder(expanded);
 }
-export async function setAllowedDirectoriesResolved(dirs, signal) {
+export async function resolveAllowedDirectoriesState(dirs, signal) {
     const primary = normalizeAllowedDirectories(dirs);
     const expanded = await expandAllowedDirectories(primary, signal);
-    setAllowedDirectoriesState(primary, expanded);
+    return { primary, expanded };
+}
+export async function setAllowedDirectoriesResolved(dirs, signal) {
+    const state = await resolveAllowedDirectoriesState(dirs, signal);
+    setAllowedDirectoriesStateResolved(state);
 }
 function ensureNonEmptyPath(requestedPath) {
     if (!requestedPath || requestedPath.trim().length === 0) {
@@ -393,6 +525,7 @@ export async function validatePathForWrite(requestedPath, signal) {
         allowedDirs,
         details: { normalizedPath: normalizedRequested },
     });
+    assertAllowedFileAccess(requestedPath, normalizedRequested);
     let current = normalizedRequested;
     for (;;) {
         try {

package/dist/lib/utils.d.ts

@@ -0,0 +1,15 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+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>;
+export declare function setIfDefined<T extends object, K extends keyof T>(target: T, key: K, value: T[K] | undefined): void;
+export interface ProgressPayload {
+    current: number;
+    total?: number;
+}
+export type ProgressCallback = ((progress: ProgressPayload) => void) | undefined;
+export interface PeriodicProgressOptions {
+    total?: number;
+    throttleModulo?: number;
+    force?: boolean;
+}
+export declare function reportPeriodicProgress(onProgress: ProgressCallback, current: number, options?: PeriodicProgressOptions): void;

package/dist/lib/utils.js

@@ -0,0 +1,33 @@
+// type-guards.ts
+export function isRecord(value) {
+    return value !== null && typeof value === 'object';
+}
+// 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;
+}
+export function setIfDefined(target, key, value) {
+    if (value !== undefined) {
+        target[key] = value;
+    }
+}
+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/resources/generated-instructions.js

@@ -2,7 +2,7 @@ import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
 import { buildCoreContextPack, getSharedConstraints, getToolContracts, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
 const INSTRUCTIONS_HEADER = `<role>
-Filesystem agent for local paths only. Operate inside allowed roots. Discover before action. Never guess paths.
+Filesystem agent. Scope: allowed roots only. Discover paths before acting — never guess.
 </role>
 
 <tools_overview>
@@ -16,10 +16,10 @@ Filesystem agent for local paths only. Operate inside allowed roots. Discover be
 
 <resources>
 - \`internal://instructions\`: Full usage reference.
-- \`internal://tool-catalog\`: Tool routing and data-flow rules.
+- \`internal://tool-catalog\`: Tool routing and data flow.
 - \`internal://workflows\`: Standard execution sequences.
-- \`internal://tool-info/{name}\`: Per-tool nuances and gotchas (example: \`internal://tool-info/read\`).
-- \`filesystem-mcp://result/{id}\`: Cached large output. If \`resourceUri\` is returned, call \`resources/read\` immediately.
+- \`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>
 
@@ -35,8 +35,8 @@ ${getSharedConstraints()
 </constraints>
 
 <error_handling>
-- \`E_ACCESS_DENIED\` => call \`roots\`, then use an allowed path.
-- \`E_NOT_FOUND\` => call \`ls\` or \`find\`, then verify spelling.
+- \`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>

package/dist/resources/tool-catalog.js

@@ -3,26 +3,26 @@ const CATALOG_GUIDE = `<tool_selection_guide>
 ## Cross-Tool Data Flow
 
 \`\`\`
-find (results[].path) -> grep.paths
-diff_files (patch text) -> apply_patch.patch
+find(results[].path) -> grep.paths
+diff_files(patch) -> apply_patch.patch
 \`\`\`
 
 ## Search Strategy
 
-- Use \`find\` for glob file discovery.
-- Use \`grep\` for text search.
-- Use \`search_and_replace\` only for replacement, never discovery.
+- \`find\`: glob file discovery.
+- \`grep\`: text content search.
+- \`search_and_replace\`: replacement only, not discovery.
 
 ## Write Strategy
 
-- Use \`edit\` for precise, first-occurrence replacements in existing files.
-- Use \`write\` to create files or overwrite full contents.
-- Use \`search_and_replace\` for bulk multi-file replacements.
+- \`edit\`: precise first-occurrence replacements.
+- \`write\`: create files or overwrite full contents.
+- \`search_and_replace\`: bulk multi-file replacements.
 
 ## Patch Management
 
 - Generate patches with \`diff_files\` first.
-- Run \`apply_patch\` with \`dryRun: true\` before writing.
+- Validate with \`apply_patch(dryRun:true)\` before writing.
 - \`apply_patch\` accepts unified diffs only.
 </tool_selection_guide>
 `;

package/dist/resources/tool-info.js

@@ -37,10 +37,10 @@ export function buildCoreContextPack() {
 }
 export function getSharedConstraints() {
     return [
-        'Use allowed roots only (provided by CLI negotiation).',
+        'Use allowed roots only (from CLI negotiation).',
         'Sensitive paths are denylisted by default.',
-        `Limits are enforced: max file size ${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB; search caps ${MAX_SEARCH_RESULTS} files and ${DEFAULT_SEARCH_CONTENT_RESULTS} lines.`,
-        'If a response includes `resourceUri`, call `resources/read` immediately; cached results expire on process restart.',
+        `Limits enforced: max file size ${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB; search caps ${MAX_SEARCH_RESULTS} files, ${DEFAULT_SEARCH_CONTENT_RESULTS} content matches.`,
+        'If response includes `resourceUri`, call `resources/read` immediately — cached results expire on restart.',
     ];
 }
 export function buildToolInfo(name) {

package/dist/resources/workflows.js

@@ -1,33 +1,20 @@
 export function buildWorkflowGuide() {
     return `<workflows>
-### A: EXPLORE
-Use when: you need directory layout or file content.
-1. \`roots\` (list allowed paths).
-2. \`ls\` (flat view) or \`tree\` (recursive view).
-3. \`stat\` or \`stat_many\` (type and size checks).
-4. \`read\` or \`read_many\` (read content).
+### A: EXPLORE — directory layout or file content
+1. \`roots\` → \`ls\` or \`tree\` → \`stat\`/\`stat_many\` → \`read\`/\`read_many\`.
    > **Strict:** Resolve paths first. Never guess.
 
-### B: SEARCH
-Use when: you need files by pattern or content.
-1. \`find\` (glob candidates).
-2. \`grep\` (content matches).
-3. \`read\` (verify matched context).
-   > **Strict:** Do content search with \`grep\`, not \`find\`.
+### B: SEARCH — files by pattern or content
+1. \`find\` (glob) → \`grep\` (content) → \`read\` (verify).
+   > **Strict:** Content search with \`grep\`, not \`find\`.
 
-### C: EDIT
-Use when: you need to modify files or layout.
-1. \`edit\` (targeted string replacement).
-2. \`search_and_replace\` (bulk replacements).
-3. \`mv\` or \`rm\` (layout changes).
-4. \`mkdir\` (directory creation).
+### C: EDIT — modify files or layout
+1. \`edit\` (targeted replacement) or \`search_and_replace\` (bulk).
+2. \`mv\`/\`rm\` (layout) or \`mkdir\` (create dirs).
    > **Strict:** Confirm destructive ops (\`write\`, \`mv\`, \`rm\`, bulk replace).
 
-### D: PATCH
-Use when: applying unified diffs from \`diff_files\`.
-1. \`diff_files\` (generate).
-2. \`apply_patch\` (dryRun: true).
-3. \`apply_patch\` (dryRun: false).
+### D: PATCH — apply unified diffs
+1. \`diff_files\` → \`apply_patch(dryRun:true)\` → \`apply_patch\`.
    > **Tip:** Feed \`diff_files\` output directly to \`apply_patch\`.
 </workflows>`;
 }

package/dist/schemas.d.ts

@@ -34,13 +34,13 @@ export declare const ToolErrorResponseSchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 declare const HeadLinesSchema: z.ZodOptional<z.ZodInt>;
-declare const LineNumberSchema: z.ZodNumber;
+declare const LineNumberSchema: z.ZodInt;
 export declare const ListDirectoryInputSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
     includeHidden: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeIgnored: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    maxDepth: z.ZodOptional<z.ZodNumber>;
-    maxEntries: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxDepth: z.ZodOptional<z.ZodInt>;
+    maxEntries: z.ZodDefault<z.ZodOptional<z.ZodInt>>;
     sortBy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         name: "name";
         size: "size";
@@ -55,7 +55,7 @@ export declare const ListAllowedDirectoriesInputSchema: z.ZodObject<{}, z.core.$
 export declare const SearchFilesInputSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
     pattern: z.ZodString;
-    maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxResults: z.ZodDefault<z.ZodOptional<z.ZodInt>>;
     includeIgnored: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeHidden: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     sortBy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
@@ -64,13 +64,13 @@ export declare const SearchFilesInputSchema: z.ZodObject<{
         path: "path";
         modified: "modified";
     }>>>;
-    maxDepth: z.ZodOptional<z.ZodNumber>;
+    maxDepth: z.ZodOptional<z.ZodInt>;
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const TreeInputSchema: z.ZodObject<{
     path: z.ZodOptional<z.ZodString>;
-    maxDepth: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    maxEntries: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    maxDepth: z.ZodDefault<z.ZodOptional<z.ZodInt>>;
+    maxEntries: z.ZodDefault<z.ZodOptional<z.ZodInt>>;
     includeHidden: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeIgnored: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strict>;
@@ -80,8 +80,8 @@ export declare const SearchContentInputSchema: z.ZodObject<{
     isRegex: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     caseSensitive: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     wholeWord: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    contextLines: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    contextLines: z.ZodDefault<z.ZodOptional<z.ZodInt>>;
+    maxResults: z.ZodDefault<z.ZodOptional<z.ZodInt>>;
     filePattern: z.ZodDefault<z.ZodOptional<z.ZodString>>;
     includeHidden: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeIgnored: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
@@ -658,7 +658,7 @@ export declare const CalculateHashOutputSchema: z.ZodObject<{
 export declare const DiffFilesInputSchema: z.ZodObject<{
     original: z.ZodString;
     modified: z.ZodString;
-    context: z.ZodOptional<z.ZodNumber>;
+    context: z.ZodOptional<z.ZodInt>;
     ignoreWhitespace: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     stripTrailingCr: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strict>;
@@ -691,7 +691,7 @@ export declare const DiffFilesOutputSchema: z.ZodObject<{
 export declare const ApplyPatchInputSchema: z.ZodObject<{
     path: z.ZodString;
     patch: z.ZodString;
-    fuzzFactor: z.ZodOptional<z.ZodNumber>;
+    fuzzFactor: z.ZodOptional<z.ZodInt>;
     autoConvertLineEndings: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     dryRun: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strict>;

package/dist/schemas.js

@@ -16,8 +16,8 @@ function isSafeGlobPattern(value) {
     return true;
 }
 const MAX_PATH_LENGTH = 4096;
-const DESC_PATH_ROOT = 'Base directory (default: root). Absolute path required if multiple roots exist. Examples: "src", "src/components"';
-const DESC_PATH_REQUIRED = 'Absolute path to file or directory. Examples: "src/index.ts", "README.md"';
+const DESC_PATH_ROOT = 'Base directory (default: root). Absolute path required if multiple roots.';
+const DESC_PATH_REQUIRED = 'Absolute path to file or directory.';
 function defaultFalseBoolean(description) {
     return z.boolean().optional().default(false).describe(description);
 }
@@ -57,10 +57,7 @@ const HeadLinesSchema = z
     .max(100000, 'Max: 100,000')
     .optional()
     .describe('Read first N lines');
-const LineNumberSchema = z
-    .number()
-    .int({ error: 'Must be integer' })
-    .min(1, 'Min: 1');
+const LineNumberSchema = z.int({ error: 'Must be integer' }).min(1, 'Min: 1');
 function addReadRangeIssue(ctx, path, message) {
     ctx.addIssue({
         code: 'custom',
@@ -115,14 +112,12 @@ export const ListDirectoryInputSchema = z.strictObject({
     includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
     includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, .git, etc).'),
     maxDepth: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(1, 'Min: 1')
         .max(MAX_TREE_DEPTH, `Max: ${MAX_TREE_DEPTH}`)
         .optional()
         .describe('Max recursion depth when pattern is provided'),
     maxEntries: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(1, 'Min: 1')
         .max(MAX_LIST_ENTRIES, `Max: ${MAX_LIST_ENTRIES}`)
@@ -158,7 +153,6 @@ export const SearchFilesInputSchema = z.strictObject({
     })
         .describe('Glob pattern (e.g. "**/*.ts", "src/*.js")'),
     maxResults: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(1, 'Min: 1')
         .max(MAX_SEARCH_RESULTS, `Max: ${MAX_SEARCH_RESULTS}`)
@@ -171,7 +165,6 @@ export const SearchFilesInputSchema = z.strictObject({
         .default('path')
         .describe('Sort by path, name, size, or modified'),
     maxDepth: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
         .max(MAX_SEARCH_DEPTH, `Max: ${MAX_SEARCH_DEPTH}`)
@@ -185,7 +178,6 @@ export const SearchFilesInputSchema = z.strictObject({
 export const TreeInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
     maxDepth: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
         .max(MAX_TREE_DEPTH, `Max: ${MAX_TREE_DEPTH}`)
@@ -193,7 +185,6 @@ export const TreeInputSchema = z.strictObject({
         .default(DEFAULT_TREE_DEPTH)
         .describe(`Depth (0=root node only, no children). Default: ${DEFAULT_TREE_DEPTH}`),
     maxEntries: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(1, 'Min: 1')
         .max(MAX_TREE_ENTRIES, `Max: ${MAX_TREE_ENTRIES}`)
@@ -209,12 +200,11 @@ export const SearchContentInputSchema = z.strictObject({
         .string()
         .min(1, 'Pattern required')
         .max(1000, 'Max 1000 chars')
-        .describe('Literal text to search for by default; treated as RE2 regex when isRegex is true.'),
-    isRegex: defaultFalseBoolean('Treat pattern as a RE2 regular expression. RE2 does not support lookahead, lookbehind, or backreferences.'),
-    caseSensitive: defaultFalseBoolean('Case-sensitive matching (default: false — searches are case-insensitive).'),
+        .describe('Search text. RE2 regex when `isRegex=true`.'),
+    isRegex: defaultFalseBoolean('Treat pattern as RE2 regex (no lookahead/lookbehind/backrefs).'),
+    caseSensitive: defaultFalseBoolean('Case-sensitive matching. Default: case-insensitive.'),
     wholeWord: defaultFalseBoolean('Match whole words only'),
     contextLines: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
         .max(50, 'Max: 50')
@@ -222,7 +212,6 @@ export const SearchContentInputSchema = z.strictObject({
         .default(0)
         .describe('Include N lines of context before/after matches'),
     maxResults: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
         .max(MAX_SEARCH_RESULTS, `Max: ${MAX_SEARCH_RESULTS}`)
@@ -434,7 +423,7 @@ export const CreateDirectoryInputSchema = z
         .describe('Absolute paths to directories to create'),
 })
     .refine((data) => data.path !== undefined || data.paths !== undefined, {
-    message: "Either 'path' or 'paths' must be provided",
+    error: "Either 'path' or 'paths' must be provided",
     path: ['path'],
 });
 export const CreateDirectoryOutputSchema = z.strictObject({
@@ -459,15 +448,15 @@ export const EditFileInputSchema = z.strictObject({
         .array(z.strictObject({
         oldText: z
             .string()
-            .describe('Exact literal string to replace — must match character-for-character including whitespace and indentation. Include 3–5 lines of surrounding context to uniquely identify the location.'),
+            .describe('Exact literal string to replace (character-for-character). Include 3–5 lines of context for unique targeting.'),
         newText: z
             .string()
-            .describe('Replacement string — preserve the indentation style of surrounding code.'),
+            .describe('Replacement string. Preserve surrounding indentation style.'),
     }))
         .min(1, 'Min 1 edit required')
         .describe('List of replacements to apply sequentially. Each edit replaces the first occurrence of oldText.'),
-    dryRun: defaultFalseBoolean('Preview edits without writing. Check unmatchedEdits in the response to verify all oldText values were found.'),
-    ignoreWhitespace: defaultFalseBoolean('Ignore leading/trailing whitespace and treat all whitespace sequences as equivalent when matching oldText.'),
+    dryRun: defaultFalseBoolean('Preview edits without writing. Check `unmatchedEdits` in response.'),
+    ignoreWhitespace: defaultFalseBoolean('Treat all whitespace sequences as equivalent when matching oldText.'),
 });
 export const EditFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -490,7 +479,7 @@ export const MoveFileInputSchema = z
     destination: RequiredPathSchema.describe('New path'),
 })
     .refine((data) => (data.source ?? data.sources) !== undefined, {
-    message: "Either 'source' or 'sources' must be provided",
+    error: "Either 'source' or 'sources' must be provided",
     path: ['source'],
 });
 export const MoveFileOutputSchema = z.strictObject({
@@ -535,7 +524,6 @@ export const DiffFilesInputSchema = z.strictObject({
     original: RequiredPathSchema.describe('Path to original file'),
     modified: RequiredPathSchema.describe('Path to modified file'),
     context: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
         .max(10000, 'Max: 10,000')
@@ -564,9 +552,8 @@ export const ApplyPatchInputSchema = z.strictObject({
     path: RequiredPathSchema.describe('Path to file to patch'),
     patch: z
         .string()
-        .describe('Unified diff content to apply — must include @@ hunk headers. Generate with `diff_files`.'),
+        .describe('Unified diff with @@ hunk headers. Generate with `diff_files`.'),
     fuzzFactor: z
-        .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
         .max(20, 'Max: 20')
@@ -581,7 +568,7 @@ export const ApplyPatchInputSchema = z.strictObject({
         .boolean()
         .optional()
         .default(false)
-        .describe('Validate the patch can be applied without writing. Check `applied` in the response before committing.'),
+        .describe('Validate patch without writing. Check `applied` before committing.'),
 });
 export const ApplyPatchOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -602,18 +589,18 @@ export const SearchAndReplaceInputSchema = z.strictObject({
     searchPattern: z
         .string()
         .min(1, 'Search pattern required')
-        .describe('Text to search for. Matched literally by default; treated as RE2 regex when isRegex is true.'),
+        .describe('Text to search for. Literal by default; RE2 regex when `isRegex=true`.'),
     replacement: z.string().describe('Replacement text'),
-    isRegex: defaultFalseBoolean('Treat searchPattern as a RE2 regular expression. Supports capture group references ($1, $2) in replacement.'),
+    isRegex: defaultFalseBoolean('Treat searchPattern as RE2 regex. Supports capture groups ($1, $2) in replacement.'),
     dryRun: defaultFalseBoolean('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
     includeHidden: z
         .boolean()
         .optional()
-        .describe('Include hidden files and directories (starting with .) in the search scope. Default: false.'),
+        .describe('Include hidden files/directories (starting with .). Default: false.'),
     includeIgnored: z
         .boolean()
         .optional()
-        .describe('Include files and directories ignored by .gitignore rules (e.g. node_modules, dist). Default: false.'),
+        .describe('Include .gitignore-ignored files (node_modules, dist). Default: false.'),
     returnDiff: z
         .boolean()
         .optional()