{"_id":"@adpharm/mcp-server-filesystem-ro","_rev":"2-f360ba2b6b7f0d30b360ead1822ffb46","name":"@adpharm/mcp-server-filesystem-ro","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.1":{"name":"@adpharm/mcp-server-filesystem-ro","version":"0.1.1","author":{"url":"fork of Model Context Protocol, a Series of LF Projects, LLC.","name":"The Adpharm"},"license":"SEE LICENSE IN LICENSE","_id":"@adpharm/mcp-server-filesystem-ro@0.1.1","maintainers":[{"name":"bentejas","email":"bentejas@hotmail.com"},{"name":"bh1","email":"bhonda89@gmail.com"}],"homepage":"https://github.com/adpharm/mcp-servers-fork/tree/main/src/filesystem","bugs":{"url":"https://github.com/adpharm/mcp-servers-fork/issues"},"bin":{"mcp-server-filesystem-ro":"dist/index.js"},"dist":{"shasum":"0064cc6ee44221bd7d2539c2c4535b7d0d179623","tarball":"https://registry.npmjs.org/@adpharm/mcp-server-filesystem-ro/-/mcp-server-filesystem-ro-0.1.1.tgz","fileCount":7,"integrity":"sha512-CPot6Yf18HQCkecOotrACiTiuhxdgW0MaVpVgL4P0987DBTIWgSB/ZB/s7f67V8bCnYscmrL8CX6Xvur1KyDUA==","signatures":[{"sig":"MEYCIQCNCqlICE9QLfgauni7DHJsKfOLluJiS5UZhIK5Fze3GwIhANKfEGB4kFSDluv5matQn8xfuBBHFlwQZFsqwkRZxyWo","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":69461},"type":"module","gitHead":"055b84ffd12b5c00164a94128a8205999fa2f92b","mcpName":"io.github.adpharm/mcp-server-filesystem-ro","scripts":{"test":"vitest run --coverage","build":"tsc && shx chmod +x dist/*.js","watch":"tsc --watch","prepare":"npm run build"},"_npmUser":{"name":"bh1","email":"bhonda89@gmail.com"},"repository":{"url":"git+https://github.com/adpharm/mcp-servers-fork.git","type":"git","directory":"src/filesystem"},"_npmVersion":"11.13.0","description":"Read-only MCP server for filesystem access (fork of @modelcontextprotocol/server-filesystem)","directories":{},"_nodeVersion":"24.16.0","dependencies":{"diff":"^8.0.3","glob":"^10.5.0","minimatch":"^10.0.1","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"shx":"^0.3.4","vitest":"^2.1.8","typescript":"^5.8.2","@types/diff":"^5.0.9","@types/node":"^22","@types/minimatch":"^5.1.2","@vitest/coverage-v8":"^2.1.8"},"upstreamVersion":"0.6.3","_npmOperationalInternal":{"tmp":"tmp/mcp-server-filesystem-ro_0.1.1_1780253809030_0.7705606513731476","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@adpharm/mcp-server-filesystem-ro","version":"0.1.2","upstreamVersion":"0.6.3","description":"Read-only MCP server for filesystem access (fork of @modelcontextprotocol/server-filesystem)","license":"SEE LICENSE IN LICENSE","mcpName":"io.github.adpharm/mcp-server-filesystem-ro","author":{"name":"The Adpharm","url":"fork of Model Context Protocol, a Series of LF Projects, LLC."},"homepage":"https://github.com/adpharm/mcp-servers-fork/tree/main/src/filesystem","bugs":{"url":"https://github.com/adpharm/mcp-servers-fork/issues"},"repository":{"type":"git","url":"git+https://github.com/adpharm/mcp-servers-fork.git","directory":"src/filesystem"},"type":"module","bin":{"mcp-server-filesystem-ro":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc && shx chmod +x dist/*.js","prepare":"npm run build","watch":"tsc --watch","test":"vitest run --coverage"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","diff":"^8.0.3","glob":"^10.5.0","minimatch":"^10.0.1"},"devDependencies":{"@types/diff":"^5.0.9","@types/minimatch":"^5.1.2","@types/node":"^22","@vitest/coverage-v8":"^2.1.8","shx":"^0.3.4","typescript":"^5.8.2","vitest":"^2.1.8"},"gitHead":"6b939a72e2b318743ba52c5260336b5f2d5a1ae5","_id":"@adpharm/mcp-server-filesystem-ro@0.1.2","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-A7Zco93o5DZM4UVxHFtr9R93/NlwZWZbu2kVLmmdb8uEM3kOV9M7ucKc1k2/HsOy6wyRFNzuK7Ia4Ft15AIy4w==","shasum":"68ced9b596e98c14304e517324d5a6ae3aeabfa6","tarball":"https://registry.npmjs.org/@adpharm/mcp-server-filesystem-ro/-/mcp-server-filesystem-ro-0.1.2.tgz","fileCount":7,"unpackedSize":66975,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBJ1l40WXQZ08yNGK5lqGDmPyTJl7qAaj3AkP7fQ9QPOAiALgESkHa6V35EX0eVDTN+Sp9A9qBYa1Ggzr5tf0rME1w=="}]},"_npmUser":{"name":"bh1","email":"bhonda89@gmail.com"},"directories":{},"maintainers":[{"name":"bentejas","email":"bentejas@hotmail.com"},{"name":"bh1","email":"bhonda89@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-filesystem-ro_0.1.2_1780254444268_0.8624596829941424"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-31T18:56:48.887Z","modified":"2026-05-31T19:07:24.553Z","0.1.1":"2026-05-31T18:56:49.167Z","0.1.2":"2026-05-31T19:07:24.422Z"},"bugs":{"url":"https://github.com/adpharm/mcp-servers-fork/issues"},"author":{"name":"The Adpharm","url":"fork of Model Context Protocol, a Series of LF Projects, LLC."},"license":"SEE LICENSE IN LICENSE","homepage":"https://github.com/adpharm/mcp-servers-fork/tree/main/src/filesystem","repository":{"type":"git","url":"git+https://github.com/adpharm/mcp-servers-fork.git","directory":"src/filesystem"},"description":"Read-only MCP server for filesystem access (fork of @modelcontextprotocol/server-filesystem)","maintainers":[{"name":"bentejas","email":"bentejas@hotmail.com"},{"name":"bh1","email":"bhonda89@gmail.com"}],"readme":"# Filesystem MCP Server (read-only)\n\n> **`@adpharm/mcp-server-filesystem-ro`** — a **read-only** fork of\n> [`@modelcontextprotocol/server-filesystem`](https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem),\n> maintained by [The Adpharm](https://github.com/adpharm/mcp-servers-fork).\n>\n> Only tools annotated `readOnlyHint: true` are exposed. The mutating tools `write_file`, `edit_file`,\n> `create_directory`, and `move_file` are **removed** and are not available in this build. Everything else below behaves\n> exactly like upstream. Install/run it as `mcp-server-filesystem-ro` (e.g.\n> `npx -y @adpharm/mcp-server-filesystem-ro /path/to/dir`).\n\nNode.js server implementing Model Context Protocol (MCP) for filesystem operations.\n\n## Features\n\n- Read files (text and media)\n- List directories / directory tree / file metadata\n- Search files\n- Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots)\n\n> ℹ️ **Read-only build:** writing, editing, creating directories, and moving/renaming are intentionally unavailable.\n\n## Directory Access Control\n\nThe server uses a flexible directory access control system. Directories can be specified via command-line arguments or dynamically via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots).\n\n### Method 1: Command-line Arguments\nSpecify Allowed directories when starting the server:\n```bash\nmcp-server-filesystem /path/to/dir1 /path/to/dir2\n```\n\n### Method 2: MCP Roots (Recommended)\nMCP clients that support [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the Allowed directories. \n\nRoots notified by Client to Server, completely replace any server-side Allowed directories when provided.\n\n**Important**: If server starts without command-line arguments AND client doesn't support roots protocol (or provides empty roots), the server will throw an error during initialization.\n\nThis is the recommended method, as this enables runtime directory updates via `roots/list_changed` notifications without server restart, providing a more flexible and modern integration experience.\n\n### How It Works\n\nThe server's directory access control follows this flow:\n\n1. **Server Startup**\n   - Server starts with directories from command-line arguments (if provided)\n   - If no arguments provided, server starts with empty allowed directories\n\n2. **Client Connection & Initialization**\n   - Client connects and sends `initialize` request with capabilities\n   - Server checks if client supports roots protocol (`capabilities.roots`)\n   \n3. **Roots Protocol Handling** (if client supports roots)\n   - **On initialization**: Server requests roots from client via `roots/list`\n   - Client responds with its configured roots\n   - Server replaces ALL allowed directories with client's roots\n   - **On runtime updates**: Client can send `notifications/roots/list_changed`\n   - Server requests updated roots and replaces allowed directories again\n\n4. **Fallback Behavior** (if client doesn't support roots)\n   - Server continues using command-line directories only\n   - No dynamic updates possible\n\n5. **Access Control**\n   - All filesystem operations are restricted to allowed directories\n   - Use `list_allowed_directories` tool to see current directories\n   - Server requires at least ONE allowed directory to operate\n\n**Note**: The server will only allow operations within directories specified either via `args` or via Roots.\n\n\n\n## API\n\n### Tools\n\n- **read_text_file**\n  - Read complete contents of a file as text\n  - Inputs:\n    - `path` (string)\n    - `head` (number, optional): First N lines\n    - `tail` (number, optional): Last N lines\n  - Always treats the file as UTF-8 text regardless of extension\n  - Cannot specify both `head` and `tail` simultaneously\n\n- **read_media_file**\n  - Read an image or audio file\n  - Inputs:\n    - `path` (string)\n  - Streams the file and returns base64 data with the corresponding MIME type\n\n- **read_multiple_files**\n  - Read multiple files simultaneously\n  - Input: `paths` (string[])\n  - Failed reads won't stop the entire operation\n\n- **list_directory**\n  - List directory contents with [FILE] or [DIR] prefixes\n  - Input: `path` (string)\n\n- **list_directory_with_sizes**\n  - List directory contents with [FILE] or [DIR] prefixes, including file sizes\n  - Inputs:\n    - `path` (string): Directory path to list\n    - `sortBy` (string, optional): Sort entries by \"name\" or \"size\" (default: \"name\")\n  - Returns detailed listing with file sizes and summary statistics\n  - Shows total files, directories, and combined size\n\n- **search_files**\n  - Recursively search for files/directories that match or do not match patterns\n  - Inputs:\n    - `path` (string): Starting directory\n    - `pattern` (string): Search pattern\n    - `excludePatterns` (string[]): Exclude any patterns.\n  - Glob-style pattern matching\n  - Returns full paths to matches\n\n- **directory_tree**\n  - Get recursive JSON tree structure of directory contents\n  - Inputs:\n    - `path` (string): Starting directory\n    - `excludePatterns` (string[]): Exclude any patterns. Glob formats are supported.\n  - Returns:\n    - JSON array where each entry contains:\n      - `name` (string): File/directory name\n      - `type` ('file'|'directory'): Entry type\n      - `children` (array): Present only for directories\n        - Empty array for empty directories\n        - Omitted for files\n  - Output is formatted with 2-space indentation for readability\n    \n- **get_file_info**\n  - Get detailed file/directory metadata\n  - Input: `path` (string)\n  - Returns:\n    - Size\n    - Creation time\n    - Modified time\n    - Access time\n    - Type (file/directory)\n    - Permissions\n\n- **list_allowed_directories**\n  - List all directories the server is allowed to access\n  - No input required\n  - Returns:\n    - Directories that this server can read/write from\n\n### Tool annotations (MCP hints)\n\nThis server sets [MCP ToolAnnotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#toolannotations)\non each tool. In this read-only build **every exposed tool is annotated `readOnlyHint: true`** — that annotation is\nexactly what the build uses to decide which tools to register, so any write-capable tool is filtered out before startup.\n\nThe mapping for the exposed tools is:\n\n| Tool                        | readOnlyHint | idempotentHint | destructiveHint | Notes      |\n|-----------------------------|--------------|----------------|-----------------|------------|\n| `read_text_file`            | `true`       | –              | –               | Pure read  |\n| `read_media_file`           | `true`       | –              | –               | Pure read  |\n| `read_multiple_files`       | `true`       | –              | –               | Pure read  |\n| `list_directory`            | `true`       | –              | –               | Pure read  |\n| `list_directory_with_sizes` | `true`       | –              | –               | Pure read  |\n| `directory_tree`            | `true`       | –              | –               | Pure read  |\n| `search_files`              | `true`       | –              | –               | Pure read  |\n| `get_file_info`             | `true`       | –              | –               | Pure read  |\n| `list_allowed_directories`  | `true`       | –              | –               | Pure read  |\n\n## Usage with Claude Desktop\nAdd this to your `claude_desktop_config.json`:\n\nNote: you can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server.\n\n### Docker\nNote: all directories must be mounted to `/projects` by default.\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"--mount\", \"type=bind,src=/Users/username/Desktop,dst=/projects/Desktop\",\n        \"--mount\", \"type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro\",\n        \"--mount\", \"type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt\",\n        \"mcp/filesystem\",\n        \"/projects\"\n      ]\n    }\n  }\n}\n```\n\n### NPX\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/Desktop\",\n        \"/path/to/other/allowed/dir\"\n      ]\n    }\n  }\n}\n```\n\nOn Windows, use `cmd /c` to launch `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"filesystem\": {\n      \"command\": \"cmd\",\n      \"args\": [\n        \"/c\",\n        \"npx\",\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"/Users/username/Desktop\",\n        \"/path/to/other/allowed/dir\"\n      ]\n    }\n  }\n}\n```\n\n## Usage with VS Code\n\nFor quick installation, click the installation buttons below...\n\n[![Install with NPX in VS Code](https://img.shields.io/badge/VS_Code-NPM-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%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D) [![Install with NPX in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-NPM-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%40modelcontextprotocol%2Fserver-filesystem%22%2C%22%24%7BworkspaceFolder%7D%22%5D%7D&quality=insiders)\n\n[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Docker-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Docker-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=filesystem&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22--mount%22%2C%22type%3Dbind%2Csrc%3D%24%7BworkspaceFolder%7D%2Cdst%3D%2Fprojects%2Fworkspace%22%2C%22mcp%2Ffilesystem%22%2C%22%2Fprojects%22%5D%7D&quality=insiders)\n\nFor manual installation, you can configure the MCP server using one of these methods:\n\n**Method 1: User Configuration (Recommended)**\nAdd the configuration to your user-level MCP configuration file. Open the Command Palette (`Ctrl + Shift + P`) and run `MCP: Open User Configuration`. This will open your user `mcp.json` file where you can add the server configuration.\n\n**Method 2: Workspace Configuration**\nAlternatively, you can add the configuration to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.\n\n> For more details about MCP configuration in VS Code, see the [official VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers).\n\nYou can provide sandboxed directories to the server by mounting them to `/projects`. Adding the `ro` flag will make the directory readonly by the server.\n\n### Docker\nNote: all directories must be mounted to `/projects` by default. \n\n```json\n{\n  \"servers\": {\n    \"filesystem\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\",\n        \"-i\",\n        \"--rm\",\n        \"--mount\", \"type=bind,src=${workspaceFolder},dst=/projects/workspace\",\n        \"mcp/filesystem\",\n        \"/projects\"\n      ]\n    }\n  }\n}\n```\n\n### NPX\n\n```json\n{\n  \"servers\": {\n    \"filesystem\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"${workspaceFolder}\"\n      ]\n    }\n  }\n}\n```\n\nOn Windows, use:\n\n```json\n{\n  \"servers\": {\n    \"filesystem\": {\n      \"command\": \"cmd\",\n      \"args\": [\n        \"/c\",\n        \"npx\",\n        \"-y\",\n        \"@modelcontextprotocol/server-filesystem\",\n        \"${workspaceFolder}\"\n      ]\n    }\n  }\n}\n```\n\n## Build\n\nDocker build:\n\n```bash\ndocker build -t mcp/filesystem -f src/filesystem/Dockerfile .\n```\n\n## License\n\nThis MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.\n","readmeFilename":"README.md"}