@j0hanz/filesystem-mcp 1.5.0 → 1.5.2

package/dist/cli.js

@@ -195,7 +195,7 @@ export async function parseArgs() {
         throw error;
     }
     const options = cli.opts();
-    const allowCwd = options.allowCwd === true;
+    const allowCwd = Boolean(options.allowCwd);
     const port = parsePortOption(options.port);
     const positionals = getParsedAllowedDirs(cli);
     let allowedDirs;

package/dist/lib/constants.d.ts

@@ -1,3 +1,4 @@
+export declare function parseTrueEnvFlag(value: string | undefined): boolean;
 export declare const DEFAULT_LOG_LEVEL: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency";
 export declare const PARALLEL_CONCURRENCY: number;
 export declare const MAX_SEARCHABLE_FILE_SIZE: number;
@@ -11,8 +12,17 @@ export declare const DEFAULT_SEARCH_TIMEOUT_MS: number;
  */
 export declare const SEARCH_WORKERS: number;
 export declare const DEFAULT_MAX_DEPTH = 10;
-export declare const DEFAULT_LIST_MAX_ENTRIES = 10000;
+export declare const DEFAULT_LIST_MAX_ENTRIES = 20000;
 export declare const DEFAULT_SEARCH_MAX_FILES = 20000;
+export declare const MAX_TREE_DEPTH = 50;
+export declare const DEFAULT_TREE_DEPTH = 5;
+export declare const MAX_TREE_ENTRIES = 20000;
+export declare const DEFAULT_TREE_ENTRIES = 1000;
+export declare const MAX_LIST_ENTRIES = 20000;
+export declare const MAX_SEARCH_RESULTS = 10000;
+export declare const DEFAULT_SEARCH_RESULTS = 100;
+export declare const MAX_SEARCH_DEPTH = 100;
+export declare const DEFAULT_SEARCH_CONTENT_RESULTS = 500;
 export declare const MAX_LINE_CONTENT_LENGTH = 200;
 export declare const BINARY_CHECK_BUFFER_SIZE = 512;
 export declare const SENSITIVE_FILE_DENYLIST: string[];

package/dist/lib/constants.js

@@ -1,6 +1,11 @@
 import { availableParallelism } from 'node:os';
 const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes', 'y', 'on']);
 const FALSE_ENV_VALUES = new Set(['0', 'false', 'no', 'n', 'off']);
