@j0hanz/filesystem-mcp 1.14.0 → 1.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 j0hanz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,6 +8,24 @@
 
 A local filesystem MCP server that lets LLMs and AI agents read, write, search, diff, patch, and manage files safely and efficiently. Built for reliable, structured, and controlled filesystem interaction.
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Quick Start](#quick-start) — [Docker](#docker) · [CLI Usage](#cli-usage)
+- [Client Configuration](#client-configuration)
+- [Use Cases](#use-cases)
+- [Architecture](#architecture)
+- [MCP Surface](#mcp-surface) — [Tools](#tools) · [Resources](#resources) · [Prompts](#prompts)
+- [MCP Capabilities](#mcp-capabilities) — [Tool Annotations](#tool-annotations) · [Structured Output](#structured-output)
+- [Configuration](#configuration) — [HTTP & Auth](#http--auth) · [File Size Limits](#file-size-limits) · [Access Control](#access-control) · [Output & Inline Limits](#output--inline-limits) · [Tasks](#tasks) · [Logging & Diagnostics](#logging--diagnostics) · [Performance](#performance)
+- [HTTP Endpoints](#http-endpoints)
+- [Security](#security)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [Credits](#credits)
+- [Contributing and License](#contributing-and-license)
+
 ## Overview
 
 A secure, production-ready [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants controlled access to the local filesystem. All operations are sandboxed to explicitly allowed directories with path traversal prevention, sensitive file blocking, and optional Bearer token authentication.
@@ -469,37 +487,39 @@ Add to VS Code `settings.json` under `augment.advanced`:
 
 </details>
 
+[↑ Back to top](#table-of-contents)
+
 ## Use Cases
 
 ### Explore and Understand a Codebase
 
 Discover project structure and navigate unfamiliar repositories. Start with `roots` to see allowed directories, use `tree` for an overview, `find` to locate files by pattern, and `read` or `read_many` to inspect contents.
 
-**Relevant tools:** `roots`, `ls`, `find`, `tree`, `read`, `read_many`, `stat`
+**Relevant tools:** [`roots`](#roots), [`ls`](#ls), [`find`](#find), [`tree`](#tree), [`read`](#read), [`read_many`](#read_many), [`stat`](#stat)
 
 ### Search Across Files
 
 Locate specific code patterns, function definitions, or configuration values across a project. Use `grep` for content search with regex support and `find` for file name matching.
 
-**Relevant tools:** `grep`, `find`
+**Relevant tools:** [`grep`](#grep), [`find`](#find)
 
 ### Edit and Refactor Code
 
 Make precise, targeted edits to source files. Use `edit` for surgical replacements with dry-run preview, or `search_and_replace` for bulk changes across multiple files matching a glob pattern.
 
-**Relevant tools:** `edit`, `search_and_replace`, `write`
+**Relevant tools:** [`edit`](#edit), [`search_and_replace`](#search_and_replace), [`write`](#write)
 
 ### Diff and Patch Workflow
 
 Compare file versions and apply patches. Generate a unified diff with `diff_files`, preview with `apply_patch(dryRun: true)`, then apply. Supports both single-file and multi-file patches (best-effort per file with per-file `results[]`).
 
-**Relevant tools:** `diff_files`, `apply_patch`
+**Relevant tools:** [`diff_files`](#diff_files), [`apply_patch`](#apply_patch)
 
 ### File Management
 
 Create directories, move/rename files, delete files, and verify file integrity via SHA-256 hashing.
 
-**Relevant tools:** `mkdir`, `mv`, `rm`, `calculate_hash`, `write`
+**Relevant tools:** [`mkdir`](#mkdir), [`mv`](#mv), [`rm`](#rm), [`calculate_hash`](#calculate_hash), [`write`](#write)
 
 ## Architecture
 
@@ -565,6 +585,8 @@ Create directories, move/rename files, delete files, and verify file integrity v
 
 ### Tools
 
+[`roots`](#roots) · [`ls`](#ls) · [`find`](#find) · [`tree`](#tree) · [`read`](#read) · [`read_many`](#read_many) · [`stat`](#stat) · [`stat_many`](#stat_many) · [`grep`](#grep) · [`mkdir`](#mkdir) · [`write`](#write) · [`edit`](#edit) · [`mv`](#mv) · [`rm`](#rm) · [`calculate_hash`](#calculate_hash) · [`diff_files`](#diff_files) · [`apply_patch`](#apply_patch) · [`search_and_replace`](#search_and_replace)
+
 #### `roots`
 
 List allowed workspace roots. Call first — all other tools are scoped to these directories.
@@ -577,17 +599,17 @@ _No parameters._
 
 List immediate directory contents: name, path, type, size, modified date.
 
-| Parameter               | Type    | Required | Description                                                  |
-| ----------------------- | ------- | -------- | ------------------------------------------------------------ |
-| `path`                  | string  | no       | Base directory (default: root)                               |
-| `includeHidden`         | boolean | no       | Include dotfiles. Default: `false`                           |
-| `includeIgnored`        | boolean | no       | Include ignored items (node_modules, .git). Default: `false` |
-| `maxDepth`              | integer | no       | Max recursion depth (1-100) when pattern is provided         |
-| `maxEntries`            | integer | no       | Max entries before truncation. Default: 1000, Max: 10000     |
-| `sortBy`                | enum    | no       | `name` \| `size` \| `modified` \| `type`. Default: `name`    |
-| `pattern`               | string  | no       | Glob filter (e.g. `**/*.ts`)                                 |
-| `includeSymlinkTargets` | boolean | no       | Resolve symlink targets. Default: `false`                    |
-| `cursor`                | string  | no       | Pagination cursor from a previous response                   |
+| Parameter               | Type    | Required | Description                                                                 |
+| ----------------------- | ------- | -------- | --------------------------------------------------------------------------- |
+| `path`                  | string  | no       | Base directory (default: root)                                              |
+| `includeHidden`         | boolean | no       | Include dotfiles. Default: `false`                                          |
+| `includeIgnored`        | boolean | no       | Include ignored items (node_modules, .git). Default: `false`                |
+| `maxDepth`              | integer | no       | Max recursion depth (1-50) when pattern is provided                         |
+| `maxEntries`            | integer | no       | Max entries before truncation. Default: 20000, Max: 20000                   |
+| `sortBy`                | enum    | no       | `name` \| `size` \| `modified` \| `type`. Default: `name`                   |
+| `pattern`               | string  | no       | Relative glob filter (e.g. `**/*.ts`). Absolute paths and `..` are rejected |
+| `includeSymlinkTargets` | boolean | no       | Resolve symlink targets. Default: `false`                                   |
+| `cursor`                | string  | no       | Pagination cursor from a previous response                                  |
 
 ---
 
@@ -595,16 +617,16 @@ List immediate directory contents: name, path, type, size, modified date.
 
 Find files by glob pattern. Returns matching files with metadata.
 
-| Parameter        | Type    | Required | Description                                               |
-| ---------------- | ------- | -------- | --------------------------------------------------------- |
-| `path`           | string  | no       | Base directory (default: root)                            |
-| `pattern`        | string  | **yes**  | Glob pattern (e.g. `**/*.ts`)                             |
-| `maxResults`     | integer | no       | Max results (1-100000). Default: 1000                     |
-| `includeIgnored` | boolean | no       | Include ignored items. Default: `false`                   |
-| `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`                        |
-| `sortBy`         | enum    | no       | `path` \| `name` \| `size` \| `modified`. Default: `path` |
-| `maxDepth`       | integer | no       | Max directory depth (0-1000)                              |
-| `cursor`         | string  | no       | Pagination cursor                                         |
+| Parameter        | Type    | Required | Description                                                                  |
+| ---------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+| `path`           | string  | no       | Base directory (default: root)                                               |
+| `pattern`        | string  | **yes**  | Relative glob pattern (e.g. `**/*.ts`). Absolute paths and `..` are rejected |
+| `maxResults`     | integer | no       | Max results (1-10000). Default: 100                                          |
+| `includeIgnored` | boolean | no       | Include ignored items. Default: `false`                                      |
+| `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`                                           |
+| `sortBy`         | enum    | no       | `path` \| `name` \| `size` \| `modified`. Default: `path`                    |
+| `maxDepth`       | integer | no       | Max directory depth (0-100)                                                  |
+| `cursor`         | string  | no       | Pagination cursor                                                            |
 
 ---
 
@@ -615,8 +637,8 @@ Render a directory tree with bounded recursion. Returns ASCII tree + structured
 | Parameter        | Type    | Required | Description                                          |
 | ---------------- | ------- | -------- | ---------------------------------------------------- |
 | `path`           | string  | no       | Base directory (default: root)                       |
-| `maxDepth`       | integer | no       | Depth (0 = root node only). Default: 10, Max: 100    |
-| `maxEntries`     | integer | no       | Max entries. Default: 5000, Max: 100000              |
+| `maxDepth`       | integer | no       | Depth (0 = root node only). Default: 5, Max: 50      |
+| `maxEntries`     | integer | no       | Max entries. Default: 1000, Max: 20000               |
 | `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`                   |
 | `includeIgnored` | boolean | no       | Include ignored items. Default: `false`              |
 | `includeSizes`   | boolean | no       | Include file sizes in tree entries. Default: `false` |
@@ -676,18 +698,18 @@ Get metadata for multiple files/directories in one request.
 
 Search file contents (grep-like). Returns matching lines with optional context.
 
-| Parameter        | Type    | Required | Description                                      |
-| ---------------- | ------- | -------- | ------------------------------------------------ |
-| `path`           | string  | no       | Base directory (default: root)                   |
-| `pattern`        | string  | **yes**  | Search text or RE2 regex when `isRegex=true`     |
-| `isRegex`        | boolean | no       | Treat pattern as RE2 regex. Default: `false`     |
-| `caseSensitive`  | boolean | no       | Case-sensitive matching. Default: `false`        |
-| `wholeWord`      | boolean | no       | Match whole words only. Default: `false`         |
-| `contextLines`   | integer | no       | Lines of context before/after (0-50). Default: 0 |
-| `maxResults`     | integer | no       | Max match rows (1-100000). Default: 100          |
-| `filePattern`    | string  | no       | Glob for candidate files (e.g. `**/*.ts`)        |
-| `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`               |
-| `includeIgnored` | boolean | no       | Include ignored items. Default: `false`          |
+| Parameter        | Type    | Required | Description                                                         |
+| ---------------- | ------- | -------- | ------------------------------------------------------------------- |
+| `path`           | string  | no       | Base directory (default: root)                                      |
+| `pattern`        | string  | **yes**  | Search text or RE2 regex when `isRegex=true`                        |
+| `isRegex`        | boolean | no       | Treat pattern as RE2 regex. Default: `false`                        |
+| `caseSensitive`  | boolean | no       | Case-sensitive matching. Default: `false`                           |
+| `wholeWord`      | boolean | no       | Match whole words only. Default: `false`                            |
+| `contextLines`   | integer | no       | Lines of context before/after (0-50). Default: 0                    |
+| `maxResults`     | integer | no       | Max match rows (0-10000). Default: 500                              |
+| `filePattern`    | string  | no       | Relative glob for candidate files (e.g. `**/*.ts`). Default: `**/*` |
+| `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`                                  |
+| `includeIgnored` | boolean | no       | Include ignored items. Default: `false`                             |
 
 ---
 
@@ -720,7 +742,7 @@ Apply sequential literal string replacements (first occurrence per edit). Use `d
 | Parameter          | Type    | Required | Description                                                |
 | ------------------ | ------- | -------- | ---------------------------------------------------------- |
 | `path`             | string  | **yes**  | Absolute path to file                                      |
-| `edits`            | array   | **yes**  | List of `{oldText, newText}` replacements                  |
+| `edits`            | array   | **yes**  | List of non-empty `{oldText, newText}` replacements        |
 | `dryRun`           | boolean | no       | Preview edits without writing. Default: `false`            |
 | `ignoreWhitespace` | boolean | no       | Treat whitespace sequences as equivalent. Default: `false` |
 
@@ -792,19 +814,19 @@ Apply a unified diff patch to one or more files. Single-file: throws on failure.
 
 Bulk search-and-replace across files matching a glob. Replaces **all** occurrences per file. Always `dryRun: true` first.
 
-| Parameter        | Type    | Required | Description                                         |
-| ---------------- | ------- | -------- | --------------------------------------------------- |
-| `path`           | string  | no       | Base directory (default: root)                      |
-| `filePattern`    | string  | **yes**  | Glob pattern (e.g. `**/*.ts`)                       |
-| `searchPattern`  | string  | **yes**  | Text to search. RE2 regex when `isRegex=true`       |
-| `replacement`    | string  | **yes**  | Replacement text. Supports `$1`, `$2` with regex    |
-| `isRegex`        | boolean | no       | Treat as RE2 regex. Default: `false`                |
-| `dryRun`         | boolean | no       | Preview matches with diff. Default: `false`         |
-| `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`                  |
-| `includeIgnored` | boolean | no       | Include ignored items. Default: `false`             |
-| `returnDiff`     | boolean | no       | Return diff even when not dry-run. Default: `false` |
-| `maxFiles`       | integer | no       | Max files to process before stopping (1-10000)      |
-| `caseSensitive`  | boolean | no       | Case-sensitive matching. Default: `true`            |
+| Parameter        | Type    | Required | Description                                             |
+| ---------------- | ------- | -------- | ------------------------------------------------------- |
+| `path`           | string  | no       | Base directory (default: root)                          |
+| `filePattern`    | string  | no       | Relative glob pattern (e.g. `**/*.ts`). Default: `**/*` |
+| `searchPattern`  | string  | **yes**  | Text to search. RE2 regex when `isRegex=true`           |
+| `replacement`    | string  | **yes**  | Replacement text. Supports `$1`, `$2` with regex        |
+| `isRegex`        | boolean | no       | Treat as RE2 regex. Default: `false`                    |
+| `dryRun`         | boolean | no       | Preview matches with diff. Default: `false`             |
+| `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`                      |
+| `includeIgnored` | boolean | no       | Include ignored items. Default: `false`                 |
+| `returnDiff`     | boolean | no       | Return diff even when not dry-run. Default: `false`     |
+| `maxFiles`       | integer | no       | Max files to process before stopping (1-10000)          |
+| `caseSensitive`  | boolean | no       | Case-sensitive matching. Default: `true`                |
 
 ### Resources
 
@@ -849,21 +871,69 @@ Bulk search-and-replace across files matching a glob. Replaces **all** occurrenc
 
 All 18 tools define `outputSchema` (Zod -> JSON Schema) and return `structuredContent` alongside text `content`. Set `FS_CONTEXT_STRIP_STRUCTURED=true` to strip output schemas from tool definitions (reduces token usage for LLMs that don't use structured output).
 
+[↑ Back to top](#table-of-contents)
+
 ## Configuration
 
-| Variable                           | Default          | Description                                                                    |
-| ---------------------------------- | ---------------- | ------------------------------------------------------------------------------ |
-| `FILESYSTEM_MCP_API_KEY`           | _(none)_         | Bearer token required when binding HTTP to a non-loopback host                 |
-| `FILESYSTEM_MCP_MAX_HTTP_SESSIONS` | `100`            | Max concurrent HTTP sessions (1-10,000)                                        |
-| `FILESYSTEM_MCP_HTTP_HOST`         | `127.0.0.1`      | HTTP server bind address                                                       |
-| `FS_CONTEXT_MAX_REQUEST_BYTES`     | `4194304` (4 MB) | Max HTTP request body size (1 KB - 256 MB)                                     |
-| `FS_CONTEXT_MAX_INLINE_CHARS`      | _(auto)_         | Max inline result chars before externalizing to `filesystem-mcp://result/{id}` |
-| `FS_CONTEXT_MAX_INLINE_MATCHES`    | `50`             | Max inline search matches before truncation                                    |
-| `FS_CONTEXT_STRIP_STRUCTURED`      | `false`          | Strip `outputSchema` from tool definitions                                     |
-| `FS_CONTEXT_DIAGNOSTICS`           | `false`          | Enable diagnostic logging                                                      |
-| `FS_CONTEXT_DIAGNOSTICS_DETAIL`    | `false`          | Enable detailed diagnostic output                                              |
-| `FS_CONTEXT_TOOL_LOG_ERRORS`       | `false`          | Log tool errors to stderr                                                      |
-| `FS_CONTEXT_SEARCH_WORKERS_DEBUG`  | `false`          | Debug logging for search worker pool                                           |
+### HTTP & Auth
+
+| Variable                           | Default          | Description                                                    |
+| ---------------------------------- | ---------------- | -------------------------------------------------------------- |
+| `FILESYSTEM_MCP_API_KEY`           | _(none)_         | Bearer token required when binding HTTP to a non-loopback host |
+| `FILESYSTEM_MCP_MAX_HTTP_SESSIONS` | `100`            | Max concurrent HTTP sessions (1-10,000)                        |
+| `FILESYSTEM_MCP_HTTP_HOST`         | `127.0.0.1`      | HTTP server bind address                                       |
+| `FS_CONTEXT_MAX_REQUEST_BYTES`     | `4194304` (4 MB) | Max HTTP request body size (1 KB - 256 MB)                     |
+
+### File Size Limits
+
+| Variable                   | Default            | Description                                                   |
+| -------------------------- | ------------------ | ------------------------------------------------------------- |
+| `MAX_FILE_SIZE`            | `10485760` (10 MB) | Max file size for text read operations (1 MB - 100 MB)        |
+| `MAX_SEARCH_SIZE`          | `1048576` (1 MB)   | Max file size for content search/grep (100 KB - 10 MB)        |
+| `MAX_READ_MANY_TOTAL_SIZE` | `524288` (512 KB)  | Max cumulative size for `read_many` requests (10 KB - 100 MB) |
+| `DEFAULT_SEARCH_TIMEOUT`   | `5000`             | Search operation timeout in ms (100 - 60,000)                 |
+
+### Access Control
+
+| Variable                     | Default  | Description                                                                     |
+| ---------------------------- | -------- | ------------------------------------------------------------------------------- |
+| `FS_CONTEXT_ALLOW_SENSITIVE` | `false`  | Allow reading sensitive files (.env, .key, credentials, tokens)                 |
+| `FS_CONTEXT_DENYLIST`        | _(none)_ | CSV/newline-separated glob patterns to block (in addition to built-in denylist) |
+| `FS_CONTEXT_ALLOWLIST`       | _(none)_ | CSV/newline-separated glob patterns to permit (overrides denylist)              |
+
+### Output & Inline Limits
+
+| Variable                        | Default | Description                                                                    |
+| ------------------------------- | ------- | ------------------------------------------------------------------------------ |
+| `FS_CONTEXT_MAX_INLINE_CHARS`   | `20000` | Max inline result chars before externalizing to `filesystem-mcp://result/{id}` |
+| `FS_CONTEXT_MAX_INLINE_MATCHES` | `50`    | Max inline search matches before truncation                                    |
+| `FS_CONTEXT_STRIP_STRUCTURED`   | `false` | Strip `outputSchema` from tool definitions (reduces tokens)                    |
+
+### Tasks
+
+| Variable                              | Default          | Description                                     |
+| ------------------------------------- | ---------------- | ----------------------------------------------- |
+| `FILESYSTEM_MCP_MAX_TASK_TTL_MS`      | `3600000` (1 hr) | Max task TTL before auto-eviction (1 s - 24 hr) |
+| `FILESYSTEM_MCP_MAX_CONCURRENT_TASKS` | `100`            | Max simultaneous task executions (1-10,000)     |
+
+### Logging & Diagnostics
+
+| Variable                          | Default | Description                                                                    |
+| --------------------------------- | ------- | ------------------------------------------------------------------------------ |
+| `FILESYSTEM_MCP_LOG_LEVEL`        | `info`  | MCP log level: debug, info, notice, warning, error, critical, alert, emergency |
+| `FS_CONTEXT_DIAGNOSTICS`          | `false` | Enable diagnostic logging                                                      |
+| `FS_CONTEXT_DIAGNOSTICS_DETAIL`   | `false` | Enable detailed diagnostic output                                              |
+| `FS_CONTEXT_TOOL_LOG_ERRORS`      | `false` | Log tool errors to stderr                                                      |
+| `FS_CONTEXT_SEARCH_WORKERS_DEBUG` | `false` | Debug logging for search worker pool                                           |
+
+### Performance
+
+| Variable                        | Default          | Description                              |
+| ------------------------------- | ---------------- | ---------------------------------------- |
+| `FS_CONTEXT_SEARCH_WORKERS`     | CPU cores (≤ 8)  | Concurrent search worker threads (1-16)  |
+| `FS_CONTEXT_LIST_CURSOR_TTL_MS` | `300000` (5 min) | Cursor TTL for `ls` pagination snapshots |
+
+[↑ Back to top](#table-of-contents)
 
 ## HTTP Endpoints
 
@@ -898,6 +968,8 @@ When started with `--port <number>`, the server exposes a single MCP endpoint:
 | Request body limit        | confirmed | `src/server/bootstrap.ts` — configurable max request size (413 on overflow)            |
 | Remote bind guard         | confirmed | `src/server/bootstrap.ts` — refuses non-loopback bind without `FILESYSTEM_MCP_API_KEY` |
 
+[↑ Back to top](#table-of-contents)
+
 ## Development
 
 - `dev` — `tsc --watch --preserveWatchOutput` — Watch mode TypeScript compilation
@@ -935,10 +1007,10 @@ When started with `--port <number>`, the server exposes a single MCP endpoint:
 | [diff](https://www.npmjs.com/package/diff)                                           | Unified diff generation and patch application |
 | [ignore](https://www.npmjs.com/package/ignore)                                       | `.gitignore` pattern matching                 |
 | [re2](https://www.npmjs.com/package/re2)                                             | Safe RE2 regex engine (no ReDoS)              |
-| [safe-regex2](https://www.npmjs.com/package/safe-regex2)                             | Regex safety validation                       |
 | [zod](https://www.npmjs.com/package/zod)                                             | Schema validation and JSON Schema generation  |
 
-## Contributing and License
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
 
-- **License:** MIT
-- Contributions welcome via pull requests.
+[↑ Back to top](#table-of-contents)

package/dist/cli.js

@@ -1,4 +1,4 @@
-import * as fs from 'node:fs/promises';
+import { stat } from 'node:fs/promises';
 import { getSystemErrorMessage, getSystemErrorName } from 'node:util';
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { processInParallel } from './lib/fs-helpers.js';
@@ -83,7 +83,7 @@ function assertDirectory(stats, inputPath) {
 async function validateDirectoryPath(inputPath) {
     const normalized = normalizePath(inputPath);
     try {
-        const stats = await fs.stat(normalized);
+        const stats = await stat(normalized);
         assertDirectory(stats, inputPath);
         return normalized;
     }

package/dist/completions.js

@@ -1,6 +1,6 @@
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
 import { CompleteRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { readdir, stat } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, parse, resolve, sep, } from 'node:path';
 import { getAllowedDirectories, isPathWithinDirectories, normalizePath, toPosixPath, } from './lib/paths.js';
 import { isRecord } from './lib/utils.js';
 import { getSortedToolContracts } from './resources/tool-info.js';
@@ -191,21 +191,21 @@ function rememberCompletionCacheValue(cache, key, value) {
     }
 }
 function hasTrailingSeparator(value) {
-    return (value.endsWith(path.sep) || value.endsWith('/') || value.endsWith('\\'));
+    return value.endsWith(sep) || value.endsWith('/') || value.endsWith('\\');
 }
 function isAbsolutePathInput(value) {
-    return (path.isAbsolute(value) ||
+    return (isAbsolute(value) ||
         /^[A-Za-z]:[\\/]/u.test(value) ||
         value.startsWith('\\\\'));
 }
 function resolveFromBase(base, rawValue, trailingSeparator) {
-    const normalizedValue = normalizePath(path.resolve(base, rawValue));
+    const normalizedValue = normalizePath(resolve(base, rawValue));
     if (trailingSeparator) {
         return { searchDir: normalizedValue, prefix: '' };
     }
     return {
-        searchDir: path.dirname(normalizedValue),
-        prefix: path.basename(normalizedValue),
+        searchDir: dirname(normalizedValue),
+        prefix: basename(normalizedValue),
     };
 }
 function resolveNamedRootContext(currentValue, allowed) {
@@ -225,18 +225,18 @@ function resolveNamedRootPath(value, allowed) {
     const root = findAllowedRootByName(parsed.rootName, allowed);
     if (!root)
         return undefined;
-    return normalizePath(path.resolve(root, parsed.remainder));
+    return normalizePath(resolve(root, parsed.remainder));
 }
 function parseNamedRootInput(value) {
     const normalizedInput = toPosixPath(value);
     const [rootName, ...rest] = normalizedInput.split('/');
     if (!rootName)
         return undefined;
-    return { rootName, remainder: rest.join(path.sep) };
+    return { rootName, remainder: rest.join(sep) };
 }
 function findAllowedRootByName(rootName, allowed) {
     const normalizedRootName = rootName.toLowerCase();
-    return allowed.find((candidate) => path.basename(candidate).toLowerCase() === normalizedRootName);
+    return allowed.find((candidate) => basename(candidate).toLowerCase() === normalizedRootName);
 }
 function chooseContextKeys(argumentName) {
     const normalized = argumentName.toLowerCase();
@@ -263,7 +263,7 @@ function resolveContextCandidatePath(candidate, allowed) {
         const base = allowed[0];
         if (!base)
             return undefined;
-        return normalizePath(path.resolve(base, candidate));
+        return normalizePath(resolve(base, candidate));
     }
     return resolveNamedRootPath(candidate, allowed);
 }
@@ -271,14 +271,14 @@ async function toAllowedContextDirectory(resolved, allowed) {
     if (!isPathWithinDirectories(resolved, allowed))
         return undefined;
     try {
-        const stats = await fs.stat(resolved);
+        const stats = await stat(resolved);
         if (stats.isDirectory())
             return resolved;
     }
     catch {
         // Fall back to parent path best-effort resolution.
     }
-    const parent = path.dirname(resolved);
+    const parent = dirname(resolved);
     return isPathWithinDirectories(parent, allowed) ? parent : undefined;
 }
 async function resolveContextBaseDirectory(argumentName, contextArguments, allowed) {
@@ -300,7 +300,7 @@ async function resolveContextBaseDirectory(argumentName, contextArguments, allow
     return undefined;
 }
 function withDirectorySeparator(value) {
-    return value.endsWith(path.sep) ? value : `${value}${path.sep}`;
+    return value.endsWith(sep) ? value : `${value}${sep}`;
 }
 function buildCompletionResult(values) {
     return {
@@ -314,8 +314,8 @@ function buildCompletionResponse(result) {
 }
 function sortCompletionMatches(matches) {
     matches.sort((left, right) => {
-        const leftIsDir = left.endsWith(path.sep);
-        const rightIsDir = right.endsWith(path.sep);
+        const leftIsDir = left.endsWith(sep);
+        const rightIsDir = right.endsWith(sep);
         if (leftIsDir && !rightIsDir)
             return -1;
         if (!leftIsDir && rightIsDir)
@@ -350,7 +350,7 @@ function collectAllowedRoots(allowed, predicate) {
 function getSearchContext(currentValue, allowed, contextBase) {
     const trailingSeparator = hasTrailingSeparator(currentValue);
     if (isAbsolutePathInput(currentValue)) {
-        return resolveFromBase(path.parse(currentValue).root || path.sep, currentValue, trailingSeparator);
+        return resolveFromBase(parse(currentValue).root || sep, currentValue, trailingSeparator);
     }
     const namedRootContext = resolveNamedRootContext(currentValue, allowed);
     if (namedRootContext) {
@@ -376,13 +376,13 @@ async function findMatchesInDirectory(searchDir, prefix, allowed) {
         return matches;
     }
     try {
-        const entries = await fs.readdir(searchDir, { withFileTypes: true });
+        const entries = await readdir(searchDir, { withFileTypes: true });
         const lowerPrefix = prefix.toLowerCase();
         for (const entry of entries) {
             if (entry.name.toLowerCase().startsWith(lowerPrefix)) {
-                const fullPath = path.join(searchDir, entry.name);
+                const fullPath = join(searchDir, entry.name);
                 const isDir = entry.isDirectory();
-                matches.push(isDir ? `${fullPath}${path.sep}` : fullPath);
+                matches.push(isDir ? `${fullPath}${sep}` : fullPath);
             }
         }
     }
@@ -396,17 +396,17 @@ function findRootPrefixMatches(currentValue, allowed) {
     if (!rootPrefix) {
         return collectAllowedRoots(allowed, () => true);
     }
-    return collectAllowedRoots(allowed, (root) => path.basename(root).toLowerCase().startsWith(rootPrefix));
+    return collectAllowedRoots(allowed, (root) => basename(root).toLowerCase().startsWith(rootPrefix));
 }
 function findMatchingRoots(searchDir, prefix, allowed) {
     const lowerPrefix = prefix.toLowerCase();
     const normalizedSearchDir = normalizePath(searchDir);
     return collectAllowedRoots(allowed, (root) => {
-        const rootDir = path.dirname(root);
+        const rootDir = dirname(root);
         // Check if root is a direct child of searchDir
         if (normalizePath(rootDir) !== normalizedSearchDir)
             return false;
-        return path.basename(root).toLowerCase().startsWith(lowerPrefix);
+        return basename(root).toLowerCase().startsWith(lowerPrefix);
     });
 }
 async function getPathCompletions(currentValue, options = {}) {
@@ -430,6 +430,34 @@ async function getPathCompletions(currentValue, options = {}) {
         return { values: [] };
     }
 }
+function handleTopicAndToolCompletions(ref, argName, argumentValue, topicValues, toolNameValues) {
+    if (!isRecord(ref))
+        return undefined;
+    const currentValue = argumentValue.toLowerCase();
+    if (ref['type'] === 'ref/prompt' && argName === 'topic') {
+        const filtered = currentValue
+            ? topicValues.filter((v) => v.startsWith(currentValue))
+            : topicValues;
+        return buildCompletionResponse(buildCompletionResult(filtered));
+    }
+    if (ref['type'] === 'ref/prompt' &&
+        ref['name'] === 'get-tool-help' &&
+        argName === 'name') {
+        const filtered = currentValue
+            ? toolNameValues.filter((value) => value.startsWith(currentValue))
+            : toolNameValues;
+        return buildCompletionResponse(buildCompletionResult(filtered));
+    }
+    if (ref['type'] === 'ref/resource' &&
+        ref['uri'] === 'internal://tool-info/{name}' &&
+        argName === 'name') {
+        const filtered = currentValue
+            ? toolNameValues.filter((value) => value.startsWith(currentValue))
+            : toolNameValues;
+        return buildCompletionResponse(buildCompletionResult(filtered));
+    }
+    return undefined;
+}
 export function registerCompletions(server, instructions = '') {
     const topicValues = extractTopicCompletions(instructions);
     const toolNameValues = extractToolNameCompletions();
@@ -437,34 +465,9 @@ export function registerCompletions(server, instructions = '') {
         const { params } = request;
         const { argument, ref } = params;
         const argName = argument.name.toLowerCase();
-        // Handle prompt topic completions
-        if (isRecord(ref) && ref['type'] === 'ref/prompt' && argName === 'topic') {
-            const currentValue = argument.value.toLowerCase();
-            const filtered = currentValue
-                ? topicValues.filter((v) => v.startsWith(currentValue))
-                : topicValues;
-            return buildCompletionResponse(buildCompletionResult(filtered));
-        }
-        if (isRecord(ref) &&
-            ref['type'] === 'ref/prompt' &&
-            ref['name'] === 'get-tool-help' &&
-            argName === 'name') {
-            const currentValue = argument.value.toLowerCase();
-            const filtered = currentValue
-                ? toolNameValues.filter((value) => value.startsWith(currentValue))
-                : toolNameValues;
-            return buildCompletionResponse(buildCompletionResult(filtered));
-        }
-        if (isRecord(ref) &&
-            ref['type'] === 'ref/resource' &&
-            ref['uri'] === 'internal://tool-info/{name}' &&
-            argName === 'name') {
-            const currentValue = argument.value.toLowerCase();
-            const filtered = currentValue
-                ? toolNameValues.filter((value) => value.startsWith(currentValue))
-                : toolNameValues;
-            return buildCompletionResponse(buildCompletionResult(filtered));
-        }
+        const predef = handleTopicAndToolCompletions(ref, argName, argument.value, topicValues, toolNameValues);
+        if (predef)
+            return predef;
         const enumResult = getEnumCompletions(argName, argument.value);
         if (enumResult) {
             return buildCompletionResponse(enumResult);

package/dist/config.d.ts

@@ -83,7 +83,7 @@ export interface SearchContentResult {
 export interface MultipleFileInfoResult {
     readonly path: string;
     readonly info?: FileInfo;
-    readonly error?: string;
+    readonly error?: Error;
 }
 export interface GetMultipleFileInfoResult {
     readonly results: readonly MultipleFileInfoResult[];
@@ -95,18 +95,18 @@ export interface GetMultipleFileInfoResult {
     };
 }
 export declare const ErrorCode: {
-    readonly E_ACCESS_DENIED: "E_ACCESS_DENIED";
-    readonly E_NOT_FOUND: "E_NOT_FOUND";
-    readonly E_NOT_FILE: "E_NOT_FILE";
-    readonly E_NOT_DIRECTORY: "E_NOT_DIRECTORY";
-    readonly E_TOO_LARGE: "E_TOO_LARGE";
-    readonly E_TIMEOUT: "E_TIMEOUT";
-    readonly E_CANCELLED: "E_CANCELLED";
-    readonly E_INVALID_PATTERN: "E_INVALID_PATTERN";
-    readonly E_INVALID_INPUT: "E_INVALID_INPUT";
-    readonly E_PERMISSION_DENIED: "E_PERMISSION_DENIED";
-    readonly E_SYMLINK_NOT_ALLOWED: "E_SYMLINK_NOT_ALLOWED";
-    readonly E_UNKNOWN: "E_UNKNOWN";
+    readonly ACCESS_DENIED: "ACCESS_DENIED";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly NOT_FILE: "NOT_FILE";
+    readonly NOT_DIRECTORY: "NOT_DIRECTORY";
+    readonly TOO_LARGE: "TOO_LARGE";
+    readonly TIMEOUT: "TIMEOUT";
+    readonly CANCELLED: "CANCELLED";
+    readonly INVALID_PATTERN: "INVALID_PATTERN";
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly SYMLINK_NOT_ALLOWED: "SYMLINK_NOT_ALLOWED";
+    readonly UNKNOWN: "UNKNOWN";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 export declare function formatBytes(bytes: number): string;