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: MCP File Operations Server

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.

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 variable:

• 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.

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, 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. grep_sources takes a directory as root; pointing it at a single file returns scanned 0 text files and no hits, which looks identical to "this string does not exist". Read the scanned N line first. The same applies under any announced cap.

• 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. 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.

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.