Bifrost

MCP-Bifrost

Rewrite 200 methods with a cheap model, without a single line of the result passing through the expensive one's context — and without writing anything to disk that does not compile.

tests license python targets

An MCP server that takes code work already analysed and split up by an orchestrating model, extracts the exact target block with the language's own parser, delegates the rewriting to a cheaper worker model, validates the result, applies it atomically, and records the whole thing outside the orchestrator's context.

The head decides. The muscle types. Bifrost is the nerve between them — and the part that guarantees nothing reaches disk broken.

In the examples below the head is Claude and the muscle is DeepSeek, which is simply the model that was to hand. Neither is a requirement. See The worker for why a 7B model on your own machine may be the more interesting choice.

---

Why

A large codebase edited by an LLM has one real bottleneck, and it is not intelligence: it is context. Reading a 4,600-line file to change thirty lines of it burns the orchestrator's window on text it will never use again.

Bifrost's premise is that the mechanical half of coding — writing the replacement text — does not need the expensive model, and does not need to pass through its context at all.

	Orchestrator does it all	Via Bifrost
202 methods × ~800 tok	~161,000 tok — exceeds a context window	~15,000 tok

The honest version (see RF-4): for a single small edit the saving is real but modest, because the orchestrator usually had to read the code anyway to say what it wanted. The order-of-magnitude win is in volume — transformations across many symbols where the instruction can be written without reading anything.

That is the use case this is built for. Not "fix this bug."

---

When not to use it

• Exploratory work. "Find why this crashes" is not an instruction Bifrost can execute. It needs to know the symbols before it starts.
• Single small edits. The token arithmetic is marginal, and we say so (RF-4). Use your agent's normal edit tool.
• Latency-sensitive loops. ~2.6 s per block, measured against DeepSeek.
• Anything that is not PHP or Python. Adding a language means writing a parser adapter, not rewriting the core — but it is not there today.
• Cross-file refactors where one edit's shape depends on another's outcome. patch_group gives atomicity, not sequencing.
• Codebases with no way of telling you something broke. Every gate here checks form; none understands meaning.

How this sits next to Aider, Serena and fast-apply models — including where they are better — is in docs/comparison.md.

---

How it works

you ──▶ Claude Code ──▶ MCP-Bifrost ──▶ worker model
         analyses,        parses,          writes one
         splits work      validates,       isolated block
                          applies, logs
                              │
                              ├──▶ source file (atomic splice)
                              └──▶ .bifrost/history.db

The orchestrator decides what and how. The worker decides nothing. The server is the only component allowed to touch disk, and it refuses until every gate passes.

Validation gates

Gate	Checks	Default
0 — offsets	the block on disk is byte-identical to what we sent the worker	on
1 — syntax	the rebuilt file passes php -l / ast.parse()	on
2 — one symbol	the returned block defines exactly one symbol	on
3 — substance	no call, variable or control keyword vanished silently	off

Three are on by default, not four. The substance gate is a coarse regex check that never fired during calibration, and a gate that rejects good patches is worse than one waiting to be armed. Enable it with substance_gate=True before bulk work.

A "perimeter check" comparing bytes outside the target range was specified, built, and then deleted: the server rebuilds the file as original[:start] + block + original[end:], so the perimeter is preserved by construction and the check can never fail. Calibration confirmed it — the gate reported 9/9 while three files were left syntactically broken. See RF-1.

Rollback

Git is already a content-addressed database, so it is used as one. git hash-object -w before each patch yields a blob SHA that goes in the log; reverting is git cat-file blob. Deduplicated and compressed for free, works with a dirty working tree, and there is no bespoke snapshot format to maintain.

---

The worker

DeepSeek is what was to hand, and every number in this repository was measured against it. It is not a requirement, and it is probably not the most interesting way to run this.

The worker's job is deliberately narrow. It receives one isolated block and one instruction, and returns one block. It does not choose files, plan changes, decide what to edit, or see anything else in the codebase. That is a task a 7B coding model can do — and the gates exist precisely so a weak worker's mistakes are caught before they reach disk rather than after.

Which makes the local case the more compelling one:

• Your code never leaves the machine. For a proprietary codebase that is not a preference, it is a precondition.
• Cost goes to zero on exactly the workload this is built for, where hundreds of blocks in one run is normal rather than extreme.
• The context requirement is tiny. One method, not one file. An 8k window is plenty; the whole design is that the worker never sees more than it needs.
• A weak worker is an acceptable worker when every output is parsed, syntax-checked and diffed before it counts for anything. A bad block costs a retry, not a corrupted file.

That last one is the real argument. Delegating code generation to a small local model is normally a bad idea because you cannot trust the output and checking it by hand costs more than writing it. Bifrost's answer is that the checking is mechanical, and the machine can do it.

Any OpenAI-compatible endpoint works — Ollama, llama.cpp's server, LM Studio, vLLM:

