@j0hanz/filesystem-mcp 1.1.2 → 1.2.0

package/README.md

@@ -2,180 +2,104 @@
 
 ![npm version](https://img.shields.io/npm/v/@j0hanz/filesystem-mcp) ![License](https://img.shields.io/npm/l/@j0hanz/filesystem-mcp) ![Node.js Version](https://img.shields.io/node/v/@j0hanz/filesystem-mcp) ![Docker Image](https://ghcr-badge.egpl.dev/j0hanz/filesystem-mcp/latest_tag?trim=major&label=docker)
 
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0078d7?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22filesystem-mcp%22%2C%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-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%7B%22name%22%3A%22filesystem-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Ffilesystem-mcp%40latest%22%5D%7D) [![Install in Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Install-f79a2e?logo=claude&logoColor=white)](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-server) [![Install in Cursor](https://img.shields.io/badge/Cursor-Install-000000?logo=cursor&logoColor=white)](https://cursor.com/deeplink/mcp-install?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
+[![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)
 
-MCP Server that enables LLMs to interact with the local filesystem. Provides tools for navigation, file management, searching, and analysis, all within a secure, allowed set of directories. Ideal for agents needing to read/write files, explore directory structures, or perform file operations as part of their tasks.
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/deeplink/mcp-install?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
 
-## Key Features
-
-- **Navigation**: List directories (`ls`), view trees (`tree`), and discover workspace roots (`roots`).
-- **File Management**: Create (`mkdir`), write (`write`), edit (`edit`), move (`mv`), and delete (`rm`) files/directories.
-- **Search**: Find files by glob pattern (`find`) or search content using regex (`grep`).
-- **Analysis**: Inspect metadata (`stat`), calculate hashes (`calculate_hash`), and compare files (`diff_files`).
-- **Batch Operations**: Read multiple files (`read_many`) or replace text across many files (`search_and_replace`).
-- **Security**: Strictly scoped to allowed directories provided at startup.
+MCP Server that enables LLMs to interact with the local filesystem. Provides tools for navigation, search, file management, and analysis — all scoped to allowed directories.
 
-## Tech Stack
+## Overview
 
-- **Runtime**: Node.js >= 24
-- **Language**: TypeScript
-- **SDK**: `@modelcontextprotocol/sdk`
-- **Libraries**: `zod`, `commander`, `re2`, `diff`
+Filesystem MCP exposes a rich set of tools for reading, writing, searching, and inspecting files and directories. All operations are strictly bounded to the directories you provide at startup, preventing access to any path outside those roots.
 
-## Repository Structure
+## Key Features
 
-```text
-.
-├── src/
-│   ├── index.ts        # Entry point
-│   ├── server.ts       # MCP Server implementation
-│   ├── tools/          # Individual tool implementations
-│   └── lib/            # Shared utilities
-├── assets/             # Images and static resources
-├── scripts/            # Build and maintenance scripts
-└── package.json
-```
+- **Navigation**: List directory contents (`ls`), render trees (`tree`), and query workspace roots (`roots`).
+- **File I/O**: Read single or multiple files (`read`, `read_many`); write, edit, move, and delete (`write`, `edit`, `mv`, `rm`).
+- **Search**: Find files by glob pattern (`find`) or search content with full regex support (`grep`).
+- **Analysis**: Metadata and token estimates (`stat`, `stat_many`), SHA-256 hashing (`calculate_hash`), and unified diffs (`diff_files`).
+- **Patch & Replace**: Apply unified patches (`apply_patch`) and bulk search-and-replace across files (`search_and_replace`).
+- **Tasks**: Long-running tools support background task execution with progress notifications and cancellation.
+- **Large Output Handling**: Oversized results are externalized to ephemeral resource URIs instead of truncating inline.
+- **Security**: Strict path validation, safe regex via RE2, `.gitignore`-aware operations, and atomic writes.
 
 ## Requirements
 
-- Node.js >= 24
-
-## Quickstart
+- **Node.js** `>= 24`
 
-Run directly with `npx`:
+## Quick Start
 
-```bash
-npx -y @j0hanz/filesystem-mcp@latest "C:\path\to\allowed\directory"
-```
-
-## Installation
-
-### NPX (Recommended)
-
-```bash
-npx -y @j0hanz/filesystem-mcp@latest [options] [directories...]
+```json
+{
+  "mcpServers": {
+    "filesystem-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/allowed/dir"]
+    }
+  }
+}
 ```
 
-### Docker
+Run directly:
 
 ```bash
-docker run -i --rm \
-  -v /path/to/your/project:/projects/workspace:ro \
-  ghcr.io/j0hanz/filesystem-mcp:latest \
-  /projects/workspace
+npx -y @j0hanz/filesystem-mcp@latest /path/to/allowed/dir
 ```
 
-> Mount host directories as volumes to `/projects/` and pass the container paths as arguments.
-
-### From Source
-
-1. Clone the repository
-2. Install dependencies:
-
-   ```bash
-   npm ci
-   ```
-
-3. Build the project:
-
-   ```bash
-   npm run build
-   ```
-
-4. Run:
+## Client Configuration
 
-   ```bash
-   node dist/index.js [options] [directories...]
-   ```
-
-## Configuration
-
-Allowed directories can be provided via command-line arguments, via the MCP Roots protocol, or by using `--allow-cwd`.
-
-### Arguments
-
-| Argument           | Description                                                                 |
-| :----------------- | :-------------------------------------------------------------------------- |
-| `[allowedDirs...]` | Positional arguments specifying the root directories the server can access. |
-
-### Options
-
-| Option          | Description                                                |
-| :-------------- | :--------------------------------------------------------- |
-| `--allow-cwd`   | Allow the current working directory as an additional root. |
-| `-v, --version` | Display server version.                                    |
-| `-h, --help`    | Display command help.                                      |
+<details>
+<summary><b>Install in VS Code</b></summary>
 
-## Usage
+[![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)
 
-### Stdio Transport
+Or add manually to `.vscode/mcp.json`:
 
-The server communicates via `stdio`. Ensure your MCP client is configured to run the server command and capture standard input/output.
+```json
+{
+  "servers": {
+    "filesystem-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]
+    }
+  }
+}
+```
 
-## MCP Surface
+CLI:
 
-### Tools
+```bash
+code --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","${workspaceFolder}"]}'
+```
 
-| Tool                 | Description                         | Key Parameters                                |
-| :------------------- | :---------------------------------- | :-------------------------------------------- |
-| `roots`              | List allowed workspace roots        | None                                          |
-| `ls`                 | List directory contents             | `path`, `includeHidden`                       |
-| `find`               | Find files by glob pattern          | `pattern`, `path`, `maxDepth`                 |
-| `tree`               | Generate directory tree             | `path`, `maxDepth`                            |
-| `read`               | Read file content                   | `path`, `head`                                |
-| `read_many`          | Read multiple files                 | `paths`                                       |
-| `grep`               | Search file content (regex/literal) | `pattern`, `path`, `isRegex`                  |
-| `stat`               | Get file metadata                   | `path`                                        |
-| `stat_many`          | Get metadata for multiple files     | `paths`                                       |
-| `calculate_hash`     | Calculate SHA-256 hash              | `path`                                        |
-| `mkdir`              | Create directory (recursive)        | `path`                                        |
-| `write`              | Write file (create/overwrite)       | `path`, `content`                             |
-| `edit`               | Edit file (string replacement)      | `path`, `edits`                               |
-| `mv`                 | Move or rename file/directory       | `source`, `destination`                       |
-| `rm`                 | Delete file or directory            | `path`, `recursive`                           |
-| `diff_files`         | Generate unified diff               | `original`, `modified`                        |
-| `apply_patch`        | Apply unified patch                 | `path`, `patch`                               |
-| `search_and_replace` | Search & replace across files       | `filePattern`, `searchPattern`, `replacement` |
-
-### Behavioral Notes
-
-- `rm` with `recursive: false`:
-  - Deletes files and empty directories.
-  - Returns `E_INVALID_INPUT` for non-empty directories with guidance to use `recursive: true`.
-- `includeIgnored: false` (default) for navigation/search tools:
-  - Excludes common generated/vendor directories such as `node_modules`, `dist`, `.git`, and similar patterns.
-  - Set `includeIgnored: true` to include those entries.
+</details>
 
-### Resources
+<details>
+<summary><b>Install in VS Code Insiders</b></summary>
 
-| URI Pattern                    | Description                                      |
-| :----------------------------- | :----------------------------------------------- |
-| `internal://instructions`      | Usage guidance and documentation                 |
-| `filesystem-mcp://result/{id}` | Ephemeral cached tool output (for large results) |
+[![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)
 
-### Prompts
+CLI:
 
-| Prompt     | Description                               |
-| :--------- | :---------------------------------------- |
-| `get-help` | Returns usage instructions for the server |
+```bash
+code-insiders --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","${workspaceFolder}"]}'
+```
 
-## Client Configuration Examples
+</details>
 
 <details>
-<summary><strong>Claude Desktop</strong></summary>
+<summary><b>Install in Cursor</b></summary>
 
-Add to your `claude_desktop_config.json`:
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/deeplink/mcp-install?name=filesystem-mcp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
+
+Or add to `~/.cursor/mcp.json`:
 
 ```json
 {
   "mcpServers": {
-    "filesystem": {
+    "filesystem-mcp": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@j0hanz/filesystem-mcp@latest",
-        "C:\\path\\to\\allowed\\directory"
-      ]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
     }
   }
 }
@@ -184,32 +108,41 @@ Add to your `claude_desktop_config.json`:
 </details>
 
 <details>
-<summary><strong>Cursor</strong></summary>
+<summary><b>Install in Claude Desktop</b></summary>
 
-Add to your `.cursor/mcp.json` or configure via UI:
+Add to `claude_desktop_config.json`:
 
 ```json
 {
-  "id": "filesystem",
-  "name": "filesystem",
-  "command": "npx",
-  "args": ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]
+  "mcpServers": {
+    "filesystem-mcp": {
+      "command": "npx",
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
+    }
+  }
 }
 ```
 
 </details>
 
 <details>
-<summary><strong>VS Code</strong></summary>
+<summary><b>Install in Claude Code</b></summary>
+
+```bash
+claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest /path/to/dir
+```
 
-Add to your `.vscode/mcp.json`:
+</details>
+
+<details>
+<summary><b>Install in Windsurf</b></summary>
 
 ```json
 {
   "mcpServers": {
-    "filesystem": {
+    "filesystem-mcp": {
       "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
     }
   }
 }
@@ -218,14 +151,32 @@ Add to your `.vscode/mcp.json`:
 </details>
 
 <details>
-<summary><strong>Docker (any MCP client)</strong></summary>
+<summary><b>Install in Codex</b></summary>
+
+```toml
+[mcp_servers.filesystem-mcp]
+command = "npx"
+args = ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]
+```
 
-Use the Docker image with any MCP client that supports stdio transport:
+</details>
+
+<details>
+<summary><b>Docker</b></summary>
+
+```bash
+docker run -i --rm \
+  -v /path/to/your/project:/projects/workspace:ro \
+  ghcr.io/j0hanz/filesystem-mcp:latest \
+  /projects/workspace
+```
+
+MCP config:
 
 ```json
 {
   "mcpServers": {
-    "filesystem": {
+    "filesystem-mcp": {
       "command": "docker",
       "args": [
         "run",
@@ -243,64 +194,439 @@ Use the Docker image with any MCP client that supports stdio transport:
 
 </details>
 
-<details>
-<summary><strong>Codex</strong></summary>
+## MCP Surface
+
+### Tools
 
-Add to your configuration:
+| Tool                 | Description                                          |
+| :------------------- | :--------------------------------------------------- |
+| `roots`              | List workspace roots the server can access           |
+| `ls`                 | List directory contents (non-recursive)              |
+| `find`               | Find files by glob pattern                           |
+| `tree`               | Render a bounded directory tree                      |
+| `read`               | Read text content of a file                          |
+| `read_many`          | Read multiple files in one request                   |
+| `stat`               | Get file or directory metadata                       |
+| `stat_many`          | Get metadata for multiple paths                      |
+| `grep`               | Search file content by literal or RE2 regex          |
+| `calculate_hash`     | Compute SHA-256 hash of a file or directory          |
+| `diff_files`         | Generate a unified diff between two files            |
+| `mkdir`              | Create a directory (recursive)                       |
+| `write`              | Write content to a file (create or overwrite)        |
+| `edit`               | Edit a file via sequential string replacements       |
+| `mv`                 | Move or rename a file or directory                   |
+| `rm`                 | Delete a file or directory                           |
+| `apply_patch`        | Apply a unified diff patch to a file                 |
+| `search_and_replace` | Search and replace text across files matching a glob |
 
-```toml
-[mcp_servers.filesystem-mcp]
-command = "npx"
-args = ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]
+---
+
+#### `roots` — List workspace roots
+
+Enumerate the directories the server is allowed to access. Call this first in any session.
+
+No input parameters.
+
+---
+
+#### `ls` — List directory contents
+
+List immediate directory contents (non-recursive). Returns name, type, size, and modified date per entry.
+
+| Parameter               | Type                               | Required | Default | Description                                               |
+| :---------------------- | :--------------------------------- | :------: | :------ | :-------------------------------------------------------- |
+| `path`                  | string                             |    No    | root    | Base directory                                            |
+| `includeHidden`         | boolean                            |    No    | `false` | Include hidden items (`.`)                                |
+| `includeIgnored`        | boolean                            |    No    | `false` | Include `node_modules`, `.git`, etc.                      |
+| `pattern`               | string                             |    No    | —       | Glob filter enabling recursive traversal (e.g. `**/*.ts`) |
+| `sortBy`                | `name`\|`size`\|`modified`\|`type` |    No    | `name`  | Sort field                                                |
+| `maxDepth`              | integer                            |    No    | —       | Max recursion depth when `pattern` is set (1–50)          |
+| `maxEntries`            | integer                            |    No    | —       | Truncation limit (1–20,000)                               |
+| `includeSymlinkTargets` | boolean                            |    No    | `false` | Resolve and include symlink targets                       |
+
+---
+
+#### `find` — Find files by glob
+
+Locate files matching a glob pattern. Returns relative paths and metadata.
+
+| Parameter        | Type                               | Required | Default | Description                                         |
+| :--------------- | :--------------------------------- | :------: | :------ | :-------------------------------------------------- |
+| `pattern`        | string                             |   Yes    | —       | Glob pattern (e.g. `**/*.ts`, `src/*.js`)           |
+| `path`           | string                             |    No    | root    | Search root                                         |
+| `maxResults`     | integer                            |    No    | `100`   | Max results (1–10,000)                              |
+| `maxDepth`       | integer                            |    No    | —       | Max directory depth to scan (0–100)                 |
+| `sortBy`         | `name`\|`size`\|`modified`\|`path` |    No    | `path`  | Sort field                                          |
+| `includeHidden`  | boolean                            |    No    | `false` | Include hidden files                                |
+| `includeIgnored` | boolean                            |    No    | `false` | Include ignored directories (disables `.gitignore`) |
+
+> [!TIP]
+> Supports background task execution with progress reporting.
+
+---
+
+#### `tree` — Render directory tree
+
+Returns both an ASCII tree (text) and a structured JSON tree.
+
+| Parameter        | Type    | Required | Default | Description                                         |
+| :--------------- | :------ | :------: | :------ | :-------------------------------------------------- |
+| `path`           | string  |    No    | root    | Base directory                                      |
+| `maxDepth`       | integer |    No    | `5`     | Max depth (0–50); `0` = root node only, no children |
+| `maxEntries`     | integer |    No    | `1000`  | Max entries (1–20,000)                              |
+| `includeHidden`  | boolean |    No    | `false` | Include hidden items                                |
+| `includeIgnored` | boolean |    No    | `false` | Include ignored items (disables `.gitignore`)       |
+
+---
+
+#### `read` — Read file content
+
+Read text content of a single file with optional line-range or head preview.
+
+| Parameter   | Type    | Required | Default | Description                                                                   |
+| :---------- | :------ | :------: | :------ | :---------------------------------------------------------------------------- |
+| `path`      | string  |   Yes    | —       | Absolute path to file                                                         |
+| `head`      | integer |    No    | —       | Read first N lines (1–100,000); mutually exclusive with `startLine`/`endLine` |
+| `startLine` | integer |    No    | —       | Start line (1-based, inclusive)                                               |
+| `endLine`   | integer |    No    | —       | End line (1-based, inclusive); requires `startLine`                           |
+
+Large files return a `resourceUri`; call `resources/read` on that URI for full content.
+
+---
+
+#### `read_many` — Read multiple files
+
+Batch-read up to 100 files in a single request.
+
+| Parameter   | Type     | Required | Default | Description                              |
+| :---------- | :------- | :------: | :------ | :--------------------------------------- |
+| `paths`     | string[] |   Yes    | —       | File paths (1–100 items)                 |
+| `head`      | integer  |    No    | —       | Read first N lines of each file          |
+| `startLine` | integer  |    No    | —       | Start line per file                      |
+| `endLine`   | integer  |    No    | —       | End line per file (requires `startLine`) |
+
+Per-file `truncationReason` can be `head`, `range`, or `externalized`. Total read budget is capped internally.
+
+---
+
+#### `stat` — Get file/directory metadata
+
+Returns name, type, size, created/modified/accessed timestamps, permissions, MIME type, and a token estimate (`size ÷ 4`).
+
+| Parameter | Type   | Required | Default | Description   |
+| :-------- | :----- | :------: | :------ | :------------ |
+| `path`    | string |   Yes    | —       | Absolute path |
+
+---
+
+#### `stat_many` — Get metadata for multiple paths
+
+Batch version of `stat`.
+
+| Parameter | Type     | Required | Default | Description         |
+| :-------- | :------- | :------: | :------ | :------------------ |
+| `paths`   | string[] |   Yes    | —       | Paths (1–100 items) |
+
+---
+
+#### `grep` — Search file content
+
+Search for text within files using literal match or RE2 regex. Returns matching lines with optional context.
+
+| Parameter        | Type    | Required | Default | Description                                                         |
+| :--------------- | :------ | :------: | :------ | :------------------------------------------------------------------ |
+| `pattern`        | string  |   Yes    | —       | Text to search (literal by default, RE2 regex when `isRegex: true`) |
+| `path`           | string  |    No    | root    | Search root (file or directory)                                     |
+| `isRegex`        | boolean |    No    | `false` | Treat `pattern` as RE2 regex                                        |
+| `caseSensitive`  | boolean |    No    | `false` | Case-sensitive matching                                             |
+| `wholeWord`      | boolean |    No    | `false` | Match whole words only                                              |
+| `contextLines`   | integer |    No    | `0`     | Lines of context before/after each match (0–50)                     |
+| `maxResults`     | integer |    No    | `500`   | Max match rows returned (0–10,000)                                  |
+| `filePattern`    | string  |    No    | `**/*`  | Glob to restrict candidate files (e.g. `**/*.ts`)                   |
+| `includeHidden`  | boolean |    No    | `false` | Include hidden files                                                |
+| `includeIgnored` | boolean |    No    | `false` | Include ignored directories                                         |
+
+> [!NOTE]
+> RE2 does not support lookahead, lookbehind, or backreferences. Results exceeding 50 inline matches are externalized via `resourceUri`.
+
+---
+
+#### `calculate_hash` — SHA-256 hash
+
+Compute a SHA-256 hash. For directories, produces a deterministic composite hash of all contained files (lexicographically sorted, `.gitignore`-aware).
+
+| Parameter | Type   | Required | Default | Description            |
+| :-------- | :----- | :------: | :------ | :--------------------- |
+| `path`    | string |   Yes    | —       | File or directory path |
+
+---
+
+#### `diff_files` — Generate unified diff
+
+Create a unified diff between two files. Check `isIdentical` in the response — if `true`, the files match and no patch is needed.
+
+| Parameter          | Type    | Required | Default | Description                        |
+| :----------------- | :------ | :------: | :------ | :--------------------------------- |
+| `original`         | string  |   Yes    | —       | Original file path                 |
+| `modified`         | string  |   Yes    | —       | Modified file path                 |
+| `context`          | integer |    No    | —       | Lines of context in the diff       |
+| `ignoreWhitespace` | boolean |    No    | `false` | Ignore leading/trailing whitespace |
+| `stripTrailingCr`  | boolean |    No    | `false` | Strip trailing carriage returns    |
+
+Large diffs are externalized to a `resourceUri`.
+
+---
+
+#### `mkdir` — Create directory
+
+Create a directory and all missing parent directories (recursive).
+
+| Parameter | Type   | Required | Default | Description              |
+| :-------- | :----- | :------: | :------ | :----------------------- |
+| `path`    | string |   Yes    | —       | Directory path to create |
+
+---
+
+#### `write` — Write file
+
+Create or overwrite a file. Parent directories are created automatically.
+
+| Parameter | Type   | Required | Default | Description      |
+| :-------- | :----- | :------: | :------ | :--------------- |
+| `path`    | string |   Yes    | —       | File path        |
+| `content` | string |   Yes    | —       | Content to write |
+
+> [!CAUTION]
+> Overwrites existing file content without confirmation.
+
+---
+
+#### `edit` — Edit file
+
+Apply sequential literal string replacements to an existing file. Replaces the **first** occurrence of each `oldText`.
+
+| Parameter | Type                   | Required | Default | Description                            |
+| :-------- | :--------------------- | :------: | :------ | :------------------------------------- |
+| `path`    | string                 |   Yes    | —       | File to edit                           |
+| `edits`   | `{oldText, newText}[]` |   Yes    | —       | Ordered list of replacement operations |
+| `dryRun`  | boolean                |    No    | `false` | Validate edits without writing         |
+
+Include 3–5 lines of surrounding context in `oldText` to uniquely target the location. Unmatched edits are reported in `unmatchedEdits`.
+
+---
+
+#### `mv` — Move or rename
+
+Move or rename a file or directory. Parent directories of the destination are created automatically. Falls back to copy+delete for cross-device moves.
+
+| Parameter     | Type   | Required | Default | Description      |
+| :------------ | :----- | :------: | :------ | :--------------- |
+| `source`      | string |   Yes    | —       | Source path      |
+| `destination` | string |   Yes    | —       | Destination path |
+
+---
+
+#### `rm` — Delete file or directory
+
+Delete a file or directory.
+
+| Parameter           | Type    | Required | Default | Description                     |
+| :------------------ | :------ | :------: | :------ | :------------------------------ |
+| `path`              | string  |   Yes    | —       | Path to delete                  |
+| `recursive`         | boolean |    No    | `false` | Delete non-empty directories    |
+| `ignoreIfNotExists` | boolean |    No    | `false` | No error if the path is missing |
+
+> [!WARNING]
+> Non-empty directories with `recursive: false` return `E_INVALID_INPUT` with guidance to retry using `recursive: true`.
+
+---
+
+#### `apply_patch` — Apply unified patch
+
+Apply a unified diff patch to a file. Always validate with `dryRun: true` before writing.
+
+| Parameter                | Type    | Required | Default | Description                                            |
+| :----------------------- | :------ | :------: | :------ | :----------------------------------------------------- |
+| `path`                   | string  |   Yes    | —       | Target file path                                       |
+| `patch`                  | string  |   Yes    | —       | Unified diff patch content (must include hunk headers) |
+| `fuzzFactor`             | integer |    No    | `0`     | Fuzzy matching tolerance                               |
+| `autoConvertLineEndings` | boolean |    No    | `true`  | Auto-convert line endings to match the target file     |
+| `dryRun`                 | boolean |    No    | `false` | Validate without writing                               |
+
+If patch application fails, regenerate a fresh patch via `diff_files` against the current file content and retry.
+
+---
+
+#### `search_and_replace` — Search and replace across files
+
+Replace text in all files matching a glob. Replaces **all** occurrences per file. Use `dryRun: true` to preview scope before writing.
+
+| Parameter       | Type    | Required | Default | Description                                                              |
+| :-------------- | :------ | :------: | :------ | :----------------------------------------------------------------------- |
+| `filePattern`   | string  |   Yes    | —       | Glob for target files (e.g. `**/*.ts`)                                   |
+| `searchPattern` | string  |   Yes    | —       | Text to find                                                             |
+| `replacement`   | string  |   Yes    | —       | Replacement text                                                         |
+| `path`          | string  |    No    | root    | Search root directory                                                    |
+| `isRegex`       | boolean |    No    | `false` | Treat `searchPattern` as RE2 regex; supports capture groups (`$1`, `$2`) |
+| `dryRun`        | boolean |    No    | `false` | Preview matches without writing                                          |
+
+---
+
+### Resources
+
+| URI                            | Description                        | MIME Type       |
+| :----------------------------- | :--------------------------------- | :-------------- |
+| `internal://instructions`      | Usage guidance for models          | `text/markdown` |
+| `filesystem-mcp://result/{id}` | Ephemeral cached large tool output | varies          |
+
+### Prompts
+
+| Prompt     | Description                               |
+| :--------- | :---------------------------------------- |
+| `get-help` | Returns usage instructions for the server |
+
+### Tasks (Background Execution)
+
+The server declares full task capabilities (`tasks/list`, `tasks/cancel`). The following tools support task-based invocation with progress notifications:
+
+`find`, `tree`, `read`, `read_many`, `stat_many`, `grep`, `mkdir`, `write`, `mv`, `rm`, `calculate_hash`, `apply_patch`, `search_and_replace`
+
+Include `_meta.progressToken` in a `tools/call` request to receive `notifications/progress` updates. Use `tools/call` with a `task` field to invoke as a background task, then poll `tasks/get` and retrieve output via `tasks/result`.
+
+## Configuration
+
+### CLI
+
+```text
+filesystem-mcp [options] [allowedDirs...]
 ```
 
