@j0hanz/filesystem-mcp 1.19.1 → 2.1.0

package/README.md

@@ -1,132 +1,91 @@
 # Filesystem MCP Server
 
-[![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)
+[![License](https://img.shields.io/github/license/j0hanz/filesystem-mcp?style=for-the-badge)](https://github.com/j0hanz/filesystem-mcp/blob/main/LICENSE) [![npm version](https://img.shields.io/npm/v/%40j0hanz%2Ffilesystem-mcp?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/@j0hanz/filesystem-mcp) [![Build](https://img.shields.io/github/actions/workflow/status/j0hanz/filesystem-mcp/release.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=build)](https://github.com/j0hanz/filesystem-mcp/actions) [![GitHub stars](https://img.shields.io/github/stars/j0hanz/filesystem-mcp?style=for-the-badge&logo=github)](https://github.com/j0hanz/filesystem-mcp/stargazers)
 
-[![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&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
-
-Secure filesystem MCP server for reading, writing, searching, diffing, and patching files.
-
-## 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)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://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-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-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 Cursor](https://img.shields.io/badge/Cursor-Install-000000?style=flat-square&logo=cursor&logoColor=white)](cursor://anysphere.cursor-deeplink/mcp/install?name=filesystem&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
 
 ## 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.
-
-Supports stdio (default) and Node Streamable HTTP transport. HTTP sessions are implemented with isolated per-session server state. The HTTP transport is stateful by default and currently non-resumable; it does not persist an event store for `Last-Event-ID` replay.
-
-## Key Features
+Filesystem-MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants read and write files within explicitly allowed directories. Sensitive file patterns (`.env`, `*.pem`, `*id_rsa*`) are blocked by default. It exposes filesystem tools, resources, and prompts over stdio or Streamable HTTP transport.
 
-- **18 filesystem tools** — read, write, search, diff, patch, hash, and bulk operations with structured output schemas
-- **Security-first** — path validation, symlink escape prevention, sensitive file denylist, localhost-only CORS, Host header validation for loopback HTTP binds, optional API key auth
-- **Dual transport** — stdio for local use, Node Streamable HTTP 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 4 built-in prompts (`get-help`, `compare-files`, `analyze-path`, `get-tool-help`)
+| Aspect       | Details                                        |
+| :----------- | :--------------------------------------------- |
+| **Status**   | Active (see npm badge for the current version) |
+| **Language** | TypeScript (strict)                            |
+| **Runtime**  | Node.js >= 24                                  |
+| **Package**  | npm                                            |
+| **License**  | MIT                                            |
 
-## Requirements
+## Features
 
-- Node.js >= 24
+| Feature                | Description                                                                                                |
+| :--------------------- | :--------------------------------------------------------------------------------------------------------- |
+| **Path guarding**      | Every path is validated against allowed roots; `.env`, `*.pem`, `*id_rsa*` and similar patterns are denied |
+| **Filesystem tools**   | Navigate, inspect, read, and write across all major file operations                                        |
+| **Batch operations**   | Most tools accept `path`, `paths[]`, or `files[]` for parallel execution                                   |
+| **Dual transport**     | stdio by default; `--port` enables Streamable HTTP                                                         |
+| **File subscriptions** | Resource subscriptions push change notifications when watched files update                                 |
+| **Regex safety**       | RE2 in all search tools: linear-time matching, so no pattern can ReDoS the server                          |
 
-## Quick Start
+## Built with
 
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
-```
+[![Node.js](https://img.shields.io/badge/node-%3E%3D24-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org) [![Docker](https://img.shields.io/badge/Docker-ready-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com)
 
-### Docker
+| Layer     | Technology                                                             |
+| :-------- | :--------------------------------------------------------------------- |
+| Protocol  | MCP SDK v2 (`@modelcontextprotocol/server`)                            |
+| Runtime   | Node.js >= 24 · TypeScript 6 · ESM                                     |
+| Transport | stdio (default) · Streamable HTTP (`--port`)                           |
+| Regex     | RE2 (`re2-wasm`) — linear time, no lookahead/lookbehind/backreferences |
+| Container | Docker alpine · multi-stage build · non-root user                      |
 
-```bash
-docker run -i --rm -v /path/to/project:/workspace:ro ghcr.io/j0hanz/filesystem-mcp /workspace
-```
+## Table of Contents
 
-Or using Docker Compose:
+- [Quick start](#quick-start)
+- [Usage](#usage)
+- [Project structure](#project-structure)
+- [Configuration](#configuration)
+- [Scripts](#scripts)
+- [Security](#security)
+- [Contributing](#contributing)
+- [License](#license)
 
-```yaml
-services:
-  filesystem-mcp:
-    build: .
-    stdin_open: true
-    volumes:
-      - ./:/projects/workspace:ro
-    command: ['/projects/workspace']
-```
+## Quick start
 
-### CLI Usage
+> [!NOTE]
+> Requires Node.js ≥ 24.
 
-```
-filesystem-mcp [options] [allowedDirs...]
+### Prerequisites
 
-Arguments:
-  allowedDirs              Directories the server can access
+| Requirement | Version / Notes              |
+| :---------- | :--------------------------- |
+| Node.js     | ≥ 24                         |
+| npm         | Bundled with Node.js         |
+| Docker      | Optional — for container use |
 
-Options:
-  --allow-cwd              Allow the current working directory as an additional root
-  --port <number>          Enable HTTP transport on the given port
-  -v, --version            Display server version
-  -h, --help               Display help
+### Install via npx
 
-Examples:
-  $ npx @j0hanz/filesystem-mcp@latest /path/to/project
-  $ npx @j0hanz/filesystem-mcp@latest --allow-cwd
-  $ npx @j0hanz/filesystem-mcp@latest --port 3000 /path/to/project
+```bash
+npx -y @j0hanz/filesystem-mcp /path/to/allowed/dir
 ```
 
-## Client Configuration
-
-<details>
-<summary><b>Install in VS Code</b></summary>
+Or install globally:
 
-[![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": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
+```bash
+npm install -g @j0hanz/filesystem-mcp
+filesystem-mcp /path/to/allowed/dir
 ```
 
-Or install via CLI:
+### Install via Docker
 
-```sh
-code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
+```bash
+docker run -i --rm \
+  -v /path/to/project:/workspace:ro \
+  ghcr.io/j0hanz/filesystem-mcp:latest \
+  --read-only /workspace
 ```
 
-</details>
-
-<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&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)
+### Configure in VS Code
 
 Add to `.vscode/mcp.json`:
 
@@ -135,7 +94,7 @@ Add to `.vscode/mcp.json`:
   "servers": {
     "filesystem": {
       "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
     }
   }
 }
@@ -144,875 +103,411 @@ Add to `.vscode/mcp.json`:
 Or install via CLI:
 
 ```sh
-code-insiders --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
+code --add-mcp '{"name":"filesystem","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","/path/to/project"]}'
 ```
 
-</details>
-
-<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&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
-
-Add to `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><b>Install in Visual Studio</b></summary>
-
-[![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)
+### Configure in Visual Studio
 
-Add to `<SOLUTIONDIR>.mcp.json` or `%USERPROFILE%\.mcp.json`:
+Add to `.vs\mcp.json` in your solution directory, or `%USERPROFILE%\.mcp.json` for a global configuration:
 
 ```json
 {
   "servers": {
     "filesystem": {
       "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
     }
   }
 }
 ```
 
-</details>
+### Configure in Claude Desktop
 
-<details>
-<summary><b>Install in Goose</b></summary>
-
-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>
-
-<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&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovZmlsZXN5c3RlbS1tY3BAbGF0ZXN0Il19)
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
     }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><b>Install in Claude Desktop</b></summary>
+### Install in Cursor
 
-Add to `claude_desktop_config.json`:
+Add to `.cursor/mcp.json` in your project root (project-scoped), or `~/.cursor/mcp.json` for a global configuration:
 
 ```json
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
     }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><b>Install in Claude Code</b></summary>
+### Docker configuration
 
-```sh
-claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
-```
-
-Or add a project-scoped `.mcp.json`:
+VS Code (`.vscode/mcp.json`) and Visual Studio (`.vs\mcp.json`):
 
 ```json
 {
-  "mcpServers": {
+  "servers": {
     "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-v",
+        "/path/to/project:/workspace",
+        "ghcr.io/j0hanz/filesystem-mcp:latest",
+        "/workspace"
+      ]
     }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><b>Install in Windsurf</b></summary>
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
+Claude Desktop (`claude_desktop_config.json`) and Cursor (`mcp.json`):
 
 ```json
 {
   "mcpServers": {
     "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-v",
+        "/path/to/project:/workspace",
+        "ghcr.io/j0hanz/filesystem-mcp:latest",
+        "/workspace"
+      ]
     }
   }
 }
 ```
 
-</details>
-
-<details>
-<summary><b>Install in Amp</b></summary>
-
-```sh
-amp mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
-```
+> [!NOTE]
+> For least privilege, use both controls: `:ro` makes the container mount
+> read-only at the operating-system boundary, while the server's `--read-only`
+> flag removes mutating tools (`create`, `edit`, `move`, `delete`, `patch`,
+> `replace_text`) from `tools/list`.
 
-Or add to `settings.json`:
+## Usage
 
-```json
-{
-  "amp.mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
-```
+### Tools
 
-</details>
+All tools are scoped to the configured roots. Call `list_roots` first to discover what is allowed.
 
-<details>
-<summary><b>Install in Cline</b></summary>
+#### Navigate
 
-Add to `cline_mcp_settings.json`:
+| Tool         | Description                                                                            |
+| :----------- | :------------------------------------------------------------------------------------- |
+| `list_roots` | List allowed workspace roots. Call this first — all other tools scope to these.        |
+| `list`       | List directory contents. Returns entries (dirs-first, alphabetical) and an ASCII tree. |
+| `find_files` | Find files by glob pattern (e.g. `**/*.ts`). Returns matching files with metadata.     |
 
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
-```
+#### Inspect
 
-</details>
+| Tool          | Description                                                                               |
+| :------------ | :---------------------------------------------------------------------------------------- |
+| `stat`        | Get file/directory metadata: size, modified time, permissions, MIME type, token estimate. |
+| `search_text` | Search file contents for text (grep-like). Returns matching lines with context.           |
+| `diff`        | Compare two files and return a unified diff with added/removed line counts.               |
 
-<details>
-<summary><b>Install in Codex</b></summary>
+#### Read
 
-```sh
-codex mcp add filesystem -- npx -y @j0hanz/filesystem-mcp@latest
-```
+| Tool   | Description                                                                          |
+| :----- | :----------------------------------------------------------------------------------- |
+| `read` | Read a text file. Supports head/tail and line ranges. Accepts `paths[]` for batches. |
 
-Or add to `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project):
+#### Write
 
-```toml
-[mcp_servers.filesystem]
-command = "npx"
-args = ["-y", "@j0hanz/filesystem-mcp@latest"]
-```
+| Tool           | Description                                                                                       |
+| :------------- | :------------------------------------------------------------------------------------------------ |
+| `create`       | Create one or more files, overwriting existing content and creating parent directories as needed. |
+| `edit`         | Apply sequential literal string replacements to one or more files (max 5 per call).               |
+| `move`         | Move, rename, or copy (`copy: true`) one or more files/directories to explicit destinations.      |
+| `delete`       | Permanently delete one or more files or directories. This action is irreversible.                 |
+| `replace_text` | Bulk search-and-replace across files matching a glob pattern.                                     |
+| `patch`        | Apply a single-file unified diff and write the result.                                            |
 
-</details>
+### Resources
 
-<details>
-<summary><b>Install in GitHub Copilot Coding Agent</b></summary>
+| URI                             | Description                                                                           |
+| :------------------------------ | :------------------------------------------------------------------------------------ |
+| `internal://instructions`       | Server navigation guide — tools overview, constraints, and error recovery.            |
+| `filesystem-mcp://file/{+path}` | Read a workspace file. Subscribe to receive push notifications on change.             |
+| `filesystem-mcp://result/{id}`  | Ephemeral cached tool output. Expires after ~60 seconds, eviction, or server restart. |
 
-Add this JSON in your repository's GitHub Copilot coding agent MCP configuration:
+### Prompts
 
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "type": "local",
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
-      "tools": ["*"]
-    }
-  }
-}
-```
+| Prompt     | Description                                                           |
+| :--------- | :-------------------------------------------------------------------- |
+| `get-help` | Return usage instructions, optionally filtered to a specific section. |
 
-</details>
+## Project structure
 
-<details>
-<summary><b>Install in Warp</b></summary>
+```text
+filesystem-mcp/
+├── __tests__/        Test suites
+├── scripts/          Build and task utilities
+├── src/
+│   ├── core/         Path guarding, filesystem abstraction, concurrency, observability
+│   ├── tools/        Tool definitions and registration
+│   ├── index.ts      Process entrypoint and transport selection
+│   ├── server.ts     Server factory and registrar composition
+│   ├── transport/    stdio and Streamable HTTP transport setup
+│   ├── prompts.ts    Prompt definitions and registration
+│   └── resources.ts  Resource definitions and registration
+└── Dockerfile        Multi-stage alpine build, non-root user
+```
+
+Runtime composition flows from `src/index.ts` to `src/transport.ts`, then to
+`src/server.ts`, the registrars, and finally `src/core/`. Each registrar owns
+the narrow dependency contract it consumes.
+
+| Path                  | Purpose                                                        |
+| :-------------------- | :------------------------------------------------------------- |
+| `src/core/path.ts`    | `PathGuard` — validates every path against allowed roots       |
+| `src/core/fs.ts`      | `GuardedFileSystem` — guarded filesystem facade                |
+| `src/tools/define.ts` | Tool registration and execution framework                      |
+| `src/tools/batch.ts`  | Batch helpers (runOverPaths, normalizeBatchItems)              |
+| `src/server.ts`       | Builds shared dependencies and invokes the three registrars    |
+| `src/transport.ts`    | Owns stdio and Streamable HTTP setup around the server factory |
 
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
-```
+## Configuration
 
-</details>
+The server starts with allowed directories from explicit startup configuration:
 
-<details>
-<summary><b>Install in Kiro</b></summary>
+1. **Positional directories** passed to `filesystem-mcp`.
+2. **Environment variable** `FS_ALLOWED_DIRS` (separated by `:` on POSIX or `;` on Windows).
+3. **Current working directory** when `--allow-cwd` is enabled.
 
-Add to `.kiro/settings/mcp.json`:
+Legacy MCP connections may additionally seed roots through the deprecated
+`roots/list` flow. Modern 2026-07-28 connections do not automatically send
+workspace roots. They can add access after startup by calling a tool with a
+concrete path and approving the elicitation-backed grant. `list_roots` reports
+the roots already configured or accepted; it cannot discover an unknown
+workspace by itself.
 
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
-  }
-}
-```
+### Recommended global recipes
 
-</details>
+#### VS Code / Cursor / Claude Code (primary recipe)
 
-<details>
-<summary><b>Install in Gemini CLI</b></summary>
+Configure the project directory explicitly:
 
-Add to `~/.gemini/settings.json`:
+Add to your global or project-scoped configuration:
 
 ```json
 {
   "mcpServers": {
     "filesystem": {
       "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
+      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/project"]
     }
   }
 }
 ```
 
-</details>
+#### Claude Desktop (fallback recipe via environment variable)
 
-<details>
-<summary><b>Install in Zed</b></summary>
+Claude Desktop and similar clients don't support the MCP Roots protocol. Use the `FS_ALLOWED_DIRS` environment variable to configure allowed folders.
 
-Add to `~/.config/zed/settings.json`:
+Add to your `claude_desktop_config.json`:
 
 ```json
 {
-  "context_servers": {
+  "mcpServers": {
     "filesystem": {
       "command": "npx",
       "args": ["-y", "@j0hanz/filesystem-mcp@latest"],
-      "env": {}
+      "env": {
+        "FS_ALLOWED_DIRS": "/path/to/project1:/path/to/project2"
+      }
     }
   }
 }
 ```
 
-</details>
+_(On Windows, separate directories with a semicolon `;` instead of a colon `:`)._
 
-<details>
-<summary><b>Install in Augment</b></summary>
+### Advanced / per-project positional arguments
 
-Add to VS Code `settings.json` under `augment.advanced`:
+You can also restrict access to specific directories by passing positional arguments directly:
 
-```json
-{
-  "augment.advanced": {
-    "mcpServers": [
-      {
-        "id": "filesystem",
-        "command": "npx",
-        "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-      }
-    ]
-  }
-}
+```bash
+# Start with explicit positional paths
+filesystem-mcp /path/to/project1 /path/to/project2
 ```
 
-</details>
-
-<details>
-<summary><b>Install in Roo Code</b></summary>
+---
 
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
+### Configuration reference
+
+#### CLI flags
+
+| Flag                      | Default | Purpose                                                                            |
+| :------------------------ | :------ | :--------------------------------------------------------------------------------- |
+| `[dirs...]`               | —       | One or more allowed root directories (positional)                                  |
+| `--allow-cwd`             | `false` | Also allow the current working directory as a root                                 |
+| `--walk-cwd`              | `false` | Walk up from CWD to find a project root; implies `--allow-cwd`                     |
+| `--allow-missing-roots`   | `false` | Start even if configured allowed directories do not exist                          |
+| `--port <n>`              | —       | Enable Streamable HTTP transport on the given port (env: `FS_PORT`)                |
+| `--http-host <host>`      | —       | HTTP server bind address (env: `FS_HTTP_HOST`)                                     |
+| `--api-key <key>`         | —       | Require this API key on HTTP requests (env: `FS_API_KEY`)                          |
+| `--read-only`             | `false` | Disable write tools: `create`, `edit`, `delete`, `move`, `patch`, `replace_text`   |
+| `--safe`                  | `false` | Alias for `--read-only`                                                            |
+| `--deny <pattern>`        | —       | Block paths matching this pattern; repeatable                                      |
+| `--allow-sensitive`       | `false` | Allow access to sensitive system paths (env: `FS_ALLOW_SENSITIVE`)                 |
+| `--root-boundary <path>`  | —       | Require all allowed roots to fall under this path (env: `FS_ROOT_BOUNDARY`)        |
+| `--max-file-size <bytes>` | —       | Maximum file size for reads in bytes (env: `FS_MAX_FILE_SIZE`)                     |
+| `--log-level <level>`     | `info`  | RFC 5424 log level, `debug` through `emergency` (env: `FS_LOG_LEVEL`)              |
+| `--print-config`          | `false` | Print the active configuration and exit (use `--json` for machine-readable output) |
+| `--json`                  | `false` | Output `--print-config` as JSON                                                    |
+
+#### Environment variables
+
+All boolean variables accept `true` or `1` to enable and `false`, `0`, or
+unset to disable; any other value logs a warning and reads as disabled.
+Flags take precedence when both are set.
+
+| Variable                      | Purpose                                                                                                                                                                                                           |
+| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FS_ALLOWED_DIRS`             | Colon-separated (POSIX) or semicolon-separated (Windows) list of directories to allow.                                                                                                                            |
+| `FS_ROOT_BOUNDARY`            | Path prefix all allowed roots must fall under (mirrors `--root-boundary`).                                                                                                                                        |
+| `FS_ALLOW_CWD_WALK`           | Walk up from CWD to find a project root (mirrors `--walk-cwd`).                                                                                                                                                   |
+| `FS_ALLOW_MISSING_ROOTS`      | Start even if configured directories do not exist (mirrors `--allow-missing-roots`).                                                                                                                              |
+| `FS_ALLOW_SENSITIVE`          | Allow access to sensitive system paths (mirrors `--allow-sensitive`).                                                                                                                                             |
+| `FS_DENYLIST`                 | Comma-separated list of paths or patterns to block (mirrors `--deny`).                                                                                                                                            |
+| `FS_MAX_FILE_SIZE`            | Maximum file size for reads in bytes (mirrors `--max-file-size`).                                                                                                                                                 |
+| `FS_LOG_LEVEL`                | RFC 5424 log level: `debug`, `info`, `notice`, `warn`/`warning`, `error`, `critical`, `alert`, or `emergency` (mirrors `--log-level`).                                                                            |
+| `FS_PORT`                     | Start the Streamable HTTP transport on this port; unset = stdio (mirrors `--port`).                                                                                                                               |
+| `FS_HTTP_HOST`                | HTTP server bind address (mirrors `--http-host`).                                                                                                                                                                 |
+| `FS_API_KEY`                  | API key required on HTTP requests (mirrors `--api-key`).                                                                                                                                                          |
+| `FS_TRUST_PROXY`              | Express `trust proxy` setting: hop count or expression. Unset = do not trust `X-Forwarded-*`.                                                                                                                     |
+| `FS_ALLOWED_HOSTS`            | Comma-separated Host header values to accept (HTTP transport).                                                                                                                                                    |
+| `FS_ALLOWED_ORIGINS`          | Comma-separated origin hostnames for CORS.                                                                                                                                                                        |
+| `FS_ALLOW_UNRESTRICTED_HOSTS` | Bind a wildcard host with no Host validation (accepts the risk).                                                                                                                                                  |
+| `FS_PUBLIC_URL`               | Resource identifier URL for RFC 9728 discovery.                                                                                                                                                                   |
+| `FS_RATE_LIMIT_RPM`           | Per-client-IP requests/minute (default 120 with API-key authentication, 6,000 for keyless loopback; range 1–100000).                                                                                              |
+| `FS_MAX_REQUEST_BYTES`        | Max HTTP request body bytes (default 4194304, 1024–268435456).                                                                                                                                                    |
+| `FS_KEEPALIVE_TIMEOUT_MS`     | HTTP keep-alive timeout in ms; set above any fronting proxy's idle timeout (default 5000, 1000–600000).                                                                                                           |
+| `FS_MAX_WATCHERS`             | Max concurrent file watchers (default 256, 1–4096).                                                                                                                                                               |
+| `FS_MAX_INLINE_MATCHES`       | Max inline content matches per search (default 50, 1–10000).                                                                                                                                                      |
+| `FS_MAX_READ_MANY_BYTES`      | Max total bytes across a batched `read` (default 524288, 10240–104857600).                                                                                                                                        |
+| `FS_SEARCH_TIMEOUT_MS`        | Search timeout in ms (default 5000, 100–60000).                                                                                                                                                                   |
+| `NO_COLOR`                    | Any value disables ANSI color output.                                                                                                                                                                             |
+| `FS_REQUEST_STATE_KEY`        | HMAC key sealing `input_required` requestState across retry rounds. Optional for stdio and single-instance HTTP (random per boot if unset); mandatory and shared across every fleet instance (UTF-8, >=32 bytes). |
+
+#### Multi-instance HTTP deployments
+
+Each instance delivers `subscriptions/listen` change events
+(`resources/updated`, `tools/list_changed`, etc.) on an in-process bus by
+default. Behind a load balancer with more than one instance, a listener on
+instance A will not see an event published on instance B. Explicit fleet mode
+therefore refuses to boot without a shared event bus.
+
+To fan events out across instances, implement the SDK's `ServerEventBus`
+interface (two methods: `publish`/`subscribe`) over whatever pub/sub you
+already run, then pass it to filesystem-mcp's programmatic HTTP entry:
+
+```ts
+import type { ServerEvent, ServerEventBus } from '@modelcontextprotocol/server';
+
+import { startHttpServer } from '@j0hanz/filesystem-mcp/transport';
+import Redis from 'ioredis';
+
+// any pub/sub client works the same way
+
+class RedisServerEventBus implements ServerEventBus {
+  private readonly listeners = new Set<(event: ServerEvent) => void>();
+  private readonly pub = new Redis(process.env['REDIS_URL']);
+  private readonly sub = new Redis(process.env['REDIS_URL']);
+
+  constructor() {
+    void this.sub.subscribe('fs-mcp-events');
+    this.sub.on('message', (_channel, message) => {
+      const event = JSON.parse(message) as ServerEvent;
+      for (const listener of this.listeners) listener(event);
+    });
   }
-}
-```
 
-</details>
-
-<details>
-<summary><b>Install in Kilo Code</b></summary>
+  publish(event: ServerEvent): void {
+    void this.pub.publish('fs-mcp-events', JSON.stringify(event));
+  }
 
-```json
-{
-  "mcpServers": {
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@j0hanz/filesystem-mcp@latest"]
-    }
+  subscribe(listener: (event: ServerEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
   }
 }
-```
-
-</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`](#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`](#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`](#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`](#diff_files), [`apply_patch`](#apply_patch)
 
-### File Management
+const eventBus = new RedisServerEventBus();
+const apiKey = process.env['FS_API_KEY'];
+if (!apiKey) throw new Error('FS_API_KEY is required for a multi-instance HTTP deployment');
 
-Create directories, move/rename files, delete files, and verify file integrity via SHA-256 hashing.
-
-**Relevant tools:** [`mkdir`](#mkdir), [`mv`](#mv), [`rm`](#rm), [`calculate_hash`](#calculate_hash), [`write`](#write)
-
-## Architecture
-
-```text
-[MCP Client]
-    |
-    | Transport: stdio (default) or Node Streamable HTTP (--port)
-    v
-[MCP Server: filesystem-mcp]
-    | Entry: src/index.ts -> src/server/bootstrap.ts
-    |
-    +-- initialize / initialized
-    |
-    +-- tools/call ──────────────────────────────────────────
-    |   +-- [roots]             — List allowed workspace roots
-    |   +-- [ls]                — List directory contents
-    |   +-- [find]              — Find files by glob
-    |   +-- [tree]              — Render directory tree
-    |   +-- [read]              — Read file contents
-    |   +-- [read_many]         — Read multiple files
-    |   +-- [stat]              — Get file metadata
-    |   +-- [stat_many]         — Get multiple file metadata
-    |   +-- [grep]              — Search file contents
-    |   +-- [mkdir]             — Create directory
-    |   +-- [write]             — Write file
-    |   +-- [edit]              — Edit file (string replacements)
-    |   +-- [mv]                — Move/rename file
-    |   +-- [rm]                — Delete file
-    |   +-- [calculate_hash]    — SHA-256 hash
-    |   +-- [diff_files]        — Unified diff
-    |   +-- [apply_patch]       — Apply unified patch
-    |   +-- [search_and_replace]— Bulk search & replace
-    |
-    +-- resources/read ──────────────────────────────────────
-    |   +-- internal://instructions
-    |   +-- internal://tool-catalog
-    |   +-- internal://workflows
-    |   +-- internal://tool-info/{name}
-    |   +-- filesystem-mcp://result/{id}
-    |   +-- filesystem-mcp://metrics
-    |
-    +-- 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
-```
-
-### Request Lifecycle
-
-```text
-[Client] -- initialize {protocolVersion, capabilities} --> [Server]
-[Server] -- {protocolVersion, capabilities, serverInfo} --> [Client]
-[Client] -- notifications/initialized --> [Server]
-[Client] -- tools/call {name, arguments} --> [Server]
-[Server] -- validate(inputSchema) --> [Handler]
-[Handler] -- {content: [{type, text}], structuredContent?, isError?} --> [Client]
+await startHttpServer(
+  3000,
+  { cliAllowedDirs: ['/workspace'] },
+  { apiKey, eventBus, deploymentMode: 'fleet' },
+);
 ```
 
-## MCP Surface
-
-### 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.
-
-_No parameters._
-
----
-
-#### `ls`
-
-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-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                                  |
-
----
-
-#### `find`
-
-Find files by glob pattern. Returns matching files with metadata.
-
-| 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                                                            |
-
----
-
-#### `tree`
-
-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: 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` |
-
----
-
-#### `read`
-
-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)                               |
-| `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` |
-
----
-
-#### `read_many`
-
-Read multiple text files in one request.
-
-| Parameter   | Type     | Required | Description                     |
-| ----------- | -------- | -------- | ------------------------------- |
-| `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     |
-
----
-
-#### `stat`
-
-Get file/directory metadata: size, modified, permissions, mime, tokenEstimate.
-
-| Parameter | Type   | Required | Description                        |
-| --------- | ------ | -------- | ---------------------------------- |
-| `path`    | string | **yes**  | Absolute path to file or directory |
-
----
-
-#### `stat_many`
-
-Get metadata for multiple files/directories in one request.
-
-| Parameter | Type     | Required | Description                  |
-| --------- | -------- | -------- | ---------------------------- |
-| `paths`   | string[] | **yes**  | File/directory paths (1-100) |
-
----
-
-#### `grep`
-
-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 (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`                             |
-
----
-
-#### `mkdir`
+This project ships no bus adapter and no pub/sub dependency. A single
+in-process instance (the common case) needs nothing extra and is the CLI's
+default. Load-balanced deployments must use the programmatic API with
+`deploymentMode: 'fleet'`.
 
-Create a new directory (recursive). Idempotent.
+### Examples
 
-| Parameter | Type     | Required | Description                                                       |
-| --------- | -------- | -------- | ----------------------------------------------------------------- |
-| `path`    | string   | no       | Absolute path to directory to create                              |
-| `paths`   | string[] | no       | Multiple directories to create. Either `path` or `paths` required |
-
----
-
-#### `write`
-
-Write content to a file, **overwriting all existing content**. Creates parent directories if needed.
-
-| Parameter | Type   | Required | Description           |
-| --------- | ------ | -------- | --------------------- |
-| `path`    | string | **yes**  | Absolute path to file |
-| `content` | string | **yes**  | Content to write      |
-
----
-
-#### `edit`
-
-Apply sequential literal string replacements (first occurrence per edit). Use `dryRun` to preview.
-
-| Parameter          | Type    | Required | Description                                                |
-| ------------------ | ------- | -------- | ---------------------------------------------------------- |
-| `path`             | string  | **yes**  | Absolute path to file                                      |
-| `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` |
-
----
-
-#### `mv`
-
-Move or rename a file or directory.
-
-| Parameter     | Type     | Required | Description                                          |
-| ------------- | -------- | -------- | ---------------------------------------------------- |
-| `source`      | string   | no       | Single path to move (deprecated: use `sources`)      |
-| `sources`     | string[] | no       | Paths to move. Either `source` or `sources` required |
-| `destination` | string   | **yes**  | Destination path                                     |
-
----
-
-#### `rm`
-
-Permanently delete a file or directory. **Irreversible.**
-
-| Parameter           | Type    | Required | Description                                    |
-| ------------------- | ------- | -------- | ---------------------------------------------- |
-| `path`              | string  | **yes**  | Absolute path to file or directory             |
-| `recursive`         | boolean | no       | Delete non-empty directories. Default: `false` |
-| `ignoreIfNotExists` | boolean | no       | No error if missing. Default: `false`          |
-
----
-
-#### `calculate_hash`
-
-Calculate SHA-256 hash of a file or directory.
-
-| Parameter | Type   | Required | Description                        |
-| --------- | ------ | -------- | ---------------------------------- |
-| `path`    | string | **yes**  | Absolute path to file or directory |
-
----
-
-#### `diff_files`
-
-Generate a unified diff between two files. Output feeds directly into `apply_patch`.
-
-| Parameter          | Type    | Required | Description                                          |
-| ------------------ | ------- | -------- | ---------------------------------------------------- |
-| `original`         | string  | **yes**  | Path to original file                                |
-| `modified`         | string  | **yes**  | Path to modified file                                |
-| `context`          | integer | no       | Lines of context in diff output                      |
-| `ignoreWhitespace` | boolean | no       | Ignore leading/trailing whitespace. Default: `false` |
-| `stripTrailingCr`  | boolean | no       | Strip trailing carriage returns. Default: `false`    |
-
----
-
-#### `apply_patch`
-
-Apply a unified diff patch to one or more files. Single-file: throws on failure. Multi-file: best-effort per file with `results[]`. Workflow: `diff_files` -> `apply_patch(dryRun)` -> `apply_patch`.
-
-| Parameter                | Type    | Required | Description                                                |
-| ------------------------ | ------- | -------- | ---------------------------------------------------------- |
-| `path`                   | string  | **yes**  | Path to file (single) or base directory (multi-file patch) |
-| `patch`                  | string  | **yes**  | Unified diff with `@@` hunk headers (single or multi-file) |
-| `fuzzFactor`             | integer | no       | Max fuzzy mismatches per hunk (0-20)                       |
-| `autoConvertLineEndings` | boolean | no       | Auto-convert line endings. Default: `true`                 |
-| `dryRun`                 | boolean | no       | Validate without writing. Default: `false`                 |
-
----
-
-#### `search_and_replace`
-
-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  | 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
-
-| 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 |
-| `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
-
-| Capability    | Status    | Evidence                                                                   |
-| ------------- | --------- | -------------------------------------------------------------------------- |
-| `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` — 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
-
-| Annotation              | Tools                                                                                                           | Value                                  |
-| ----------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
-| `readOnlyHint: true`    | `roots`, `ls`, `find`, `tree`, `read`, `read_many`, `stat`, `stat_many`, `grep`, `calculate_hash`, `diff_files` | Read-only, idempotent, non-destructive |
-| `destructiveHint: true` | `write`, `edit`, `rm`, `mv`, `search_and_replace`, `apply_patch`                                                | Destructive writes, not idempotent     |
-| `idempotentHint: true`  | `mkdir`                                                                                                         | Idempotent write, non-destructive      |
-
-### Structured Output
-
-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
-
-### 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
+```bash
+# Allow current working directory
+filesystem-mcp --allow-cwd
 
-When started with `--port <number>`, the server exposes a single MCP endpoint:
+# HTTP transport on port 3000
+filesystem-mcp --port 3000
+```
 
-| Method   | Path   | Purpose                                               |
-| -------- | ------ | ----------------------------------------------------- |
-| `POST`   | `/mcp` | Initialize session or send requests (Streamable HTTP) |
-| `GET`    | `/mcp` | HTTP streaming session endpoint                       |
-| `DELETE` | `/mcp` | Terminate a session                                   |
+## Scripts
 
-**Required headers:**
+| Mode             | Command                          | Description                                          |
+| :--------------- | :------------------------------- | :--------------------------------------------------- |
+| Full check       | `node scripts/tasks.mjs`         | Run build, type check, lint, format, knip, and tests |
+| Auto-fix + check | `node scripts/tasks.mjs fix`     | Auto-fix formatting/linting and run the full check   |
+| Static only      | `node scripts/tasks.mjs --quick` | Run static analysis without tests                    |
+| Tests only       | `node scripts/tasks.mjs test`    | Run tests; accepts native `node --test` options      |
 
-- `mcp-protocol-version` — use the negotiated MCP protocol version on post-initialize HTTP requests
-- `mcp-session-id` — required for `GET`/`DELETE` (returned by `POST` on initialize)
+## Security
 
-**Authentication:** Requests to non-loopback HTTP binds require `FILESYSTEM_MCP_API_KEY`; clients must then send `Authorization: Bearer <key>`. Loopback-only binds may omit auth for local use. Uses SHA-256 timing-safe comparison.
+> [!IMPORTANT]
+> Report vulnerabilities privately via [GitHub Security Advisories](https://github.com/j0hanz/filesystem-mcp/security/advisories). Do not open public issues for security reports.
 
-**CORS:** Only localhost origins allowed (`127.0.0.1`, `::1`, `localhost`).
+| Topic           | Detail                                                                          |
+| :-------------- | :------------------------------------------------------------------------------ |
+| Path traversal  | Every path is resolved and validated against allowed roots before any operation |
+| Sensitive files | `.env`, `*.pem`, `*id_rsa*`, and similar patterns are denied by default         |
+| Regex safety    | RE2 cannot backtrack, so a hostile pattern cannot hang the server (ReDoS)       |
+| Container       | Runs as non-root `mcp` user; bind mounts control what is exposed                |
 
-**Host validation:** Loopback HTTP binds validate the `Host` header (`localhost`, `127.0.0.1`, `[::1]`) to reduce DNS rebinding risk. Non-loopback binds still require `FILESYSTEM_MCP_API_KEY`.
+## Contributing
 
-## Security
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feat/your-feature`.
+3. Commit your changes with a clear message.
+4. Run `node scripts/tasks.mjs` to confirm tests, types, lint, formatting, and knip all pass.
+5. Open a pull request.
 
-| Control                   | Status    | Evidence                                                                               |
-| ------------------------- | --------- | -------------------------------------------------------------------------------------- |
-| Path sandboxing           | confirmed | `src/lib/paths.ts` — all paths validated against allowed roots                         |
-| Traversal prevention      | confirmed | `src/lib/paths.ts` — resolved paths checked after normalization                        |
-| Symlink escape prevention | confirmed | `src/__tests__/security.test.ts` — symlink boundary enforcement                        |
-| Sensitive file denylist   | confirmed | `src/lib/constants.ts` — blocks `.git`, `.env*`, SSH keys, certs, secrets              |
-| Origin validation         | confirmed | `src/server/bootstrap.ts` — localhost-only Origin allowlist                            |
-| Bearer auth               | confirmed | `src/server/bootstrap.ts` — optional `FILESYSTEM_MCP_API_KEY` with timing-safe compare |
-| Input validation          | confirmed | `src/schemas.ts` — Zod strict schemas on all tool inputs                               |
-| 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
-- `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
-
-- **CI:** `.github/workflows/release.yml` — runs lint, type-check, test, build before tagging/publishing.
-- **Docker:** Multi-stage build with `node:24-alpine`. Builder compiles TypeScript + native modules (re2); release stage runs as non-root `mcp` user.
-- **npm:** `npm run prepublishOnly` runs lint + type-check + build.
-
-## Troubleshooting
-
-- **"No allowed directories"** — Pass at least one directory argument or use `--allow-cwd`.
-- **Sensitive file blocked** — Files matching the denylist (`.env*`, `.git`, SSH keys) are blocked by design. Check `src/lib/constants.ts` for the full list.
-- **Large result externalized** — When tool output exceeds inline limits, it's cached as a resource at `filesystem-mcp://result/{id}`. Read the resource URI to get the full content.
-- **Stdio: logs on stdout** — Keep logs on stderr only. The server uses `console.error` for diagnostics.
-- **HTTP 413** — Request body exceeds `FS_CONTEXT_MAX_REQUEST_BYTES`. Increase the limit or reduce payload size.
-- **HTTP 401** — `FILESYSTEM_MCP_API_KEY` is set but the request is missing or has an incorrect `Authorization: Bearer` header.
-
-## Credits
-
-| Dependency                                                                                 | Description                                   |
-| ------------------------------------------------------------------------------------------ | --------------------------------------------- |
-| [@modelcontextprotocol/server](https://www.npmjs.com/package/@modelcontextprotocol/server) | MCP server SDK package                        |
-| [@modelcontextprotocol/client](https://www.npmjs.com/package/@modelcontextprotocol/client) | MCP client SDK package                        |
-| [@modelcontextprotocol/node](https://www.npmjs.com/package/@modelcontextprotocol/node)     | Node transport package for MCP runtime        |
-| [commander](https://www.npmjs.com/package/commander)                                       | CLI argument parsing                          |
-| [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)              |
-| [zod](https://www.npmjs.com/package/zod)                                                   | Schema validation and JSON Schema generation  |
+[![Contributors](https://contrib.rocks/image?repo=j0hanz/filesystem-mcp)](https://github.com/j0hanz/filesystem-mcp/graphs/contributors)
 
 ## License
 
-MIT License. See [LICENSE](LICENSE) for details.
-
-[↑ Back to top](#table-of-contents)
+Released under the MIT License. See [LICENSE](LICENSE) for details.