"env": {
  "BIFROST_WORKER_BASE_URL": "http://localhost:11434/v1",
  "BIFROST_WORKER_MODEL": "qwen2.5-coder:7b"
}

No key is needed when the endpoint is not the default one.

Worker compatibility

No local model has been measured yet. The endpoint is configurable and the protocol is a plain OpenAI-compatible chat completion, but this repository does not publish claims it has not measured — and that includes claims in its own favour.

The instrument exists. Point it at your endpoint:

BIFROST_TARGET=/path/to/your/codebase \
BIFROST_WORKER_BASE_URL=http://localhost:11434/v1 \
BIFROST_WORKER_MODEL=your-model \
python3 calibratge/calibra.py --cases 9

Worker	Valid JSON	Byte-identical (identity task)	No lines lost	Unfenced	Latency
DeepSeek (deepseek-chat, API)	9/9	3/3	3/3	9/9	2.6 s
your model here

If you run it, open a PR with the row. Numbers that make a model look bad are as useful as numbers that make it look good — the table exists to say which workers this actually works with, not to advertise.

One thing to expect. DeepSeek returned zero of nine responses wrapped in markdown fences. Smaller models fence almost everything, and that is a parsing problem rather than a capability one. Bifrost already strips fences; if your model is otherwise sound but still fails on them, report it as a bug here rather than as a mark against the model.

---

What leaves the machine

The unit of work sent to a worker is one parsed block — a single method — and never the file it came from. That is a consequence of the design rather than a feature added to it: if the replacement code does not pass through the orchestrator's context, it does not pass through anywhere else either.

What it does not mean. The block does leave, in the clear, to whatever endpoint you configured. So does the instruction, which may itself describe internal architecture.

What already guards it. Heimdall runs before the send, not before the write. Where a secret is a self-contained token it is swapped for a placeholder, the worker transforms the code around it, and the original goes back before the file is written — every placeholder must return exactly once or nothing is written at all. What cannot be safely redacted blocks the send outright. Measured false-positive rate on a real codebase: 2 findings across 1,291 symbols, both correct refusals of code that manipulates keys rather than holding one.

If your constraint is that nothing may leave at all, the answer is a local worker, not a smaller payload.

Designed, not built

Two additions would close most of the remaining gap. Neither exists yet, and they are named here rather than hidden in an issue because the design is the interesting part:

• Egress log. The log records the size of what was sent, not the bytes. Recording them alongside what came back is nearly free, and it turns "trust us" into "audit it".
• Comment and literal redaction. Heimdall redacts things shaped like secrets. The parser already produces the tree, so comments and string literals — often the highest-risk payload and frequently irrelevant to the transformation — could be replaced with opaque markers and restored on return.

The obvious objection to the second is that quality may suffer when the worker cannot see the names. That is a measurable question, not an argument: nine cases with redaction, nine without, calibratge/calibra.py. Whichever way it comes out gets published.

---

Quick start

Python 3.11+. No runtime dependencies — the server runs on the standard library, and each language is parsed by its own official tooling (php as an external binary, ast from the stdlib).

pipx install mcp-bifrost      # or: uv tool install mcp-bifrost

Add it to .mcp.json in the project you want to patch:

{
  "mcpServers": {
    "bifrost": {
      "command": "mcp-bifrost",
      "env": { "BIFROST_DB": ".bifrost/history.db" }
    }
  }
}

Or from source, without installing:

git clone https://github.com/FixemBCN/MCP-Bifrost.git
cd MCP-Bifrost
python3 -m unittest discover tests    # 128 tests, ~15s
python3 -m mcp_bifrost.server         # same server, PYTHONPATH=.

The key does not go in that file. Put it in .bifrost.env at your project root, which the server reads when the environment does not carry it:

echo "DEEPSEEK_API_KEY=sk-..." > .bifrost.env
chmod 600 .bifrost.env
echo ".bifrost.env" >> .gitignore

Or skip the key entirely and point BIFROST_WORKER_BASE_URL at a local model. Full instructions, and what to do before pointing this at anything that matters, are in the manual.

Tools

Tool	What it does
fix_symbols	one instruction across many symbols — the main one
fix_symbol / fix_range	rewrite one symbol, or an explicit line range
insert_symbol / insert_case	add a method, or a branch to a switch router
create_file	write a new file, optionally by analogy with an existing one
patch_group	several operations as one transaction
export_docs / publish_session	changelog from the log; batch onto a reviewable branch
revert_patch / revert_session	undo one patch, or the whole batch

---

Calibration

Before writing a line of the server, one question had to be answered:

Given a real method from a real codebase, packed with the compact schema, does the worker return code that can be applied without breaking anything?

The harness in calibratge/ answers it. Zero dependencies — Python stdlib plus the php binary.