-</details>
+| Option             | Description                                               |
+| :----------------- | :-------------------------------------------------------- |
+| `[allowedDirs...]` | Positional: one or more directories the server may access |
+| `--allow-cwd`      | Allow the current working directory as an additional root |
+| `-v, --version`    | Display server version                                    |
+| `-h, --help`       | Display help                                              |
+
+Examples:
+
+```bash
+# Single directory
+filesystem-mcp /project/src
+
+# Multiple directories
+filesystem-mcp /project/src /project/tests
+
+# Current working directory
+filesystem-mcp --allow-cwd
+
+# Combined
+filesystem-mcp /project/src --allow-cwd
+```
+
+### Allowed Directories
+
+Directories are resolved from three sources, merged at runtime:
+
+1. **CLI arguments** — positional directory paths passed at startup.
+2. **MCP Roots protocol** — directories provided by the connected client after initialization (accepted only if they are within the CLI baseline when CLI directories are set).
+3. **`--allow-cwd`** — the current working directory is added automatically.
+
+> [!TIP]
+> If no directories are configured at startup and the connected client does not supply MCP Roots, all tool calls will fail. Pass at least one directory argument or use `--allow-cwd`.
 
 ## Security
 
-- **Path Restrictions**: All file operations are strictly validated against the allowed root directories provided at startup.
-- **Path Validation**: Uses `isPathWithinDirectories` to prevent path traversal attacks.
-- **Hidden Files**: Hidden files (starting with `.`) are excluded by default in listings and searches unless explicitly requested.
-- **Ignored Directories**: Ignored directories (for example `node_modules`, `.git`, `dist`) are excluded by default unless `includeIgnored=true`.
+- **Path validation**: All operations use `isPathWithinDirectories` to prevent path traversal attacks.
+- **Glob safety**: Glob patterns are validated to reject absolute paths and `..` traversal before execution.
+- **Safe regex**: `re2` executes regex (no catastrophic backtracking); `safe-regex2` rejects unsafe patterns before use.
+- **Hidden files**: Excluded from listings and searches by default; opt in with `includeHidden: true`.
+- **Ignored directories**: `node_modules`, `.git`, `dist`, and similar directories are excluded by default; opt in with `includeIgnored: true`.
+- **Windows safety**: Reserved device names (e.g. `CON`, `NUL`, `COM1`) and drive-relative paths (e.g. `C:path`) are rejected at the CLI.
+- **Input limits**: Paths are bounded to 4,096 characters; patterns to 1,000 characters.
+- **Atomic writes**: File writes use an atomic write-then-rename strategy to prevent partial writes.
+- **Docker**: The container runs as a non-root user (`mcp`).
+
+> [!IMPORTANT]
+> All diagnostic output goes to `stderr`. Tool handlers must never write to `stdout`, as doing so would corrupt the stdio transport.
+
+## Development
+
+### Install
+
+```bash
+npm ci
+```
+
+### Scripts
+
+| Script          | Command                                                   | Purpose                             |
+| :-------------- | :-------------------------------------------------------- | :---------------------------------- |
+| `dev`           | `tsc --watch`                                             | Watch-mode TypeScript compilation   |
+| `dev:run`       | `node --watch dist/index.js`                              | Run built server with file watching |
+| `build`         | `node scripts/tasks.mjs build`                            | Production build                    |
+| `test`          | `node scripts/tasks.mjs test`                             | Run full test suite                 |
+| `test:fast`     | `node --test --import tsx/esm src/__tests__/**/*.test.ts` | Fast test runner (no build step)    |
+| `test:coverage` | `node scripts/tasks.mjs test --coverage`                  | Test with coverage                  |
+| `lint`          | `eslint .`                                                | Lint source files                   |
+| `lint:fix`      | `eslint . --fix`                                          | Auto-fix lint issues                |
+| `format`        | `prettier --write .`                                      | Format all files                    |
+| `type-check`    | `node scripts/tasks.mjs type-check`                       | TypeScript type checking            |
+
+### MCP Inspector
+
+```bash
+npm run inspector
+```
+
+Or manually:
+
+```bash
+npx @modelcontextprotocol/inspector node dist/index.js /path/to/dir
+```
 
