@j0hanz/filesystem-mcp 1.13.2 → 1.14.1

package/README.md

@@ -2,9 +2,9 @@
 
 [![npm version](https://img.shields.io/npm/v/%40j0hanz%2Ffilesystem-mcp?style=flat-square&logo=npm)](https://www.npmjs.com/package/%40j0hanz%2Ffilesystem-mcp) [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](#contributing-and-license)
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders) [![Install in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install_Server-C16FDE?logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders) [![Install in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install_Server-C16FDE?logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D)
 
-[![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem-mcp&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
+[![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
 
 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.
 
@@ -12,7 +12,7 @@ A local filesystem MCP server that lets LLMs and AI agents read, write, search,
 
 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.
 
-Supports **stdio** (default) and **Streamable HTTP + SSE** transports with per-session isolation.
+Supports stdio (default) and Streamable HTTP transport with SSE support. HTTP sessions are implemented with isolated per-session server state.
 
 ## Key Features
 
@@ -20,7 +20,7 @@ Supports **stdio** (default) and **Streamable HTTP + SSE** transports with per-s
 - **Security-first** — path validation, symlink escape prevention, sensitive file denylist, localhost-only CORS, optional API key auth
 - **Dual transport** — stdio for local use, Streamable HTTP with SSE for networked/multi-session deployments
 - **Structured output** — all tools return typed `outputSchema` / `structuredContent` for reliable LLM parsing
-- **Self-documenting** — 6 built-in resources (`internal://instructions`, `internal://tool-catalog`, etc.) and a `get-help` prompt
+- **Self-documenting** — 6 built-in resources (`internal://instructions`, `internal://tool-catalog`, etc.) and 4 built-in prompts (`get-help`, `compare-files`, `analyze-path`, `get-tool-help`)
 
 ## Requirements
 
@@ -31,7 +31,7 @@ Supports **stdio** (default) and **Streamable HTTP + SSE** transports with per-s
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -82,14 +82,14 @@ Examples:
 <details>
 <summary><b>Install in VS Code</b></summary>
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D)
 
 Add to `.vscode/mcp.json`:
 
 ```json
 {
   "servers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -100,7 +100,7 @@ Add to `.vscode/mcp.json`:
 Or install via CLI:
 
 ```sh
-code --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
+code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
 ```
 
 </details>
@@ -108,14 +108,14 @@ code --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/f
 <details>
 <summary><b>Install in VS Code Insiders</b></summary>
 
-[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem-mcp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders)
+[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D&quality=insiders)
 
 Add to `.vscode/mcp.json`:
 
 ```json
 {
   "servers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -126,7 +126,7 @@ Add to `.vscode/mcp.json`:
 Or install via CLI:
 
 ```sh
-code-insiders --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
+code-insiders --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
 ```
 
 </details>
@@ -134,14 +134,14 @@ code-insiders --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","
 <details>
 <summary><b>Install in Cursor</b></summary>
 
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
 
 Add to `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -156,10 +156,12 @@ Add to `~/.cursor/mcp.json`:
 
 [![Install in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install_Server-C16FDE?logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22filesystem-mcp%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D%7D)
 
+Add to `<SOLUTIONDIR>.mcp.json` or `%USERPROFILE%\.mcp.json`:
+
 ```json
 {
-  "mcpServers": {
-    "filesystem-mcp": {
+  "servers": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -172,17 +174,20 @@ Add to `~/.cursor/mcp.json`:
 <details>
 <summary><b>Install in Goose</b></summary>
 
-[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem-mcp&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
+[![Install in Goose](https://block.github.io/goose/img/extension-install-dark.svg)](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Ffilesystem-mcp%40latest&id=%40j0hanz%2Ffilesystem-mcp&name=filesystem&description=MCP%20Server%20that%20enables%20LLMs%20to%20interact%20with%20the%20local%20filesystem.)
 
-```json
-{
-  "mcpServers": {
-    "filesystem-mcp": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
+Add to `~/.config/goose/config.yaml`:
+
+```yaml
+extensions:
+  filesystem:
+    name: Filesystem MCP
+    cmd: npx
+    args:
+      - -y
+      - '@j0hanz/filesystem-mcp@latest'
+    enabled: true
+    type: stdio
 ```
 
 </details>
@@ -190,12 +195,12 @@ Add to `~/.cursor/mcp.json`:
 <details>
 <summary><b>Add to LM Studio</b></summary>
 
-[![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
+[![Add to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
 
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -213,7 +218,7 @@ Add to `claude_desktop_config.json`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -230,12 +235,12 @@ Add to `claude_desktop_config.json`:
 claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
 ```
 
-Or add to config:
+Or add a project-scoped `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -253,7 +258,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -270,12 +275,12 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 amp mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
 ```
 
-Or add to config:
+Or add to `settings.json`:
 
 ```json
 {
-  "mcpServers": {
-    "filesystem-mcp": {
+  "amp.mcpServers": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -293,7 +298,7 @@ Add to `cline_mcp_settings.json`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -304,32 +309,35 @@ Add to `cline_mcp_settings.json`:
 </details>
 
 <details>
-<summary><b>Install in Codex CLI</b></summary>
+<summary><b>Install in Codex</b></summary>
 
-```json
-{
-  "mcpServers": {
-    "filesystem-mcp": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
+```sh
+codex mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest
+```
+
+Or add to `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project):
+
+```toml
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@j0hanz/filesystem-mcp@latest"]
 ```
 
 </details>
 
 <details>
-<summary><b>Install in GitHub Copilot</b></summary>
+<summary><b>Install in GitHub Copilot Coding Agent</b></summary>
 
-Add to `.vscode/mcp.json`:
+Add this JSON in your repository's GitHub Copilot coding agent MCP configuration:
 
 ```json
 {
-  "servers": {
-    "filesystem-mcp": {
+  "mcpServers": {
+    "filesystem": {
+      "type": "local",
       "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
+      "tools": ["*"]
     }
   }
 }
@@ -343,7 +351,7 @@ Add to `.vscode/mcp.json`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -361,7 +369,7 @@ Add to `.kiro/settings/mcp.json`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -379,7 +387,7 @@ Add to `~/.gemini/settings.json`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -397,11 +405,10 @@ Add to `~/.config/zed/settings.json`:
 ```json
 {
   "context_servers": {
-    "filesystem-mcp": {
-      "settings": {
-        "command": "npx",
-        "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-      }
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
+      "env": {}
     }
   }
 }
@@ -419,7 +426,7 @@ Add to VS Code `settings.json` under `augment.advanced`:
   "augment.advanced": {
     "mcpServers": [
       {
-        "id": "filesystem-mcp",
+        "id": "filesystem",
         "command": "npx",
         "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
       }
@@ -436,7 +443,7 @@ Add to VS Code `settings.json` under `augment.advanced`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -452,7 +459,7 @@ Add to VS Code `settings.json` under `augment.advanced`:
 ```json
 {
   "mcpServers": {
-    "filesystem-mcp": {
+    "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
     }
@@ -536,6 +543,9 @@ Create directories, move/rename files, delete files, and verify file integrity v
     |
     +-- prompts/get ─────────────────────────────────────────
     |   +-- get-help (optional topic argument)
+    |   +-- compare-files (original, modified)
+    |   +-- analyze-path (path)
+    |   +-- get-tool-help (name)
     |
     +-- Capabilities: logging, resources, tools, prompts, completions, tasks
 ```
@@ -567,17 +577,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-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       | 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                                  |
 
 ---
 
@@ -585,16 +595,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-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                                                            |
 
 ---
 
@@ -602,26 +612,29 @@ Find files by glob pattern. Returns matching files with metadata.
 
 Render a directory tree with bounded recursion. Returns ASCII tree + structured JSON.
 
-| 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           |
-| `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)                       |
+| `maxDepth`       | integer | no       | Depth (0 = root node only). Default: 10, Max: 100    |
+| `maxEntries`     | integer | no       | Max entries. Default: 5000, Max: 100000              |
+| `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` |
 
 ---
 
 #### `read`
 
-Read text file contents. Use `head` to preview first N lines of large files.
+Read text file contents. Use `head`/`tail` to preview first/last N lines of large files.
 
-| Parameter   | Type    | Required | Description                                         |
-| ----------- | ------- | -------- | --------------------------------------------------- |
-| `path`      | string  | **yes**  | Absolute path to file                               |
-| `head`      | integer | no       | Read first N lines (1-100000)                       |
-| `startLine` | integer | no       | Start line (1-based, inclusive)                     |
-| `endLine`   | integer | no       | End line (1-based, inclusive). Requires `startLine` |
+| Parameter     | Type    | Required | Description                                                 |
+| ------------- | ------- | -------- | ----------------------------------------------------------- |
+| `path`        | string  | **yes**  | Absolute path to file                                       |
+| `head`        | integer | no       | Read first N lines (1-100000)                               |
+| `tail`        | integer | no       | Read last N lines (1-100000)                                |
+| `startLine`   | integer | no       | Start line (1-based, inclusive)                             |
+| `endLine`     | integer | no       | End line (1-based, inclusive). Requires `startLine`         |
+| `includeHash` | boolean | no       | Include SHA-256 hash of full file content. Default: `false` |
 
 ---
 
@@ -633,6 +646,7 @@ Read multiple text files in one request.
 | ----------- | -------- | -------- | ------------------------------- |
 | `paths`     | string[] | **yes**  | Files to read (1-100 paths)     |
 | `head`      | integer  | no       | Read first N lines of each file |
+| `tail`      | integer  | no       | Read last N lines of each file  |
 | `startLine` | integer  | no       | Start line (1-based) per file   |
 | `endLine`   | integer  | no       | End line (1-based) per file     |
 
@@ -662,18 +676,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 (1-100000). Default: 100                                                  |
+| `filePattern`    | string  | no       | Relative glob for candidate files (e.g. `**/*.ts`). Absolute paths and `..` are rejected |
+| `includeHidden`  | boolean | no       | Include dotfiles. Default: `false`                                                       |
+| `includeIgnored` | boolean | no       | Include ignored items. Default: `false`                                                  |
 
 ---
 
@@ -706,7 +720,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` |
 
@@ -778,34 +792,39 @@ 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` |
+| Parameter        | Type    | Required | Description                                                                  |
+| ---------------- | ------- | -------- | ---------------------------------------------------------------------------- |
+| `path`           | string  | no       | Base directory (default: root)                                               |
+| `filePattern`    | string  | **yes**  | Relative glob pattern (e.g. `**/*.ts`). Absolute paths and `..` are rejected |
+| `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
 
-| Resource     | URI                            | MIME Type     | Description                                                        |
-| ------------ | ------------------------------ | ------------- | ------------------------------------------------------------------ |
-| Instructions | `internal://instructions`      | text/markdown | Comprehensive usage rules and guidelines                           |
-| Tool Catalog | `internal://tool-catalog`      | text/markdown | Tool selection guide and data flow map                             |
-| Workflows    | `internal://workflows`         | text/markdown | Standard operating procedures for exploration, search, edit, patch |
-| Tool Info    | `internal://tool-info/{name}`  | text/markdown | Per-tool contract details, nuances, gotchas                        |
-| Result Cache | `filesystem-mcp://result/{id}` | text/markdown | Ephemeral cached tool output (large results externalized here)     |
-| Metrics      | `filesystem-mcp://metrics`     | text/markdown | Live per-tool call/error/avgDurationMs snapshot                    |
+| Resource     | URI                            | MIME Type        | Description                                                        |
+| ------------ | ------------------------------ | ---------------- | ------------------------------------------------------------------ |
+| Instructions | `internal://instructions`      | text/markdown    | Comprehensive usage rules and guidelines                           |
+| Tool Catalog | `internal://tool-catalog`      | text/markdown    | Tool selection guide and data flow map                             |
+| Workflows    | `internal://workflows`         | text/markdown    | Standard operating procedures for exploration, search, edit, patch |
+| Tool Info    | `internal://tool-info/{name}`  | text/markdown    | Per-tool contract details, nuances, gotchas                        |
+| Result Cache | `filesystem-mcp://result/{id}` | text/plain       | Ephemeral cached tool output (large results externalized here)     |
+| Metrics      | `filesystem-mcp://metrics`     | application/json | Live per-tool call/error/avgDurationMs snapshot                    |
 
 ### Prompts
 
-| Prompt     | Arguments          | Description                                                            |
-| ---------- | ------------------ | ---------------------------------------------------------------------- |
-| `get-help` | `topic` (optional) | Return usage instructions. Optionally filter by section heading prefix |
+| Prompt          | Arguments              | Description                                                            |
+| --------------- | ---------------------- | ---------------------------------------------------------------------- |
+| `get-help`      | `topic` (optional)     | Return usage instructions. Optionally filter by section heading prefix |
+| `compare-files` | `original`, `modified` | Generate a workflow for comparing two files using `diff_files`         |
+| `analyze-path`  | `path`                 | Generate a workflow for analyzing a file or directory                  |
+| `get-tool-help` | `name`                 | Return a prompt with the authoritative contract for a specific tool    |
 
 ## MCP Capabilities
 
@@ -814,8 +833,8 @@ Bulk search-and-replace across files matching a glob. Replaces **all** occurrenc
 | `logging`     | confirmed | `src/server/bootstrap.ts` — registered in capabilities                     |
 | `resources`   | confirmed | `src/server/bootstrap.ts` — 6 resources registered                         |
 | `tools`       | confirmed | `src/server/bootstrap.ts` — 18 tools registered                            |
-| `prompts`     | confirmed | `src/server/bootstrap.ts` — `get-help` prompt registered                   |
-| `completions` | confirmed | `src/completions.ts` — path + topic auto-completion                        |
+| `prompts`     | confirmed | `src/server/bootstrap.ts` — 4 prompts registered                           |
+| `completions` | confirmed | `src/completions.ts` — path, topic, and tool-name auto-completion          |
 | `tasks`       | confirmed | `src/server/bootstrap.ts` — optional task support (list, cancel, requests) |
 
 ### Tool Annotations
@@ -881,18 +900,16 @@ When started with `--port <number>`, the server exposes a single MCP endpoint:
 
 ## Development
 
-| Script       | Command                                                   | Purpose                           |
-| ------------ | --------------------------------------------------------- | --------------------------------- |
-| `dev`        | `tsc --watch`                                             | Watch mode TypeScript compilation |
-| `dev:run`    | `node --env-file=.env --watch dist/index.js`              | Run server with auto-reload       |
-| `start`      | `node dist/index.js`                                      | Run production server             |
-| `build`      | `node scripts/tasks.mjs build`                            | Clean build                       |
-| `test`       | `node scripts/tasks.mjs test`                             | Build + run all tests             |
-| `test:fast`  | `node --test --import tsx/esm src/__tests__/**/*.test.ts` | Run tests without build           |
-| `lint`       | `eslint .`                                                | Lint source                       |
-| `type-check` | `node scripts/tasks.mjs type-check`                       | Type-check src + tests            |
-| `format`     | `prettier --write .`                                      | Format code                       |
-| `inspector`  | `npm run build && npx @modelcontextprotocol/inspector`    | Launch MCP Inspector              |
+- `dev` — `tsc --watch --preserveWatchOutput` — Watch mode TypeScript compilation
+- `dev:run` — `node --env-file=.env --watch dist/index.js` — Run server with auto-reload
+- `start` — `node dist/index.js` — Run production server
+- `build` — `node scripts/tasks.mjs build` — Clean build
+- `test` — `node scripts/tasks.mjs test` — Build + run all tests
+- `test:fast` — `node --test --import tsx/esm src/__tests__/**/*.test.ts node-tests/**/*.test.ts` — Run tests without build
+- `lint` — `eslint .` — Lint source
+- `type-check` — `node scripts/tasks.mjs type-check` — Type-check src + tests
+- `format` — `prettier --write .` — Format code
+- `inspector` — `npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js ${workspaceFolder}` — Launch MCP Inspector
 
 ## Build and Release
 

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;
     }