srcbridge

A sandboxed file-access MCP server for Claude Desktop. Deliberately not shaped like the official filesystem server: different tool names, a different contract, and a strong bias toward failing loudly instead of returning something that merely looks complete.

MCP (Model Context Protocol) is how Claude Desktop reaches local tools. This server is the piece that gives Claude read and write access to a set of directories you choose, and nothing outside them.

Node-only, ESM, no build step. Three dependencies (@modelcontextprotocol/sdk, isomorphic-git, diff) and zero shell execution.

Why this exists

It started as a replacement when the official @modelcontextprotocol/server-filesystem stopped working client-side, but the reason it stayed is different: an LLM working through a file API cannot tell a truncated answer from a complete one, and cannot tell "no matches" from "never searched". Every design decision here follows from that.

The full reasoning for each version lives in CHANGELOG.md; each entry records the real incident that prompted it.

Related MCP server: vulcan-file-ops

What you get that a thin fs wrapper does not

• An undo for every destructive write. The previous version is snapshotted first, and a snapshot failure aborts the write -- a write with no undo is worse than a failed write.

• Writes verified against the disk. Atomic temp + rename, then the content is hashed back off disk and the sha1 reported, so a timed-out call can be told apart from a lost one.

• Announced limits. Truncation, hit caps, skipped directories, binary and non-UTF-8 files are all reported -- so an empty result can be distinguished from an unsearched one.

• All-or-nothing multi-point edits. edit_batch validates every anchor in memory before anything is written, and rolls back if a write fails partway.

• Anchor mismatches that explain themselves. A failed edit names the diverging character and its code point rather than just saying "not found".

• Word documents as text. .docx becomes Markdown with tables and list numbering intact, plus a heading outline and a document-aware grep.

• Legacy encodings refused, not mangled. A Big5/GBK file is reported as such instead of being returned as mojibake and written back corrupted.

• Read-only git. Status, diff and history, with no write path anywhere in the codebase.

• Secret-like files are refused, not served. .env, private keys, keystores and credential stores never enter the model's context on any read, edit, overwrite, diff or history path; grep skips them and says how many. Template files (.env.example and friends) stay readable.

Design rules

These are the contract. They are repeated at the top of server.mjs and are the thing to check any change against.

1. Zero shell execution. node:fs plus pure-JS libraries only.

2. Every path resolves inside a root given on argv. No escapes.

3. Never let a partial result look complete. All truncation, capping and skipping is announced in the output.

4. Writes are atomic (temp + rename, file mode preserved) and verified by hashing the content back off disk.

5. Git is read-only. Status, diff and log. No commit/add/push code path exists, and none will.

6. Never hard-delete a user's file. The server may garbage-collect its own artifacts (expired auto-snapshots, stale temp files); nothing else.

Install

git clone https://github.com/kerwinkao/srcbridge.git
cd srcbridge
npm install

Then add it to claude_desktop_config.json and restart Claude Desktop. Every argument after the script path is an allowed root:

"srcbridge": {
  "command": "node",
  "args": [
    "C:\\path\\to\\srcbridge\\server.mjs",
    "C:\\projects",
    "\\\\wsl$\\Ubuntu\\home\\<user>"
  ]
}

Roots may live on different volumes; cross-volume moves fall back to copy + verify + source-to-trash rather than failing with EXDEV.

Optional environment variables:

• SRCBRIDGE_SKIP_DIRS=dirA,dirB — additional directory names to skip during recursive walks, on top of node_modules, .git, .srcbridge-trash, dist, build, .expo, coverage, android, ios.

• SRCBRIDGE_SECRET_GLOBS=a,b — additional basename globs (* only) treated as secret-like, on top of .env, .env.*, *.pem, *.key, *.p12, *.pfx, *.jks, *.keystore, *.ppk, id_rsa*, id_dsa*, id_ecdsa*, id_ed25519*, *.secret, secrets.json/.yaml/.yml, credentials.json, .netrc, .pgpass, .git-credentials, .npmrc, .htpasswd. Basenames ending in .example, .sample, .template or .dist are never treated as secret.

• SRCBRIDGE_ALLOW_SECRETS=1 — disables the secret guard for the whole server. The startup banner prints SECRET GUARD OFF while this is set.

Tools

Read — read_source, read_sources, read_bytes, list_entries, tree_view, stat_source, list_workspaces

Search — find_sources (paths), grep_sources (contents), grep_identifier (one concept across camelCase / PascalCase / snake_case / SCREAMING_SNAKE / kebab-case), grep_document (inside .docx)

Write — write_source, write_bytes, edit_source, edit_batch, edit_all (replace every occurrence in one file, but only when the count you declare is the count the file has), move_lines (cut a line range out of one file into another, byte-for-byte, optionally indented on the way; the primitive a module split needs), make_folder, move_source, discard_source

Word documents — read_document (.docx/.dotx → Markdown, with outline=true for a heading index), grep_document

