@j0hanz/filesystem-mcp 1.7.2 → 1.7.3

package/dist/lib/file-operations/search-files.js

@@ -3,9 +3,9 @@ import { DEFAULT_SEARCH_MAX_FILES, DEFAULT_SEARCH_TIMEOUT_MS, } from '../constan
 import { createTimedAbortSignal } from '../fs-helpers.js';
 import { isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
-import { needsStatsForSort, withOptionalStoppedReason } from './common.js';
+import { compareOptionalNumberDesc, compareStringValues, isEntryAccessibleByType, needsStatsForSort, resolveEntryType, resolveStopReason, stableSortByDerivedString, withOptionalStoppedReason, } from './common.js';
 import { isIgnoredByGitignore, loadRootGitignore } from './gitignore.js';
-import { globEntries, resolveEntryType } from './glob-engine.js';
+import { globEntries } from './glob-engine.js';
 // Internal default for find tool - not exposed to MCP users
 const INTERNAL_MAX_RESULTS = 1000;
 function normalizeOptions(options) {
@@ -41,17 +41,17 @@ function buildSearchResult(entry, entryType, needsStats) {
         ...(modified !== undefined ? { modified } : {}),
     };
 }
-function markStopped(state, reason) {
-    state.truncated = true;
-    state.stoppedReason = reason;
-}
 function shouldStopCollecting(state, normalized, signal) {
-    if (signal.aborted) {
-        markStopped(state, 'timeout');
-        return true;
-    }
-    if (state.filesScanned >= normalized.maxFilesScanned) {
-        markStopped(state, 'maxFiles');
+    const stopReason = resolveStopReason({
+        signal,
+        current: state.filesScanned,
+        max: normalized.maxFilesScanned,
+        abortedReason: 'timeout',
+        maxReason: 'maxFiles',
+    });
+    if (stopReason !== undefined) {
+        state.truncated = true;
+        state.stoppedReason = stopReason;
         return true;
     }
     return false;
@@ -99,7 +99,8 @@ function buildCollectResult(state) {
 function handleEntry(entry, entryType, needsStats, normalized, state) {
     state.results.push(buildSearchResult(entry, entryType, needsStats));
     if (state.results.length >= normalized.maxResults) {
-        markStopped(state, 'maxResults');
+        state.truncated = true;
+        state.stoppedReason = 'maxResults';
     }
 }
 function reportSearchFilesProgress(onProgress, current, total, force = false) {
@@ -109,7 +110,7 @@ function reportSearchFilesProgress(onProgress, current, total, force = false) {
         return;
     onProgress({ current, total });
 }
-async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, onProgress) {
+async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, accessDeps, onProgress) {
     for await (const entry of stream) {
         if (shouldStopCollecting(state, normalized, signal))
             break;
@@ -122,7 +123,7 @@ async function collectFromStream(stream, root, rootDirectories, gitignoreMatcher
         if (!shouldIncludeEntry(entryType, normalized)) {
             continue;
         }
-        const isAccessible = await isEntryAccessible(entry, entryType, rootDirectories, signal);
+        const isAccessible = await isEntryAccessibleByType(entry.path, entryType, rootDirectories, signal, accessDeps);
         if (!isAccessible) {
             state.skippedInaccessible++;
             continue;
@@ -138,31 +139,21 @@ function isEntryIgnoredByGitignore(matcher, root, entryPath, relativePath) {
         return false;
     return isIgnoredByGitignore(matcher, root, entryPath, relativePath ? { relativePath } : {});
 }
-async function isEntryAccessible(entry, entryType, rootDirectories, signal) {
-    if (entryType === 'symlink') {
-        try {
-            const validated = await validateExistingPathDetailed(entry.path, signal);
-            return !isSensitivePath(validated.requestedPath, validated.resolvedPath);
-        }
-        catch {
-            return false;
-        }
-    }
-    const resolvedPath = normalizePath(entry.path);
-    if (!isPathWithinDirectories(resolvedPath, rootDirectories)) {
-        return false;
-    }
-    return !isSensitivePath(entry.path, resolvedPath);
-}
 async function collectSearchResults(root, pattern, excludePatterns, normalized, signal, onProgress) {
     const needsStats = needsStatsForSort(normalized.sortBy);
     const stream = buildSearchStream(root, pattern, excludePatterns, normalized, needsStats);
     const state = createCollectState();
     const rootDirectories = [root];
+    const accessDeps = {
+        normalizePath,
+        isPathWithinDirectories,
+        isSensitivePath,
+        validateSymlinkPath: validateExistingPathDetailed,
+    };
     const gitignoreMatcher = normalized.respectGitignore
         ? await loadRootGitignore(root, signal)
         : null;
-    await collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, onProgress);
+    await collectFromStream(stream, root, rootDirectories, gitignoreMatcher, normalized, needsStats, state, signal, accessDeps, onProgress);
     return buildCollectResult(state);
 }
 function buildSearchSummary(results, filesScanned, truncated, stoppedReason, skippedInaccessible) {
@@ -174,27 +165,17 @@ function buildSearchSummary(results, filesScanned, truncated, stoppedReason, ski
     };
     return withOptionalStoppedReason(summary, stoppedReason);
 }
-const collator = new Intl.Collator(undefined, { numeric: true });
-function compareString(a, b) {
-    return collator.compare(a ?? '', b ?? '');
-}
 function compareNameThenPath(a, b) {
-    const nameCompare = compareString(a.name, b.name);
+    const nameCompare = compareStringValues(a.name, b.name);
     if (nameCompare !== 0)
         return nameCompare;
-    return compareString(a.path, b.path);
+    return compareStringValues(a.path, b.path);
 }
 function comparePathThenName(a, b) {
-    const pathCompare = compareString(a.path, b.path);
+    const pathCompare = compareStringValues(a.path, b.path);
     if (pathCompare !== 0)
         return pathCompare;
-    return compareString(a.name, b.name);
-}
-function compareOptionalNumberDesc(left, right, tieBreak) {
-    const diff = (right ?? 0) - (left ?? 0);
-    if (diff !== 0)
-        return diff;
-    return tieBreak();
+    return compareStringValues(a.name, b.name);
 }
 const SORT_COMPARATORS = {
     size: (a, b) => compareOptionalNumberDesc(a.size, b.size, () => compareNameThenPath(a, b)),
@@ -204,32 +185,7 @@ const SORT_COMPARATORS = {
 };
 export function sortSearchResults(results, sortBy) {
     if (sortBy === 'name') {
-        const decorated = [];
-        for (let index = 0; index < results.length; index += 1) {
-            const item = results[index];
-            if (!item)
-                continue;
-            decorated.push({
-                item,
-                baseName: path.basename(item.path ?? ''),
-                index,
-            });
-        }
-        decorated.sort((a, b) => {
-            const baseCompare = compareString(a.baseName, b.baseName);
-            if (baseCompare !== 0)
-                return baseCompare;
-            const pathCompare = compareString(a.item.path, b.item.path);
-            if (pathCompare !== 0)
-                return pathCompare;
-            return a.index - b.index;
-        });
-        for (let index = 0; index < decorated.length; index += 1) {
-            const entry = decorated[index];
-            if (entry) {
-                results[index] = entry.item;
-            }
-        }
+        stableSortByDerivedString(results, (item) => path.basename(item.path ?? ''), (left, right) => comparePathThenName(left, right));
         return;
     }
     const comparator = SORT_COMPARATORS[sortBy];

package/dist/lib/file-operations/tree.d.ts

@@ -1,7 +1,7 @@
-type TreeEntryType = 'file' | 'directory' | 'symlink' | 'other';
+import type { EntryType } from './common.js';
 interface TreeEntry {
     name: string;
-    type: TreeEntryType;
+    type: EntryType;
     relativePath: string;
     children?: TreeEntry[];
 }

package/dist/lib/file-operations/tree.js

@@ -4,8 +4,9 @@ import { createTimedAbortSignal } from '../fs-helpers.js';
 import { toPosixPath } from '../path-format.js';
 import { isSensitivePath } from '../path-policy.js';
 import { isPathWithinDirectories, normalizePath, validateExistingDirectory, validateExistingPathDetailed, } from '../path-validation.js';
+import { isEntryAccessibleByType, resolveEntryType, resolveStopReason, } from './common.js';
 import { isIgnoredByGitignore, loadRootGitignore } from './gitignore.js';
-import { globEntries, resolveEntryType } from './glob-engine.js';
+import { globEntries } from './glob-engine.js';
 function toSafeNonNegativeInt(value, fallback) {
     if (typeof value !== 'number' || !Number.isFinite(value))
         return fallback;
@@ -90,36 +91,11 @@ function getTreeTypeRank(type) {
         return 1;
     return 2;
 }
-function getStopReason(signal, totalEntries, maxEntries) {
-    if (signal.aborted) {
-        return 'aborted';
-    }
-    if (totalEntries >= maxEntries) {
-        return 'maxEntries';
-    }
-    return undefined;
-}
-async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal) {
+async function resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps) {
     const type = resolveEntryType(entry.dirent);
-    if (type !== 'symlink') {
-        const normalized = normalizePath(entry.path);
-        if (!isPathWithinDirectories(normalized, rootDirectories)) {
-            return null;
-        }
-        if (isSensitivePath(entry.path, normalized)) {
-            return null;
-        }
-    }
-    else {
-        try {
-            const validated = await validateExistingPathDetailed(entry.path, signal);
-            if (isSensitivePath(validated.requestedPath, validated.resolvedPath)) {
-                return null;
-            }
-        }
-        catch {
-            return null;
-        }
+    const isAccessible = await isEntryAccessibleByType(entry.path, type, rootDirectories, signal, accessDeps);
+    if (!isAccessible) {
+        return null;
     }
     if (gitignoreMatcher &&
         isIgnoredByGitignore(gitignoreMatcher, root, entry.path, {
@@ -222,6 +198,12 @@ export async function treeDirectory(dirPath, options = {}) {
     const root = await validateExistingDirectory(dirPath, signal);
     const rootNormalized = normalizePath(root);
     const rootDirectories = [rootNormalized];
+    const accessDeps = {
+        normalizePath,
+        isPathWithinDirectories,
+        isSensitivePath,
+        validateSymlinkPath: validateExistingPathDetailed,
+    };
     try {
         const excludePatterns = normalized.includeIgnored
             ? []
@@ -253,12 +235,18 @@ export async function treeDirectory(dirPath, options = {}) {
             suppressErrors: true,
         });
         for await (const entry of stream) {
-            const stopReason = getStopReason(signal, totalEntries, normalized.maxEntries);
+            const stopReason = resolveStopReason({
+                signal,
+                current: totalEntries,
+                max: normalized.maxEntries,
+                abortedReason: 'aborted',
+                maxReason: 'maxEntries',
+            });
             if (stopReason) {
                 truncated = true;
                 break;
             }
-            const resolved = await resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal);
+            const resolved = await resolveTreeEntry(entry, root, rootDirectories, gitignoreMatcher, signal, accessDeps);
             if (!resolved) {
                 continue;
             }

package/dist/prompts.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { withDefaultIcons } from './tools/shared.js';
 const HELP_PROMPT_NAME = 'get-help';
 const HELP_PROMPT_TITLE = 'Get Help';
-const HELP_PROMPT_DESCRIPTION = 'Retrieve the full filesystem-mcp XML usage guide.';
+const HELP_PROMPT_DESCRIPTION = 'Return filesystem-mcp usage instructions.';
 function filterInstructionsByTopic(instructions, topic) {
     const normalized = topic.trim().toLowerCase();
     if (!normalized)
@@ -16,7 +16,7 @@ function filterInstructionsByTopic(instructions, topic) {
         .map((sec) => sec.split('\n')[0]?.replace(/^##\s*/u, '') ?? '')
         .filter(Boolean)
         .join(', ');
-    return `Section '${topic}' not found. Available sections: ${available}\n\n${instructions}`;
+    return `Section '${topic}' not found. Available: ${available}\n\n${instructions}`;
 }
 export function registerGetHelpPrompt(server, instructions, iconInfo) {
     const baseConfig = withDefaultIcons({ title: HELP_PROMPT_TITLE, description: HELP_PROMPT_DESCRIPTION }, iconInfo);
@@ -26,7 +26,7 @@ export function registerGetHelpPrompt(server, instructions, iconInfo) {
             topic: z
                 .string()
                 .optional()
-                .describe('Section heading prefix to filter (e.g. "error handling strategy"). Omit for full instructions.'),
+                .describe('Optional section heading prefix (example: "error handling"). Omit to return full instructions.'),
         },
     }, ({ topic }) => {
         const text = topic

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>
-Expert filesystem agent. Operate ONLY within allowed roots. Always discover before acting — never guess paths.
+Filesystem agent for local paths only. Operate inside allowed roots. Discover before action. Never guess paths.
 </role>
 
 <tools_overview>
@@ -15,16 +15,16 @@ Expert filesystem agent. Operate ONLY within allowed roots. Always discover befo
 </tools_overview>
 
 <resources>
-- \`internal://instructions\`: Full server usage guide.
-- \`internal://tool-catalog\`: Tool routing and cross-tool data-flow guide.
-- \`internal://workflows\`: Standard operating sequences (explore/search/edit/patch).
-- \`internal://tool-info/{name}\`: Per-tool details (nuances/gotchas), e.g. \`internal://tool-info/read\`.
-- \`filesystem-mcp://result/{id}\`: Large output cache. Call \`resources/read\` immediately if \`resourceUri\` is returned.
-- \`filesystem-mcp://metrics\`: Live per-tool stats.
+- \`internal://instructions\`: Full usage reference.
+- \`internal://tool-catalog\`: Tool routing and data-flow rules.
+- \`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.
+- \`filesystem-mcp://metrics\`: Per-tool runtime metrics.
 </resources>
 
 <task_protocol>
-Async execution: provide \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, call \`tasks/result\`.
+Async execution: pass \`_meta.progressToken\` in \`tools/call\`, poll \`tasks/get\`, then call \`tasks/result\`.
 Task-capable: \`find\`, \`tree\`, \`read\`, \`read_many\`, \`stat_many\`, \`grep\`, \`mkdir\`, \`write\`, \`mv\`, \`rm\`, \`calculate_hash\`, \`apply_patch\`, \`search_and_replace\`.
 </task_protocol>
 `;
@@ -35,19 +35,19 @@ ${getSharedConstraints()
 </constraints>
 
 <error_handling>
-- \`E_ACCESS_DENIED\` → Call \`roots\`; use allowed path.
-- \`E_NOT_FOUND\`     → Call \`ls\`/\`find\`; verify spelling.
-- \`E_TOO_LARGE\`     → Use range/head or \`read_many\`.
-- \`E_TIMEOUT\`       → Reduce scope or result limits.
+- \`E_ACCESS_DENIED\` => call \`roots\`, then use an allowed path.
+- \`E_NOT_FOUND\` => call \`ls\` or \`find\`, then verify spelling.
+- \`E_TOO_LARGE\` => use \`head\`, line ranges, or \`read_many\`.
+- \`E_TIMEOUT\` => reduce scope or result limits.
 </error_handling>
 `;
 function formatToolSection(tool) {
     const parts = [`### ${tool.name}\n${tool.description}`];
     if (tool.nuances && tool.nuances.length > 0) {
-        parts.push(...tool.nuances.map((n) => `» ${n}`));
+        parts.push(...tool.nuances.map((n) => `- Nuance: ${n}`));
     }
     if (tool.gotchas && tool.gotchas.length > 0) {
-        parts.push(...tool.gotchas.map((g) => `⚠ ${g}`));
+        parts.push(...tool.gotchas.map((g) => `- Gotcha: ${g}`));
     }
     return parts.join('\n');
 }

package/dist/resources/tool-catalog.js

@@ -9,21 +9,21 @@ diff_files (patch text) -> apply_patch.patch
 
 ## Search Strategy
 
-- Use \`find\` for glob-based file discovery.
-- Use \`grep\` for content-based searches.
-- Use \`search_and_replace\` ONLY for bulk replacements, not for discovery.
+- Use \`find\` for glob file discovery.
+- Use \`grep\` for text search.
+- Use \`search_and_replace\` only for replacement, never discovery.
 
 ## Write Strategy
 
-- Use \`edit\` for precise, single-occurrence string replacements in existing files.
-- Use \`write\` to create new files or completely overwrite existing content.
-- Use \`search_and_replace\` for bulk regex replacements across multiple files.
+- 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.
 
 ## Patch Management
 
-- Always generate a patch with \`diff_files\` first.
-- Always use \`dryRun: true\` with \`apply_patch\` to verify changes.
-- \`apply_patch\` works on unified diff format.
+- Generate patches with \`diff_files\` first.
+- Run \`apply_patch\` with \`dryRun: true\` before writing.
+- \`apply_patch\` accepts unified diffs only.
 </tool_selection_guide>
 `;
 export function buildToolCatalog() {

package/dist/resources/tool-info.js

@@ -37,10 +37,10 @@ export function buildCoreContextPack() {
 }
 export function getSharedConstraints() {
     return [
-        'Allowed roots only (negotiated via CLI).',
-        'Sensitive files denylisted by default.',
-        `Max file size (${Math.floor(MAX_TEXT_FILE_SIZE / 1024 / 1024)}MB) & search results (${MAX_SEARCH_RESULTS} files, ${DEFAULT_SEARCH_CONTENT_RESULTS} lines) enforced.`,
-        'If a response includes `resourceUri`, call `resources/read` immediately — results expire on process restart.',
+        'Use allowed roots only (provided by 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.',
     ];
 }
 export function buildToolInfo(name) {
@@ -49,7 +49,7 @@ export function buildToolInfo(name) {
         return undefined;
     const lines = [`## ${entry.name}`, '', entry.description];
     if (entry.annotations && entry.annotations.length > 0) {
-        lines.push('', `**Annotations:** ${entry.annotations.join(', ')}`);
+        lines.push('', `**Hints:** ${entry.annotations.join(', ')}`);
     }
     if (entry.nuances && entry.nuances.length > 0) {
         lines.push('', '**Nuances:**');

package/dist/resources/workflows.js

@@ -1,33 +1,33 @@
 export function buildWorkflowGuide() {
     return `<workflows>
 ### A: EXPLORE
-Use when: navigating an unfamiliar directory or reading file content.
-1. \`roots\` (List allowed paths).
-2. \`ls\` (files) | \`tree\` (structure).
-3. \`stat\` | \`stat_many\` (size/type check).
-4. \`read\` | \`read_many\` (content).
-   > **Strict:** Never guess paths. Resolve first.
+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).
+   > **Strict:** Resolve paths first. Never guess.
 
 ### B: SEARCH
-Use when: locating files by name pattern or by content match.
+Use when: you need files by pattern or content.
 1. \`find\` (glob candidates).
-2. \`grep\` (content search).
-3. \`read\` (verify context).
-   > **Strict:** Use \`grep\` for content search, not \`find\`.
+2. \`grep\` (content matches).
+3. \`read\` (verify matched context).
+   > **Strict:** Do content search with \`grep\`, not \`find\`.
 
 ### C: EDIT
-Use when: modifying existing files or reorganizing the filesystem.
-1. \`edit\` (precise string match).
-2. \`search_and_replace\` (bulk regex/glob).
-3. \`mv\` | \`rm\` (file layout).
-4. \`mkdir\` (create dirs).
+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).
    > **Strict:** Confirm destructive ops (\`write\`, \`mv\`, \`rm\`, bulk replace).
 
 ### D: PATCH
-Use when: applying structured diffs produced by \`diff_files\`.
+Use when: applying unified diffs from \`diff_files\`.
 1. \`diff_files\` (generate).
 2. \`apply_patch\` (dryRun: true).
 3. \`apply_patch\` (dryRun: false).
-   > **Tip:** Pass \`diff_files\` output directly into \`apply_patch\`.
+   > **Tip:** Feed \`diff_files\` output directly to \`apply_patch\`.
 </workflows>`;
 }

package/dist/schemas.js

@@ -18,6 +18,9 @@ function isSafeGlobPattern(value) {
 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"';
+function defaultFalseBoolean(description) {
+    return z.boolean().optional().default(false).describe(description);
+}
 const PathSchemaBase = z
     .string()
     .max(MAX_PATH_LENGTH, `Path too long (max ${MAX_PATH_LENGTH} chars)`);
@@ -109,16 +112,8 @@ const OperationSummarySchema = z.strictObject({
 });
 export const ListDirectoryInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, .git, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, .git, etc).'),
     maxDepth: z
         .number()
         .int({ error: 'Must be integer' })
@@ -143,11 +138,7 @@ export const ListDirectoryInputSchema = z.strictObject({
         .max(1000, 'Max 1000 chars')
         .optional()
         .describe('Optional glob pattern filter (e.g. "**/*.ts")'),
-    includeSymlinkTargets: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Resolve and include symlink targets in results'),
+    includeSymlinkTargets: defaultFalseBoolean('Resolve and include symlink targets in results'),
     cursor: z
         .string()
         .optional()
@@ -174,16 +165,8 @@ export const SearchFilesInputSchema = z.strictObject({
         .optional()
         .default(DEFAULT_SEARCH_RESULTS)
         .describe(`Max results (1-${MAX_SEARCH_RESULTS}). Default: ${DEFAULT_SEARCH_RESULTS}`),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, etc).'),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
     sortBy: SearchFilesSortSchema.optional()
         .default('path')
         .describe('Sort by path, name, size, or modified'),
@@ -217,16 +200,8 @@ export const TreeInputSchema = z.strictObject({
         .optional()
         .default(DEFAULT_TREE_ENTRIES)
         .describe(`Max entries. Default: ${DEFAULT_TREE_ENTRIES}`),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items. Disables .gitignore.'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items. Disables .gitignore.'),
 });
 export const SearchContentInputSchema = z.strictObject({
     path: OptionalPathSchema.describe(DESC_PATH_ROOT),
@@ -235,21 +210,9 @@ export const SearchContentInputSchema = z.strictObject({
         .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: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Treat pattern as a RE2 regular expression. RE2 does not support lookahead, lookbehind, or backreferences.'),
-    caseSensitive: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Case-sensitive matching (default: false — searches are case-insensitive).'),
-    wholeWord: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Match whole words only'),
+    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).'),
+    wholeWord: defaultFalseBoolean('Match whole words only'),
     contextLines: z
         .number()
         .int({ error: 'Must be integer' })
@@ -273,16 +236,8 @@ export const SearchContentInputSchema = z.strictObject({
         .optional()
         .default('**/*')
         .describe('Glob for candidate files (e.g. "**/*.ts")'),
-    includeHidden: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include hidden items (starting with .)'),
-    includeIgnored: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Include ignored items (node_modules, etc).'),
+    includeHidden: defaultFalseBoolean('Include hidden items (starting with .)'),
+    includeIgnored: defaultFalseBoolean('Include ignored items (node_modules, etc).'),
 });
 export const ReadFileInputSchema = z
     .strictObject({
@@ -511,16 +466,8 @@ export const EditFileInputSchema = z.strictObject({
     }))
         .min(1, 'Min 1 edit required')
         .describe('List of replacements to apply sequentially. Each edit replaces the first occurrence of oldText.'),
-    dryRun: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Preview edits without writing. Check unmatchedEdits in the response to verify all oldText values were found.'),
-    ignoreWhitespace: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Ignore leading/trailing whitespace and treat all whitespace sequences as equivalent when matching 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.'),
 });
 export const EditFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -562,16 +509,8 @@ export const MoveFileOutputSchema = z.strictObject({
 });
 export const DeleteFileInputSchema = z.strictObject({
     path: RequiredPathSchema.describe(DESC_PATH_REQUIRED),
-    recursive: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Delete non-empty directories'),
-    ignoreIfNotExists: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('No error if missing'),
+    recursive: defaultFalseBoolean('Delete non-empty directories'),
+    ignoreIfNotExists: defaultFalseBoolean('No error if missing'),
 });
 export const DeleteFileOutputSchema = z.strictObject({
     ok: z.boolean(),
@@ -665,16 +604,8 @@ export const SearchAndReplaceInputSchema = z.strictObject({
         .min(1, 'Search pattern required')
         .describe('Text to search for. Matched literally by default; treated as RE2 regex when isRegex is true.'),
     replacement: z.string().describe('Replacement text'),
-    isRegex: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Treat searchPattern as a RE2 regular expression. Supports capture group references ($1, $2) in replacement.'),
-    dryRun: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
+    isRegex: defaultFalseBoolean('Treat searchPattern as a RE2 regular expression. Supports capture group references ($1, $2) in replacement.'),
+    dryRun: defaultFalseBoolean('Preview matches without writing. Check changedFiles and matches in the response before committing.'),
     includeHidden: z
         .boolean()
         .optional()

package/dist/server/bootstrap.js

@@ -66,8 +66,8 @@ export async function createServer(options = {}) {
     if (serverInstructions) {
         serverConfig.instructions =
             'filesystem-mcp: Secure local filesystem MCP server. ' +
-                'Always begin with: roots → ls/find → stat → read. Never guess paths. ' +
-                'Full reference: read the internal://instructions resource or invoke the get-help prompt.';
+                'Start with: roots -> ls/find -> stat -> read. Never guess paths. ' +
+                'For full guidance, read internal://instructions or run the get-help prompt.';
     }
     const server = new McpServer(withDefaultIcons({
         name: 'filesystem-mcp',