export BIFROST_TARGET=/path/to/your/codebase
python3 calibratge/calibra.py --dry-run    # show cases, no API calls
export DEEPSEEK_API_KEY=...
python3 calibratge/calibra.py --cases 9

Result: the premise holds. 9/9 valid JSON, 3/3 byte-identical on the identity task, 3/3 with no original lines lost, 0/9 wrapped in markdown fences, 2.6 s average latency.

It also caught a byte-offset bug that had nothing to do with the worker and would have corrupted files silently in production. Full write-up: docs/calibration.md.

---

Repository layout

Path	What
mcp_bifrost/	the server
docs/	manual, architecture, critical review, calibration, comparison, licensing
tests/	128 tests
brainstorm/	the working record — how each decision was reached, including the reversed ones
calibratge/	the measurement harness

---

Behind the code

To be completely transparent: not a single line of this codebase was written by hand. It was conceptualised, challenged, implemented, tested and documented through a human-directed AI process. Here is what that actually meant, as precisely as it can be stated.

Human — problem, decisions, direction. I brought the initial specification and made every product decision: which worker model, which languages, what to cut, what to build next, the licence, the naming, when to stop. Several reversed earlier ones — the licence started as a no-resale source-available one and ended up Apache-2.0 once I decided reach mattered more than control. I also decided what the system must refuse to do, which turned out to be the more consequential half.

Claude Opus — adversarial design. Before implementation, Claude reviewed the specification as an outsider looking for reasons it would fail, and produced twelve findings. Two killed design elements I had approved: the central "perimeter check" the spec relied on turned out to be incapable of failing, and the project's stated justification — token savings — was shown to be marginal for single edits and only decisive in bulk. Both are preserved, unedited, in brainstorm/.

Measurement before code. Rather than trusting the design, a calibration harness was built first and run against the real worker on real code. It failed 6 of 9 cases — none of them the worker's fault. The cause was a byte-offset bug that would have silently corrupted any file containing an accented character. It also refuted two of Claude's own review findings. Those corrections sit above the original claims rather than replacing them.

Claude Opus — the core; delegated models — the periphery. Claude wrote the parsing, patching, validation gates, secret handling and engine directly. Two peripheral modules and the entire test suite were delegated to smaller models (Haiku and Sonnet) running as subagents. The split was deliberate rather than economical: a model starting cold on the patching code would very plausibly have reintroduced the byte-offset bug, because the natural way to write that code is the wrong way.

The delegated models found four real bugs in code Claude had written, including one that detached a docblock from the method it documented and one where nested switch statements silently dropped branches. Both passed every validation gate. Adversarial review by a model with no stake in the code was the only thing that caught them.

Human — review and acceptance. I directed the sequence, inspected results, challenged claims, and decided what stayed. Claude executed the validation and calibration runs; I read what came back and decided what it meant.

What this process did not provide

No human has read all ~7,400 lines of this repository — roughly 4,100 of server, 2,700 of tests and 600 of measurement harness — line by line. The confidence here comes from tests checked against deliberately broken code, from measurements against a real codebase, and from a design that refuses to write anything it cannot verify — not from manual audit.

If that is not the kind of confidence you want in a tool that edits your source files, that is a reasonable position, and the responsibility section is specific about what the gates do and do not catch.

Why this is in the README

Bifrost is a demonstration of its own premise. The valuable human contribution was not typing the code: it was defining the problem, controlling the context, challenging the output, and insisting on enough validation that generated code could be trusted at all.

The repository deliberately keeps the reasoning, the rejected ideas, the adversarial review and the measurements — including the parts where the AI was wrong and said so.

---

Documentation

Document	What it is
Manual	what it is, what it can do, how to install it, and what you are responsible for
Architecture	what gets built and why
Critical review	a fresh-eyes pass hunting for reasons this fails — twelve findings, two later refuted by measurement
Calibration results	what the worker actually did when asked
Comparison	how this sits next to Aider, Serena and fast-apply — and where they win
Licensing	what we consume, what we grant

brainstorm/ holds the working record: the original spec, the design journal across five revisions, the adversarial review, and the calibration results. docs/ is the reference and wins where the two differ.

---

Responsibility

This tool edits your source files automatically using a language model. Apache 2.0 means it is provided as is, without warranty: you are responsible for what it does to your code. Read the diffs, run your tests, deploy on purpose. The manual is specific about what the gates do and do not catch.

Contributing

Contributions of every kind are welcome — including an argument that something here is wrong. This project has already deleted one validation gate for being tautological and refuted two of its own claims with measurement.

One convention, and it is the one that matters: every test must be able to fail. Details in the manual.

License

Apache License 2.0.

Built on the Model Context Protocol, MIT-licensed by Anthropic, PBC. MCP-Bifrost is an independent project and is not affiliated with, endorsed by, or sponsored by Anthropic, PBC.