MCP-Bifrost

<!-- mcp-name: io.github.FixemBCN/mcp-bifrost -->

<picture>
  <source media="(prefers-color-scheme: dark)"
          srcset="https://raw.githubusercontent.com/FixemBCN/MCP-Bifrost/main/assets/Bifrost_Logo_DarkBackground.png">
  <img src="https://raw.githubusercontent.com/FixemBCN/MCP-Bifrost/main/assets/Bifrost_Logo_transparentBackground.png"
       alt="MCP-Bifrost" width="60" align="right">
</picture>

# 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](https://img.shields.io/badge/tests-128%20passing-2ea44f)](https://github.com/FixemBCN/MCP-Bifrost/blob/main/tests/)
[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/FixemBCN/MCP-Bifrost/blob/main/LICENSE)
[![python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![targets](https://img.shields.io/badge/targets-PHP%20%7C%20Python-777)](https://github.com/FixemBCN/MCP-Bifrost/blob/main/docs/comparison.md)

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](#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](https://github.com/FixemBCN/MCP-Bifrost/blob/main/docs/critical-review.md)): 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](https://github.com/FixemBCN/MCP-Bifrost/blob/main/docs/critical-review.md)). 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`](https://github.com/FixemBCN/MCP-Bifrost/blob/main/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](https://github.com/FixemBCN/MCP-Bifrost/blob/main/docs/critical-review.md).

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

```json
"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:

```bash
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.