+export function parseTrueEnvFlag(value) {
+    if (value === undefined)
+        return false;
+    return TRUE_ENV_VALUES.has(value.trim().toLowerCase());
+}
 const KIB = 1024;
 const MIB = 1024 * KIB;
 function logInvalidEnvValue(envVar, value, expected, defaultValue) {
@@ -109,8 +114,18 @@ const ENV_ALLOWLIST = parseEnvList('FS_CONTEXT_ALLOWLIST');
 export const SEARCH_WORKERS = parseEnvInt('FS_CONTEXT_SEARCH_WORKERS', getDefaultSearchWorkers(), 1, 16);
 // Hardcoded defaults
 export const DEFAULT_MAX_DEPTH = 10;
-export const DEFAULT_LIST_MAX_ENTRIES = 10000;
+export const DEFAULT_LIST_MAX_ENTRIES = 20000;
 export const DEFAULT_SEARCH_MAX_FILES = 20000;
+// Schema limits and defaults
+export const MAX_TREE_DEPTH = 50;
+export const DEFAULT_TREE_DEPTH = 5;
+export const MAX_TREE_ENTRIES = 20000;
+export const DEFAULT_TREE_ENTRIES = 1000;
+export const MAX_LIST_ENTRIES = 20000;
+export const MAX_SEARCH_RESULTS = 10000;
+export const DEFAULT_SEARCH_RESULTS = 100;
+export const MAX_SEARCH_DEPTH = 100;
+export const DEFAULT_SEARCH_CONTENT_RESULTS = 500;
 // Non-configurable constants
 export const MAX_LINE_CONTENT_LENGTH = 200;
 export const BINARY_CHECK_BUFFER_SIZE = 512;

package/dist/lib/fs-helpers.js

@@ -419,7 +419,7 @@ async function readRangeContent(handle, startLine, endLine, options) {
             if (hasEndLine && lineNumber === stopAt) {
                 const peek = await iterator.next();
                 hasMoreLines = !peek.done;
-                reachedEof = peek.done === true;
+                reachedEof = Boolean(peek.done);
                 stoppedEarly = true;
                 break;
             }

package/dist/lib/observability.js

@@ -2,21 +2,18 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { hash } from 'node:crypto';
 import { channel, tracingChannel } from 'node:diagnostics_channel';
 import { monitorEventLoopDelay, performance, PerformanceObserver, } from 'node:perf_hooks';
+import { parseTrueEnvFlag } from './constants.js';
 import { isRecord } from './type-guards.js';
 // --- Configuration ---
 const ENV = process.env;
 let _cachedConfig;
 function readConfig() {
     return (_cachedConfig ??= {
-        enabled: isTrue(ENV['FS_CONTEXT_DIAGNOSTICS']),
+        enabled: parseTrueEnvFlag(ENV['FS_CONTEXT_DIAGNOSTICS']),
         detail: parseDetail(ENV['FS_CONTEXT_DIAGNOSTICS_DETAIL']),
-        logToolErrors: isTrue(ENV['FS_CONTEXT_TOOL_LOG_ERRORS']),
+        logToolErrors: parseTrueEnvFlag(ENV['FS_CONTEXT_TOOL_LOG_ERRORS']),
     });
 }
-function isTrue(val) {
-    const norm = val?.trim().toLowerCase();
-    return norm === '1' || norm === 'true' || norm === 'yes';
-}
 function parseDetail(val) {
     if (val === '2')
         return 2;

package/dist/prompts.js

@@ -9,7 +9,14 @@ function filterInstructionsByTopic(instructions, topic) {
         return instructions;
     const sections = instructions.split(/\n(?=## )/u);
     const match = sections.find((sec) => sec.toLowerCase().startsWith(`## ${normalized}`));
-    return match ?? instructions;
+    if (match !== undefined)
+        return match;
+    const available = sections
+        .filter((sec) => sec.startsWith('## '))
+        .map((sec) => sec.split('\n')[0]?.replace(/^##\s*/u, '') ?? '')
+        .filter(Boolean)
+        .join(', ');
+    return `Section '${topic}' not found. Available sections: ${available}\n\n${instructions}`;
 }
 export function registerGetHelpPrompt(server, instructions, iconInfo) {
     const baseConfig = withDefaultIcons({ title: HELP_PROMPT_TITLE, description: HELP_PROMPT_DESCRIPTION }, iconInfo);

package/dist/resources/generated-instructions.js

@@ -1,32 +1,28 @@
 import { buildToolCatalogDetailsOnly } from './tool-catalog.js';
 import { buildCoreContextPack, getSharedConstraints, getToolContracts, } from './tool-info.js';
 import { buildWorkflowGuide } from './workflows.js';
-const INSTRUCTIONS_HEADER = `# FILESYSTEM-MCP INSTRUCTIONS
+const INSTRUCTIONS_HEADER = `# FILESYSTEM-MCP
 
-> Resource: \`internal://instructions\` | Prompt: \`get-help\`
+Operate ONLY within allowed roots. Always discover before acting — never guess paths.
 
-## CORE CAPABILITY
+## TOOLS
 
-- **Domain:** Safe local filesystem operations (read/write/diff/patch) within allowed roots.
-- **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\`.
+| Category | Tools |
+|----------|-------|
+| Navigate | \`roots\`, \`ls\`, \`tree\`, \`find\` |
+| Inspect  | \`stat\`, \`stat_many\`, \`grep\`, \`calculate_hash\` |
+| Read     | \`read\`, \`read_many\`, \`diff_files\` |
+| Write    | \`mkdir\`, \`write\`, \`edit\`, \`mv\`, \`rm\`, \`apply_patch\`, \`search_and_replace\` |
 
 ## RESOURCES
 
-- \`filesystem-mcp://result/{id}\`: Ephemeral cached output.
-- \`filesystem-mcp://metrics\`: Live tool stats.
-- **Tip:** If response has \`resourceUri\`, call \`resources/read\` to fetch full content.
+- \`filesystem-mcp://result/{id}\`: Large output is cached here. **If a response includes \`resourceUri\`, call \`resources/read\` immediately — results expire on process restart.**
+- \`filesystem-mcp://metrics\`: Live per-tool call/error stats.
 
-## PROGRESS & TASKS
+## TASK PROTOCOL
 
-- Support \`_meta.progressToken\` for updates.
-- Task tools: \`find\`, \`tree\`, \`read\`, \`read_many\`, \`stat_many\`, \`grep\`, \`mkdir\`, \`write\`, \`mv\`, \`rm\`, \`calculate_hash\`, \`apply_patch\`, \`search_and_replace\`.
-- Flow: \`tools/call\` (task) → \`tasks/get\` → \`tasks/result\`.
-
-## GOLDEN PATH WORKFLOWS
-
-See "Workflow Reference" below for detailed execution sequences.
+Long-running tools support async execution: provide \`_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\`.
 
 `;
 const INSTRUCTIONS_FOOTER = `
@@ -45,22 +41,11 @@ ${getSharedConstraints()
 `;
 function formatToolSection(tool) {
     const parts = [`${tool.name}: ${tool.description}`];
-    if (tool.annotations) {
-        const attrs = [];
-        if (tool.annotations.destructiveHint)
-            attrs.push('[Destructive]');
-        if (tool.annotations.idempotentHint)
-            attrs.push('[Idempotent]');
-        if (tool.annotations.readOnlyHint)
-            attrs.push('[Read-Only]');
-        if (attrs.length > 0)
-            parts.push(attrs.join(' '));
-    }
     if (tool.nuances && tool.nuances.length > 0) {
-        parts.push(...tool.nuances.map((n) => `! ${n}`));
+        parts.push(...tool.nuances.map((n) => `» ${n}`));
     }
     if (tool.gotchas && tool.gotchas.length > 0) {
-        parts.push(...tool.gotchas.map((g) => `! ${g}`));
+        parts.push(...tool.gotchas.map((g) => `⚠ ${g}`));
     }
     return parts.join('\n');
 }

package/dist/resources/tool-catalog.js

@@ -1,19 +1,25 @@
 import { buildCoreContextPack } from './tool-info.js';
-const CATALOG_GUIDE = `## Tool Catalog Details
+const CATALOG_GUIDE = `## Tool Selection Guide
 
 ## Cross-Tool Data Flow
 
 \`\`\`
-find -> output_paths -> grep.paths
-diff_files -> output_patch -> apply_patch.patch
+find (results[].path) -> grep.paths
+diff_files (patch text) -> apply_patch.patch
 \`\`\`
 
-## Search Strategy Strategy
+## 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.
 
+## 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.
+
 ## Patch Management
 
 - Always generate a patch with \`diff_files\` first.
@@ -21,7 +27,6 @@ diff_files -> output_patch -> apply_patch.patch
 - \`apply_patch\` works on unified diff format.
 `;
 export function buildToolCatalog() {
-    // Return combined view for standalone resource usage
     return `${buildCoreContextPack()}\n\n${CATALOG_GUIDE}`;
 }
 export function buildToolCatalogDetailsOnly() {

package/dist/resources/tool-info.js

@@ -1,3 +1,4 @@
+import { DEFAULT_SEARCH_CONTENT_RESULTS, MAX_SEARCH_RESULTS, MAX_TEXT_FILE_SIZE, } from '../lib/constants.js';
 import { ALL_TOOLS } from '../tools.js';
 function toEntry(contract) {
     const annotations = [];
@@ -38,7 +39,7 @@ export function getSharedConstraints() {
     return [
         'Allowed roots only (negotiated via CLI).',
         'Sensitive files denylisted by default.',
-        'Max file size & search results enforced.',
-        'Externalized results are ephemeral (in-memory).',
+        `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.',
     ];
 }

package/dist/resources/workflows.js

@@ -1,8 +1,8 @@
-import { getSharedConstraints } from './tool-info.js';
 export function buildWorkflowGuide() {
     return `## Workflow Reference
 
 ### 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).
@@ -10,12 +10,14 @@ export function buildWorkflowGuide() {
    > **Strict:** Never guess paths. Resolve first.
 
 ### B: SEARCH
+Use when: locating files by name pattern or by content match.
 1. \`find\` (glob candidates).
 2. \`grep\` (content search).
 3. \`read\` (verify context).
-   > **Tip:** Content search requires \`grep\`, not \`find\`.
+   > **Strict:** Use \`grep\` for content search, 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).
@@ -23,14 +25,10 @@ export function buildWorkflowGuide() {
    > **Strict:** Confirm destructive ops (\`write\`, \`mv\`, \`rm\`, bulk replace).
 
 ### D: PATCH
+Use when: applying structured diffs produced by \`diff_files\`.
 1. \`diff_files\` (generate).
 2. \`apply_patch\` (dryRun: true).
 3. \`apply_patch\` (dryRun: false).
-   > **Tip:** Use \`diff_files\` output directly.
-
-## Shared Constraints
-${getSharedConstraints()
-        .map((c) => `- ${c}`)
-        .join('\n')}
+   > **Tip:** Pass \`diff_files\` output directly into \`apply_patch\`.
 `;
 }

package/dist/resources.js

@@ -47,7 +47,7 @@ export function registerToolCatalogResource(server, iconInfo) {
         mimeType: 'text/markdown',
         annotations: {
             audience: ['assistant'],
-            priority: 0.6,
+            priority: 0.7,
         },
     }, iconInfo), (uri) => ({
         contents: [
@@ -66,7 +66,7 @@ export function registerWorkflowGuideResource(server, iconInfo) {
         mimeType: 'text/markdown',
         annotations: {
             audience: ['assistant'],
-            priority: 0.7,
+            priority: 0.6,
         },
     }, iconInfo), (uri) => ({
         contents: [

package/dist/schemas.d.ts

@@ -38,7 +38,7 @@ export declare const ListDirectoryInputSchema: z.ZodObject<{
     includeHidden: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     includeIgnored: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
     maxDepth: z.ZodOptional<z.ZodNumber>;
-    maxEntries: z.ZodOptional<z.ZodNumber>;
+    maxEntries: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     sortBy: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         name: "name";
         size: "size";

package/dist/schemas.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { DEFAULT_LIST_MAX_ENTRIES, DEFAULT_SEARCH_CONTENT_RESULTS, DEFAULT_SEARCH_RESULTS, DEFAULT_TREE_DEPTH, DEFAULT_TREE_ENTRIES, MAX_LIST_ENTRIES, MAX_SEARCH_DEPTH, MAX_SEARCH_RESULTS, MAX_TREE_DEPTH, MAX_TREE_ENTRIES, } from './lib/constants.js';
 import { ErrorCode } from './lib/errors.js';
 function isSafeGlobPattern(value) {
     if (value.length === 0)
@@ -25,8 +26,12 @@ const RequiredPathSchema = PathSchemaBase.min(1, 'Path required');
 const FileTypeSchema = z.enum(['file', 'directory', 'symlink', 'other']);
 const ListDirectorySortSchema = z.enum(['name', 'size', 'modified', 'type']);
 const SearchFilesSortSchema = z.enum(['name', 'size', 'modified', 'path']);
-const SearchStopReasonSchema = z.enum(['maxResults', 'maxFiles', 'timeout']);
-const ListDirectoryStopReasonSchema = z.enum(['maxEntries', 'aborted']);
+const SearchStopReasonSchema = z
+    .enum(['maxResults', 'maxFiles', 'timeout'])
+    .describe('maxResults: result limit hit; maxFiles: file count limit hit; timeout: time limit exceeded');
+const ListDirectoryStopReasonSchema = z
+    .enum(['maxEntries', 'aborted'])
+    .describe('maxEntries: entry limit hit; aborted: operation was cancelled');
 const TreeEntrySchema = z.lazy(() => z.strictObject({
     name: z.string().describe('Name'),
     type: FileTypeSchema.describe('Type'),
@@ -111,16 +116,17 @@ export const ListDirectoryInputSchema = z.strictObject({
         .number()
         .int({ error: 'Must be integer' })
         .min(1, 'Min: 1')
-        .max(50, 'Max: 50')
+        .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(20000, 'Max: 20,000')
+        .max(MAX_LIST_ENTRIES, `Max: ${MAX_LIST_ENTRIES}`)
         .optional()
-        .describe('Maximum entries to return before truncation'),
+        .default(DEFAULT_LIST_MAX_ENTRIES)
+        .describe(`Maximum entries to return before truncation. Default: ${DEFAULT_LIST_MAX_ENTRIES}`),
     sortBy: ListDirectorySortSchema.optional()
         .default('name')
         .describe('Sort field (name, size, modified, type)'),
@@ -157,10 +163,10 @@ export const SearchFilesInputSchema = z.strictObject({
         .number()
         .int({ error: 'Must be integer' })
         .min(1, 'Min: 1')
-        .max(10000, 'Max: 10,000')
+        .max(MAX_SEARCH_RESULTS, `Max: ${MAX_SEARCH_RESULTS}`)
         .optional()
-        .default(100)
-        .describe('Max results (1-10000)'),
+        .default(DEFAULT_SEARCH_RESULTS)
+        .describe(`Max results (1-${MAX_SEARCH_RESULTS}). Default: ${DEFAULT_SEARCH_RESULTS}`),
     includeIgnored: z
         .boolean()
         .optional()
@@ -178,7 +184,7 @@ export const SearchFilesInputSchema = z.strictObject({
         .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
-        .max(100, 'Max: 100')
+        .max(MAX_SEARCH_DEPTH, `Max: ${MAX_SEARCH_DEPTH}`)
         .optional()
         .describe('Maximum directory depth to scan'),
     cursor: z
@@ -192,18 +198,18 @@ export const TreeInputSchema = z.strictObject({
         .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
-        .max(50, 'Max: 50')
+        .max(MAX_TREE_DEPTH, `Max: ${MAX_TREE_DEPTH}`)
         .optional()
-        .default(5)
-        .describe('Depth (0=root node only, no children). Default: 5'),
+        .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(20000, 'Max: 20,000')
+        .max(MAX_TREE_ENTRIES, `Max: ${MAX_TREE_ENTRIES}`)
         .optional()
-        .default(1000)
-        .describe('Max entries (Default: 1000)'),
+        .default(DEFAULT_TREE_ENTRIES)
+        .describe(`Max entries. Default: ${DEFAULT_TREE_ENTRIES}`),
     includeHidden: z
         .boolean()
         .optional()
@@ -249,10 +255,10 @@ export const SearchContentInputSchema = z.strictObject({
         .number()
         .int({ error: 'Must be integer' })
         .min(0, 'Min: 0')
-        .max(10000, 'Max: 10,000')
+        .max(MAX_SEARCH_RESULTS, `Max: ${MAX_SEARCH_RESULTS}`)
         .optional()
-        .default(500)
-        .describe('Maximum match rows to return'),
+        .default(DEFAULT_SEARCH_CONTENT_RESULTS)
+        .describe(`Maximum match rows to return. Default: ${DEFAULT_SEARCH_CONTENT_RESULTS}`),
     filePattern: z
         .string()
         .min(1, 'Pattern required')

package/dist/server/bootstrap.js

@@ -28,9 +28,6 @@ function getRootsManager(server) {
     }
     return manager;
 }
-function loadServerInstructions() {
-    return buildServerInstructions();
-}
 async function getLocalIconInfo() {
     const name = 'logo.svg';
     const mime = 'image/svg+xml';
@@ -52,7 +49,7 @@ async function getLocalIconInfo() {
 }
 export async function createServer(options = {}) {
     const resourceStore = createInMemoryResourceStore();
-    const serverInstructions = loadServerInstructions();
+    const serverInstructions = buildServerInstructions();
     const localIcon = await getLocalIconInfo();
     const taskToolSupport = supportsTaskToolRequests();
     const serverConfig = {
@@ -68,7 +65,7 @@ export async function createServer(options = {}) {
     if (serverInstructions) {
         serverConfig.instructions =
             'filesystem-mcp: Secure local filesystem MCP server. ' +
-                'Essential sequence: roots → ls/tree/find → read/grep. ' +
+                'Always begin with: roots → ls/find → stat → read. Never guess paths. ' +
                 'Full reference: read the internal://instructions resource or invoke the get-help prompt.';
     }
     const server = new McpServer(withDefaultIcons({
@@ -113,13 +110,37 @@ export async function startServer(server) {
     };
     rootsManager.logMissingDirectoriesIfNeeded(server);
 }
+const MAX_REQUEST_BODY_BYTES = parseInt(process.env['FS_CONTEXT_MAX_REQUEST_BYTES'] ?? '', 10) ||
+    4 * 1024 * 1024; // 4 MB default
+class RequestBodyError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'RequestBodyError';
+    }
+}
 async function readRequestBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
+        let totalBytes = 0;
+        let tooBig = false;
         req.on('data', (chunk) => {
+            totalBytes += chunk.length;
+            if (totalBytes > MAX_REQUEST_BODY_BYTES) {
+                if (!tooBig) {
+                    tooBig = true;
+                    chunks.length = 0; // free accumulated memory
+                    req.pause(); // stop emitting data events; TCP window fills naturally
+                    reject(new RequestBodyError('Request body too large', 413));
+                }
+                return;
+            }
             chunks.push(chunk);
         });
         req.on('end', () => {
+            if (tooBig)
+                return; // already rejected in 'data' handler
             const raw = Buffer.concat(chunks).toString('utf-8');
             if (!raw) {
                 resolve(undefined);
@@ -129,7 +150,7 @@ async function readRequestBody(req) {
                 resolve(JSON.parse(raw));
             }
             catch {
-                resolve(undefined);
+                reject(new RequestBodyError('Invalid JSON in request body', 400));
             }
         });
         req.on('error', reject);
@@ -171,11 +192,22 @@ function sendJsonRpcError(res, status, code, message) {
         id: null,
     }));
 }
+const LOCALHOST_ORIGIN_RE = /^https?:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/u;
+function isAllowedOrigin(origin) {
+    if (origin === undefined)
+        return true; // Non-browser clients omit Origin.
+    return LOCALHOST_ORIGIN_RE.test(origin);
+}
 export async function startHttpServer(port, options) {
     const sessions = new Map();
     async function handleMcpRequest(req, res) {
         const { method } = req;
         const sessionId = req.headers['mcp-session-id'];
+        const { origin } = req.headers;
+        if (!isAllowedOrigin(origin)) {
+            sendJsonRpcError(res, 403, -32000, 'Forbidden: disallowed origin');
+            return;
+        }
         const apiKey = process.env['FILESYSTEM_MCP_API_KEY'];
         if (apiKey) {
             const authHeader = req.headers['authorization'];
@@ -237,6 +269,12 @@ export async function startHttpServer(port, options) {
             }
         }
         catch (error) {
+            if (error instanceof RequestBodyError && !res.headersSent) {
+                const rpcCode = error.statusCode === 413 ? -32600 : -32700;
+                res.setHeader('Connection', 'close');
+                sendJsonRpcError(res, error.statusCode, rpcCode, error.message);
+                return;
+            }
             console.error('[HTTP] Error handling request:', formatUnknownErrorMessage(error));
             if (!res.headersSent) {
                 sendJsonRpcError(res, 500, -32603, 'Internal Server Error');
@@ -255,10 +293,13 @@ export async function startHttpServer(port, options) {
             res.end('Not Found');
         }
     });
+    // Default to localhost-only binding to prevent DNS-rebinding and unintended
+    // external exposure. Override with FILESYSTEM_MCP_HTTP_HOST for remote setups.
+    const httpHost = process.env['FILESYSTEM_MCP_HTTP_HOST'] ?? '127.0.0.1';
     return new Promise((resolve, reject) => {
         httpServer.once('error', reject);
-        httpServer.listen(port, () => {
-            console.error(`MCP HTTP server listening on port ${port}`);
+        httpServer.listen(port, httpHost, () => {
+            console.error(`MCP HTTP server listening on ${httpHost}:${port}`);
             resolve(httpServer);
         });
     });

package/dist/server/logging.js

@@ -20,7 +20,7 @@ function canSendMcpLogs(server) {
         return false;
     if (!('logging' in capabilities))
         return false;
-    return capabilities.logging !== null;
+    return !!capabilities['logging'];
 }
 export function logToMcp(server, level, data, minLevel = 'debug') {
     if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[minLevel]) {

package/dist/server/roots-manager.js

@@ -117,7 +117,7 @@ export class RootsManager {
     }
     async recomputeAllowedDirectories() {
         const cliAllowedDirs = normalizeCLIDirectories(this.options.cliAllowedDirs ?? []);
-        const allowCwd = this.options.allowCwd === true;
+        const allowCwd = Boolean(this.options.allowCwd);
         const allowCwdDirs = allowCwd ? [normalizePath(process.cwd())] : [];
         const baseline = [...cliAllowedDirs, ...allowCwdDirs];
         const { signal, cleanup } = createTimedAbortSignal(undefined, ROOTS_TIMEOUT_MS);

package/dist/tools/calculate-hash.js

@@ -171,7 +171,7 @@ export function registerCalculateHashTool(server, options = {}) {
                 baseReporter({
                     current,
                     ...(total !== undefined ? { total } : {}),
-                    message: `🕮 calculate_hash: ${baseName} — ${current} ${fileWord} hashed`,
+                    message: `🕮 calculate_hash: ${baseName} [${current} ${fileWord} hashed]`,
                 });
             };
             try {

package/dist/tools/create-directory.js

@@ -9,10 +9,11 @@ import { registerToolTaskIfAvailable } from './task-support.js';
 export const CREATE_DIRECTORY_TOOL = {
     name: 'mkdir',
     title: 'Create Directory',
-    description: 'Create a new directory at the specified path (recursive)',
+    description: 'Create a new directory at the specified path (recursive).',
     inputSchema: CreateDirectoryInputSchema,
     outputSchema: CreateDirectoryOutputSchema,
     annotations: IDEMPOTENT_WRITE_TOOL_ANNOTATIONS,
+    nuances: ['Succeeds silently if the directory already exists (idempotent).'],
 };
 async function handleCreateDirectory(args, signal) {
     const validPath = await validatePathForWrite(args.path, signal);
@@ -34,11 +35,11 @@ export function registerCreateDirectoryTool(server, options = {}) {
     const wrappedHandler = wrapToolHandler(handler, {
         guard: options.isInitialized,
         progressMessage: (args) => {
-            const name = path.basename(args.path) || args.path;
+            const name = path.basename(args.path) || '.';
             return `🛠 mkdir: ${name}`;
         },
         completionMessage: (args, result) => {
-            const name = path.basename(args.path) || args.path;
+            const name = path.basename(args.path) || '.';
             if (result.isError)
                 return `🛠 mkdir: ${name} • failed`;
             return `🛠 mkdir: ${name} • created`;

package/dist/tools/delete-file.js

@@ -9,11 +9,12 @@ import { registerToolTaskIfAvailable } from './task-support.js';
 export const DELETE_FILE_TOOL = {
     name: 'rm',
     title: 'Delete File',
-    description: 'Delete a file or directory.',
+    description: 'Permanently delete a file or directory. This action is irreversible.',
     inputSchema: DeleteFileInputSchema,
     outputSchema: DeleteFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
     gotchas: [
+        'Deletion is permanent — there is no undo or recycle bin.',
         'Non-empty directory delete requires `recursive=true`; else returns actionable input error.',
     ],
 };

package/dist/tools/edit-file.js

@@ -96,7 +96,8 @@ export function registerEditFileTool(server, options = {}) {
         guard: options.isInitialized,
         progressMessage: (args) => {
             const name = path.basename(args.path);
-            return `🛠 edit: ${name} [${args.edits.length} edits]`;
+            const dryTag = args.dryRun ? ' [dry run]' : '';
+            return `🛠 edit: ${name} [${args.edits.length} edits]${dryTag}`;
         },
         completionMessage: (args, result) => {
             const name = path.basename(args.path);
@@ -105,10 +106,16 @@ export function registerEditFileTool(server, options = {}) {
             const sc = result.structuredContent;
             if (!sc.ok)
                 return `🛠 edit: ${name} • failed`;
+            const applied = sc.appliedEdits ?? 0;
+            const unmatched = sc.unmatchedEdits?.length ?? 0;
+            const dryPrefix = args.dryRun ? 'dry run — ' : '';
+            if (unmatched > 0) {
+                return `🛠 edit: ${name} • ${dryPrefix}${applied} applied, ${unmatched} unmatched`;
+            }
             if (sc.lineRange) {
-                return `🛠 edit: ${name} • [${sc.lineRange[0]}-${sc.lineRange[1]}]`;
+                return `🛠 edit: ${name} • ${dryPrefix}lines ${sc.lineRange[0]}–${sc.lineRange[1]}`;
             }
-            return `🛠 edit: ${name} • [${sc.appliedEdits ?? 0} edits]`;
+            return `🛠 edit: ${name} • ${dryPrefix}${applied} applied`;
         },
     });
     const validatedHandler = withValidatedArgs(EditFileInputSchema, wrappedHandler);

package/dist/tools/list-directory.js

@@ -98,7 +98,7 @@ function decodeCursor(cursor) {
 async function handleListDirectory(args, signal) {
     const dirPath = resolvePathOrRoot(args.path);
     const cursorOffset = args.cursor !== undefined ? decodeCursor(args.cursor) : 0;
-    const pageSize = args.maxEntries ?? 20_000;
+    const pageSize = args.maxEntries;
     const options = {
         includeHidden: args.includeHidden,
         excludePatterns: args.includeIgnored ? [] : DEFAULT_EXCLUDE_PATTERNS,

package/dist/tools/move-file.js

@@ -14,6 +14,9 @@ export const MOVE_FILE_TOOL = {
     outputSchema: MoveFileOutputSchema,
     annotations: DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS,
     nuances: ['Cross-device moves fall back to copy+delete.'],
+    gotchas: [
+        'On POSIX, an existing destination is silently overwritten; on Windows, rename fails with EEXIST if destination exists.',
+    ],
 };
 async function handleMoveFile(args, signal) {
     const validSource = await validateExistingPath(args.source, signal);

package/dist/tools/replace-in-files.js

@@ -265,7 +265,7 @@ export function registerSearchAndReplaceTool(server, options = {}) {
                 baseReporter({
                     current,
                     ...(total !== undefined ? { total } : {}),
-                    message: `🛠 search_and_replace: "${args.searchPattern}" — ${current} files processed`,
+                    message: `🛠 search_and_replace: ${args.searchPattern} [${current} files processed]`,
                 });
             };
             try {

package/dist/tools/search-content.js

@@ -24,7 +24,7 @@ export const SEARCH_CONTENT_TOOL = {
         'Skips binary and oversized files.',
     ],
     gotchas: [
-        'Inline match rows are capped (first 50); full structured results are externalized via `resourceUri`.',
+        'Skips binary and oversized files silently — check file type with `stat` if no matches appear.',
     ],
     taskSupport: 'required',
 };
@@ -220,7 +220,7 @@ export function registerSearchContentTool(server, options = {}) {
                 baseReporter({
                     current,
                     ...(total !== undefined ? { total } : {}),
-                    message: `🔎︎ grep: ${pattern} — ${current} ${fileWord} scanned`,
+                    message: `🔎︎ grep: ${pattern} [${current} ${fileWord} scanned]`,
                 });
             };
             try {

package/dist/tools/shared.d.ts

@@ -8,6 +8,7 @@ export { type ToolContract } from './contract.js';
 export declare const READ_ONLY_TOOL_ANNOTATIONS: {
     readonly readOnlyHint: true;
     readonly idempotentHint: true;
+    readonly destructiveHint: false;
     readonly openWorldHint: false;
 };
 export declare const DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS: {
@@ -18,6 +19,7 @@ export declare const DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS: {
 export declare const IDEMPOTENT_WRITE_TOOL_ANNOTATIONS: {
     readonly readOnlyHint: false;
     readonly idempotentHint: true;
+    readonly destructiveHint: false;
     readonly openWorldHint: false;
 };
 export declare function shouldStripStructuredOutput(): boolean;

package/dist/tools/shared.js

@@ -1,5 +1,6 @@
 import { channel } from 'node:diagnostics_channel';
 import { z } from 'zod';
+import { parseTrueEnvFlag } from '../lib/constants.js';
 import { createDetailedError, ErrorCode, formatDetailedError, getSuggestion, McpError, } from '../lib/errors.js';
 import { createTimedAbortSignal } from '../lib/fs-helpers.js';
 import { withToolDiagnostics } from '../lib/observability.js';
@@ -8,7 +9,6 @@ export {} from './contract.js';
 const MAX_INLINE_CONTENT_CHARS = parseInt(process.env['FS_CONTEXT_MAX_INLINE_CHARS'] ?? '', 10) || 20_000;
 const MAX_INLINE_PREVIEW_CHARS = 4_000;
 const PROGRESS_RATE_LIMIT_MS = 50;
-const TRUE_ENV_VALUES = new Set(['1', 'true', 'yes']);
 const CONTEXT_DIAGNOSTICS_CHANNEL = channel('filesystem-mcp:context');
 function publishContextDiagnostics(event) {
     if (!CONTEXT_DIAGNOSTICS_CHANNEL.hasSubscribers)
@@ -18,6 +18,7 @@ function publishContextDiagnostics(event) {
 export const READ_ONLY_TOOL_ANNOTATIONS = {
     readOnlyHint: true,
     idempotentHint: true,
+    destructiveHint: false,
     openWorldHint: false,
 };
 export const DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS = {
@@ -28,13 +29,11 @@ export const DESTRUCTIVE_WRITE_TOOL_ANNOTATIONS = {
 export const IDEMPOTENT_WRITE_TOOL_ANNOTATIONS = {
     readOnlyHint: false,
     idempotentHint: true,
+    destructiveHint: false,
     openWorldHint: false,
 };
 export function shouldStripStructuredOutput() {
-    const value = process.env['FS_CONTEXT_STRIP_STRUCTURED'];
-    if (value === undefined)
-        return false;
-    return TRUE_ENV_VALUES.has(value.trim().toLowerCase());
+    return parseTrueEnvFlag(process.env['FS_CONTEXT_STRIP_STRUCTURED']);
 }
 export function maybeStripStructuredContentFromResult(result) {
     if (!shouldStripStructuredOutput())

package/dist/tools/stat-many.js

@@ -9,7 +9,7 @@ import { registerToolTaskIfAvailable } from './task-support.js';
 export const GET_MULTIPLE_FILE_INFO_TOOL = {
     name: 'stat_many',
     title: 'Get Multiple File Info',
-    description: 'Get metadata for multiple files or directories in one request.',
+    description: 'Get metadata (including tokenEstimate) for multiple files or directories in one request. Use tokenEstimate (size÷4) to pre-screen token cost before reading.',
     inputSchema: GetMultipleFileInfoInputSchema,
     outputSchema: GetMultipleFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,

package/dist/tools/stat.js

@@ -8,7 +8,7 @@ import { buildFileInfoPayload, buildToolErrorResponse, buildToolResponse, execut
 export const GET_FILE_INFO_TOOL = {
     name: 'stat',
     title: 'Get File Info',
-    description: 'Get metadata (size, modified time, permissions, mime type) for a file or directory.',
+    description: 'Get metadata (size, modified time, permissions, mime type, tokenEstimate) for a file or directory. Use tokenEstimate (size÷4) to pre-screen token cost before reading.',
     inputSchema: GetFileInfoInputSchema,
     outputSchema: GetFileInfoOutputSchema,
     annotations: READ_ONLY_TOOL_ANNOTATIONS,

package/dist/tools/write-file.js

@@ -9,15 +9,12 @@ import { registerToolTaskIfAvailable } from './task-support.js';
 export const WRITE_FILE_TOOL = {
     name: 'write',
     title: 'Write File',
-    description: 'Write content to a file. Creates the file if it does not exist.',
+    description: 'Write content to a file, OVERWRITING ALL existing content. Creates the file and parent directories if needed.',
     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.',
+        '`write` replaces ALL existing content — use `edit` for partial updates.',
     ],
 };
 async function handleWriteFile(args, signal) {

package/dist/tools.js

@@ -18,48 +18,38 @@ 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,
-    registerSearchFilesTool,
-    registerTreeTool,
-    registerReadFileTool,
-    registerReadMultipleFilesTool,
-    registerGetFileInfoTool,
-    registerGetMultipleFileInfoTool,
-    registerSearchContentTool,
-    registerCreateDirectoryTool,
-    registerWriteFileTool,
-    registerEditFileTool,
-    registerMoveFileTool,
-    registerDeleteFileTool,
-    registerCalculateHashTool,
-    registerDiffFilesTool,
-    registerApplyPatchTool,
-    registerSearchAndReplaceTool,
+const TOOL_ENTRIES = [
+    {
+        contract: LIST_ALLOWED_DIRECTORIES_TOOL,
+        register: registerListAllowedDirectoriesTool,
+    },
+    { contract: LIST_DIRECTORY_TOOL, register: registerListDirectoryTool },
+    { contract: SEARCH_FILES_TOOL, register: registerSearchFilesTool },
+    { contract: TREE_TOOL, register: registerTreeTool },
+    { contract: READ_FILE_TOOL, register: registerReadFileTool },
+    {
+        contract: READ_MULTIPLE_FILES_TOOL,
+        register: registerReadMultipleFilesTool,
+    },
+    { contract: GET_FILE_INFO_TOOL, register: registerGetFileInfoTool },
+    {
+        contract: GET_MULTIPLE_FILE_INFO_TOOL,
+        register: registerGetMultipleFileInfoTool,
+    },
+    { contract: SEARCH_CONTENT_TOOL, register: registerSearchContentTool },
+    { contract: CREATE_DIRECTORY_TOOL, register: registerCreateDirectoryTool },
+    { contract: WRITE_FILE_TOOL, register: registerWriteFileTool },
+    { contract: EDIT_FILE_TOOL, register: registerEditFileTool },
+    { contract: MOVE_FILE_TOOL, register: registerMoveFileTool },
+    { contract: DELETE_FILE_TOOL, register: registerDeleteFileTool },
+    { contract: CALCULATE_HASH_TOOL, register: registerCalculateHashTool },
+    { contract: DIFF_FILES_TOOL, register: registerDiffFilesTool },
+    { contract: APPLY_PATCH_TOOL, register: registerApplyPatchTool },
+    { contract: SEARCH_AND_REPLACE_TOOL, register: registerSearchAndReplaceTool },
 ];
+export const ALL_TOOLS = TOOL_ENTRIES.map((e) => e.contract);
 export function registerAllTools(server, options = {}) {
-    for (const registerTool of TOOL_REGISTRARS) {
-        registerTool(server, options);
+    for (const { register } of TOOL_ENTRIES) {
+        register(server, options);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/filesystem-mcp",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",
@@ -73,7 +73,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "eslint": "^10.0.0",
+    "eslint": "^10.0.1",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/node": "^24",
     "eslint-config-prettier": "^10.1.8",
@@ -81,7 +81,7 @@
     "eslint-plugin-depend": "^1.4.0",
     "eslint-plugin-unused-imports": "^4.4.1",
     "jscpd": "^4.0.8",
-    "knip": "^5.84.1",
+    "knip": "^5.85.0",
     "prettier": "^3.8.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",