{"_id":"@abhishekmcp/files","_rev":"2-0923f19b81e989e3eb6e7d4d5989a361","name":"@abhishekmcp/files","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@abhishekmcp/files","version":"0.1.0","keywords":["mcp","modelcontextprotocol","filesystem","files","claude"],"author":{"url":"https://github.com/Abhishekkumar2021","name":"Abhishek"},"license":"MIT","_id":"@abhishekmcp/files@0.1.0","maintainers":[{"name":"abhishek.opensource","email":"abhishek.opensource.dev@gmail.com"}],"homepage":"https://github.com/Abhishekkumar2021/mcp-suite/tree/main/servers/files#readme","bugs":{"url":"https://github.com/Abhishekkumar2021/mcp-suite/issues"},"bin":{"mcp-files":"dist/index.js"},"dist":{"shasum":"355e06cb06bf01d86c5651fee2f06d56ba578375","tarball":"https://registry.npmjs.org/@abhishekmcp/files/-/files-0.1.0.tgz","fileCount":26,"integrity":"sha512-3VS08L8oid1X353IVli1Jf7QfZnb/ijtlj65k2oXhBPaQxYT3RsbU7d4KPYal5+d6ABV5NhfgF9QkOufZDTOmQ==","signatures":[{"sig":"MEYCIQDBPRL9zLFu2e3+AR7zCuYNO8Jp1bkzxBm5UoPdfGZZtAIhAOwBEkw4+vUDPOsclvT+w7bVRUZd+JtgFNiYXX9lVo6c","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119415},"type":"module","engines":{"node":">=18"},"gitHead":"b85475a7b5468f2041c7cb301270da5e001f49b6","mcpName":"io.github.Abhishekkumar2021/files","scripts":{"dev":"tsc && node dist/index.js","build":"tsc","start":"node dist/index.js","watch":"tsc --watch","prepublishOnly":"npm run build"},"_npmUser":{"name":"abhishek.opensource","email":"abhishek.opensource.dev@gmail.com"},"repository":{"url":"git+https://github.com/Abhishekkumar2021/mcp-suite.git","type":"git","directory":"servers/files"},"_npmVersion":"11.17.0","description":"MCP server for the local filesystem — read, search, edit, copy, archive, and safely manage files within sandboxed roots, from any MCP client.","directories":{},"_nodeVersion":"24.13.0","dependencies":{"zod":"^3.23.8","diff":"^9.0.0","fflate":"^0.8.2","fast-glob":"^3.3.2","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public","provenance":true},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/files_0.1.0_1782629878582_0.966152330193937","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@abhishekmcp/files","version":"0.2.0","description":"MCP server for the local filesystem — read, search, edit, copy, archive, and safely manage files within sandboxed roots, from any MCP client.","mcpName":"io.github.Abhishekkumar2021/files","type":"module","bin":{"mcp-files":"dist/index.js"},"publishConfig":{"access":"public","provenance":true},"scripts":{"build":"tsc","watch":"tsc --watch","start":"node dist/index.js","dev":"tsc && node dist/index.js","test":"npm run build && node --test test/*.test.mjs","prepublishOnly":"npm run build"},"keywords":["mcp","modelcontextprotocol","filesystem","files","claude"],"author":{"name":"Abhishek","url":"https://github.com/Abhishekkumar2021"},"license":"MIT","homepage":"https://github.com/Abhishekkumar2021/mcp-suite/tree/main/servers/files#readme","repository":{"type":"git","url":"git+https://github.com/Abhishekkumar2021/mcp-suite.git","directory":"servers/files"},"bugs":{"url":"https://github.com/Abhishekkumar2021/mcp-suite/issues"},"engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","diff":"^9.0.0","fast-glob":"^3.3.2","fflate":"^0.8.2","ignore":"^7.0.5","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0"},"gitHead":"6e5fc28bf0ff99e6bbc343967538da474fd6ebc8","_id":"@abhishekmcp/files@0.2.0","_nodeVersion":"22.23.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-qHHEdq6uWH4+lYCvV4MD0evd7W75ZkBPCSI8csho/8lRpU/VCY4dhqmeyq5g1HyMF43UEFQMh/PUAZOwF+7Vow==","shasum":"8caf28993579119b0724b5ca50ab632c3c6bbc3c","tarball":"https://registry.npmjs.org/@abhishekmcp/files/-/files-0.2.0.tgz","fileCount":38,"unpackedSize":147020,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@abhishekmcp%2ffiles@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDyHBjIEtss++/m1YfhnsbgkHCdmdKD8vhUY7TNA+hAhgIgGZPIGcKDGJRiYeLpvk/dsZi2o5z/j2MujXJZvnLpVC8="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:b77b0e13-b1a3-410a-9488-63e6ff4ecd02"}},"directories":{},"maintainers":[{"name":"abhishek.opensource","email":"abhishek.opensource.dev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/files_0.2.0_1782635864734_0.8842115422932211"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-28T06:57:58.472Z","modified":"2026-06-28T08:37:45.196Z","0.1.0":"2026-06-28T06:57:58.710Z","0.2.0":"2026-06-28T08:37:44.876Z"},"bugs":{"url":"https://github.com/Abhishekkumar2021/mcp-suite/issues"},"author":{"name":"Abhishek","url":"https://github.com/Abhishekkumar2021"},"license":"MIT","homepage":"https://github.com/Abhishekkumar2021/mcp-suite/tree/main/servers/files#readme","keywords":["mcp","modelcontextprotocol","filesystem","files","claude"],"repository":{"type":"git","url":"git+https://github.com/Abhishekkumar2021/mcp-suite.git","directory":"servers/files"},"description":"MCP server for the local filesystem — read, search, edit, copy, archive, and safely manage files within sandboxed roots, from any MCP client.","maintainers":[{"name":"abhishek.opensource","email":"abhishek.opensource.dev@gmail.com"}],"readme":"# @abhishekmcp/files\n\nA robust, **sandboxed** filesystem [MCP](https://modelcontextprotocol.io) server. Gives any MCP client\n(Claude Desktop, Claude Code, Cursor, …) safe, capable access to files within directories you allow —\nread, search, edit, organize, archive — with a security-first design. Pure JavaScript, no native\ndependencies, no API keys.\n\n## Features\n\n### Read & navigate\n- `read_file` — read text with optional `head`/`tail` or a 1-based line window (pagination + truncation flag)\n- `read_media` — read images/audio/binary as base64 (returned as an image/audio block when possible)\n- `read_multiple` — batch-read several files\n- `stat` — metadata (type, size, timestamps, mode); does not follow a final symlink\n- `list_dir` — directory listing with type + size, sortable, paginated\n- `tree` — recursive directory tree (depth-capped)\n- `changed_since` — files modified after a timestamp (poll-based change detection)\n- `list_roots` — the allowed sandbox roots\n\n### Search\n- `find_files` — glob search (`**/*.ts`), excludes `node_modules`/`.git` by default\n- `search_content` — content grep (substring or regex) with context lines; skips binaries\n\n### Integrity\n- `file_hash` — sha256/sha1/md5 checksum\n- `find_duplicates` — duplicate files by size then sha256\n- `list_archive` — list a `.zip`'s contents without extracting\n\n### Edit & write (token-efficient)\n- `write_file` — create/overwrite (atomic; no-clobber unless `overwrite`)\n- `edit_file` — replace a **unique** `oldText` with `newText` (refuses ambiguous matches); `dryRun` shows a unified diff\n- `edit_lines` — replace a line range, optionally guarded by a content hash (`expectedHash`) to reject stale edits\n\n### Organize\n- `create_dir`, `move`, `copy` (recursive)\n- `delete` — **soft-delete to trash** (recoverable), `list_trash`, `restore`, `empty_trash`\n- `zip` / `unzip` — archives (zip-slip protected)\n\nEvery destructive tool supports `dryRun` to preview before committing.\n\n## Configuration\n\n| Variable | Required | Effect |\n|----------|----------|--------|\n| `FS_ROOTS` | **yes** | Allowed root directories, comma-separated. The server refuses to start without it. |\n| `FS_READONLY` | no | `1`/`true` registers only read tools (safe sharing). |\n| `FS_ALLOW_SECRETS` | no | `1`/`true` disables the secret denylist (see below). |\n| `FS_AUDIT_LOG` | no | Path to append a JSON-lines audit record of every mutation. |\n| `FS_OP_TIMEOUT_MS` | no | Per-operation timeout (default 30000). |\n| `FS_MAX_CONCURRENCY` | no | Max concurrent tool executions (default 8). |\n\n### Secret protection\nBy default the server **blocks reads of, and hides from discovery,** files that commonly hold secrets:\n`.env`, `*.pem`, `*.key`, `id_rsa*`, `.ssh/**`, `.aws/**`, `.npmrc`, `credentials`, and more. Add your\nown patterns in a per-root **`.mcpignore`** (gitignore syntax). Set `FS_ALLOW_SECRETS=1` to disable.\n\n### Production hardening\nEvery mutation is timestamped to `FS_AUDIT_LOG` (if set) and stderr. All ops run under a concurrency\nlimit + per-op timeout. Reads stream (head reads and hashing never load whole files), and edits\n**preserve line endings** (a CRLF file stays CRLF) and BOMs. The server ships with a committed\n`node:test` suite (unit tests for the sandbox + integration/security tests) run in CI.\n\n## Security\n\nThe whole design is sandbox-first:\n- Every path is confined to `FS_ROOTS`, checked **both lexically and via `realpath`** — a symlink inside\n  a root that points outside is rejected (on reads *and* writes).\n- Writes/edits/deletes refuse to act **through** a symlink; writes are atomic (temp + rename).\n- `unzip` is **zip-slip protected** (entries can't escape the destination).\n- Size limits on reads, depth/result caps on tree/search/copy, control-char/`..` rejection.\n- Deletes are **soft** (moved to `.mcp-trash`) and restorable.\n\n## Usage\n\n### Claude Code — plugin\n\n```\n/plugin marketplace add Abhishekkumar2021/mcp-suite\n/plugin install files\n```\n\n### Claude Code — manual\n\n```bash\nclaude mcp add files --env FS_ROOTS=$HOME/projects -- npx -y @abhishekmcp/files\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"files\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abhishekmcp/files\"],\n      \"env\": { \"FS_ROOTS\": \"/absolute/path/to/allow\" }\n    }\n  }\n}\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}