-## Testing Notes
+## Build & Release
 
-- For protocol-level validation, prefer an MCP SDK client (`listTools`, `listResources`, `listPrompts`, `callTool`, `readResource`) as source-of-truth.
-- Some third-party MCP CLIs may have URI parsing limitations when reading resources; if this happens, verify resource behavior through SDK client calls.
+Releases are triggered manually via [GitHub Actions](.github/workflows/release.yml) (`workflow_dispatch`). The pipeline:
 
-## Development Workflow
+1. Bumps `package.json` and `server.json` to the selected version (patch / minor / major or custom).
+2. Runs lint, type-check, tests, and build.
+3. Commits, tags (`vX.Y.Z`), and creates a GitHub Release with auto-generated notes.
+4. Publishes to **npm** (`@j0hanz/filesystem-mcp`) with OIDC provenance.
+5. Publishes to the **MCP Registry** (`io.github.j0hanz/filesystem-mcp`).
+6. Builds and pushes the **Docker image** (`ghcr.io/j0hanz/filesystem-mcp`) for `linux/amd64` and `linux/arm64`.
 
-1. **Install Dependencies**:
+The [Glama](https://glama.ai/mcp/servers/j0hanz/filesystem-mcp) listing requires a separate manual release step on the Glama dashboard.
 
-   ```bash
-   npm install
-   ```
+### Docker Build (local)
+
+```bash
+docker build -t filesystem-mcp .
+```
 
-2. **Development Mode** (watch):
+## Troubleshooting
 
-   ```bash
-   npm run dev
-   ```
+**No directories configured**
+If no directories are provided at startup and the client doesn't supply MCP Roots, all tool calls fail with `E_ACCESS_DENIED`. Use `roots` to inspect configured roots.
 
-3. **Run Locally**:
+**Path outside allowed directories**
+Tools return `E_ACCESS_DENIED` when a path is outside all allowed roots. Use `roots` first to see what is available.
 
-   ```bash
-   npm start -- --allow-cwd
-   ```
+**Empty directory or no matches**
+`find` and `grep` return empty results rather than errors when nothing matches. Verify the pattern and root path.
 
-4. **Test**:
+**Pattern rejected (`E_INVALID_PATTERN`)**
+Glob patterns cannot be absolute or use `..` to traverse upward. RE2 patterns are validated before use.
 
-   ```bash
-   npm run test
-   ```
+**Non-empty directory delete fails**
+`rm` returns `E_INVALID_INPUT` for non-empty directories without `recursive: true`. Either set `recursive: true` or remove contents first.
 
-5. **Lint & Format**:
+**Patch application failed**
+`apply_patch` requires valid unified hunk headers (`@@ -N,M +N,M @@`). Regenerate the patch with `diff_files` against the current file content and retry.
 
-   ```bash
-   npm run lint
-   npm run format
-   ```
+**Stdout contamination**
+The server uses stdio transport. Never write to `stdout` in custom integrations. All diagnostic output goes to `stderr`. For Claude Desktop, check `~/Library/Logs/Claude/mcp*.log` (macOS) or the equivalent on Windows.
 
 ## License
 
-MIT
+[MIT](LICENSE)