Git (read-only) — diff_changes (workdir vs HEAD, or any from..to commit pair), log_changes, read_source_at (file content at any commit)

Housekeeping — trash_status

Auditing & counting — checksum_sources (one-call sha1 manifest of a directory), count_source (exact CJK/word/char statistics for manuscript length governance)

Each tool's own description carries its traps inline, because a tool description is re-injected into the model's context every turn while a protocol document read mid-session is not.

Operating notes

Things that have actually caused wrong conclusions, in rough order of how often:

• An empty search result is not proof of absence. Read the scanned N line and every announced cap before concluding anything. (Until v1.8.0 a root that was a file or did not exist returned scanned 0 and no hits — indistinguishable from a real miss. A file root now searches that file and says so; a missing root is an error.)

• When an edit anchor fails to match, suspect your own string first. Since v1.4.0 the mismatch error carries a DIAGNOSIS block naming the diverging character and its code point. Never \u-escape CJK on the way in — type the characters directly and copy them verbatim out of read_source. Escapes are for genuinely invisible characters only (zero-width, variation selectors, NBSP).

• replace has no guard that find has. A mistyped anchor fails loudly; a mistyped replacement lands silently. Since v1.5.0 every applied edit echoes the landed text back with the changed lines marked — that echo is the only thing standing between a typo and the disk. Since v1.13.0 it also names every CJK character the file did not contain before the edit, with the nearest one it does contain (a miscounted \u code point lands a few positions from the intended character, which is almost always already in the file). Read it.

• A timed-out call tells you nothing about whether the write happened. Use stat_source(sha1=true) and compare against the sha1 the write reported. Re-running blindly is how a half-applied state gets created.

• Use edit_batch whenever edits are linked. Validation runs fully in memory first; any miss aborts with the edit number named and nothing written.

• Use find_to for long stretches instead of pasting thousands of characters into find. Two short anchors, and preview reports the span size before you commit to it.

Undo

Every destructive write snapshots the previous version into <root>/.srcbridge-trash/autosnap/ first; a snapshot failure aborts the write, because a write with no undo is worse than a failed write. The newest 5 snapshots per file are kept and older ones garbage-collected.

discard_source is a soft delete into <root>/.srcbridge-trash/ and is never pruned. trash_status reports usage per root. Restoring anything is just move_source.

Development

node selftest.mjs

The selftest drives every tool in-process against a sandbox root — no MCP transport, no Claude Desktop restart per change. The assertion count is deliberately not written down anywhere; the criterion is "run it and see all green".

After changing server.mjs, office.mjs or selftest.mjs, all three steps are required: run the selftest green → restart Claude Desktop → let the client reload the tool definitions. Skipping any one of them means you are testing something other than what is running.

Fixtures under __selftest/ encode line endings, BOMs and legacy encodings on purpose. .gitattributes disables all text conversion for that reason — do not "fix" a fixture that looks malformed.

Structure (v1.11.0)

server.mjs          VERSION, tool registry, dispatcher, MCP main (~200 lines)
lib/core.mjs        limits, sandbox roots, secret guard, fidelity gates,
                    verified atomic writes + undo, path policy, defineTools
lib/editengine.mjs  anchor diagnosis / locate / span / echo, matchers (pure)
lib/scan.mjs        recursive walk, announced skips, the shared text scan
lib/gitro.mjs       read-only git helpers
tools/*.mjs         one module per tool group (read, docs, write, fs,
                    search, git, audit); each exports defineTools(defs, runs)
office.mjs          .docx parsing
selftest.mjs        the in-process runner (see above)

The shape that matters:

• A tool module holds defs (what the model sees: name, description, input schema, and a paths declaration naming every parameter that is a path and with what intent — read / edit / overwrite / diff / history / path; ? optional, [] list) next to runs (one handler per tool, (args, pth) => string). defineTools joins them by name and throws on any mismatch when the module loads.

• The dispatcher in server.mjs resolves every declared path into the sandbox and applies the secret guard for its intent BEFORE a handler runs. pth is what the handler receives. Handlers never resolve or guard a path themselves; if you find one that does, that is a bug, not a style choice.

• Cross-module checks at load: no duplicate tool names, every paths entry is well-formed and present in its schema, and every schema property that is a path by name is declared. All import-time errors, so node selftest.mjs dies on its import line rather than the Desktop failing later.

• Adding a tool = one entry in defs, one in runs, in the module it belongs to. Nothing in server.mjs changes.

The split itself was done with move_lines (v1.10.0) — no line was re-typed — and the selftest did not change. Before splitting selftest.mjs, add a --only <section> filter to the runner; that removes the actual pain without creating a second harness.

Versioning

CHANGELOG.md is the version history and the record of design decisions, including the ones that were deliberately not taken. It starts at v1.0.0; the v0.x series was a single day of unstable design and its load-bearing reasoning lives in code comments instead.