@j0hanz/filesystem-mcp 1.5.1 → 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;

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) {

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

@@ -40,6 +40,6 @@ export function getSharedConstraints() {
         '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.`,
-        'Externalized results are ephemeral (in-memory).',
+        '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.js

@@ -26,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'),

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/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);

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/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/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',
 };

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)
@@ -33,10 +33,7 @@ export const IDEMPOTENT_WRITE_TOOL_ANNOTATIONS = {
     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.1",
+  "version": "1.5.2",
   "mcpName": "io.github.j0hanz/filesystem-mcp",
   "description": "MCP Server that enables LLMs to interact with the local filesystem.",
   "type": "module",