MCP-Bifrost

用廉价模型重写 200 个代码块，但不会让结果中的任何一个进入昂贵模型的上下文——也不会拿磁盘上写入任何无法编译的内容。

一个 MCP 服务器，接收编排模型已经分析并拆解好的代码任务, 用语言自身的解析器精确提取目标代码块，将改写工作交给一个更廉价的工作模型，校验结果，原子地应用，并把整个过程记录在编排模型的上下文之外。

大脑负责决策，肌肉负责键入。Bifrost 就是二者之间的神经——并且负责保证没有任何损坏的内容落到磁盘上。

下面的示例中，大脑是 Claude，肌肉是 DeepSeek——DeepSeek 只是当时手头可用的模型。两者都不是必需的。为什么要看 The worker, 可以了解为什么需要一个您本机也常用的 7B 模型。

Why(为什么)

一个由 LLM 编辑的大型代码库只有一个真正的瓶颈，并不任何智能，而是上下文：代码库读取一个第 4600 行文件，只改其中的三十行，这会烧掉编排者的窗口，而这些文本之后不会被用到。

Bifrost 的前提是编码中机械的那一半——编写替换文本——既不需要昂贵模型，也不需要经过其上下文。

实话实说（见 RF-4）：对单个小改动而言，节省是真实但有局限的，因为编排者通常无论如何都得先读代码，才能说清楚自己想要什么。数量级的好处是在“量大”时显现——跨多个符号的变换，指令可以不用读任何内容就能写出来。

这就是本项目所要解决的使用场景。不是“修复这个 bug”。

Related MCP server: ropey

何时不使用

• 探索性任务。“找出崩溃的原因”不是 Bifrost 能执行的一项说明。它在开始之前必须知道对应的符号。

• 零星的单次小改动。 此刻面量平权意义不大，我们也这样说过（RF-4）。使用你的智能体常规工具去编辑。

• 延迟敏感多的循环。 平均约 2.6 秒一个块，已针对 DeepSeek 实测。

• 所有不是 PHP 或 Python 的东西。 添加一门语言意味着编写一个解析器适配器，而不是改核心——但目前还没有。

• 跨文件重构，且一个编辑的结果由编辑自身的输出决定。patch_group 提供原子性，而不是先后顺序。

• 无法告诉你是否出错的代码库。 这里的每个门只查形式；没有哪个门理解含义。

和 Aider、Serena 以及 fast-apply 模型相比是如何定位的——包括在哪些它们更优秀——见 docs/comparison.md。

它是如何工作的

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

编排者决定做什么与怎么做。worker 什么也不决定。唯一允许触碰磁盘的是服务器，而且在所有关卡通过之前，它都会拒绝。

校验关卡

默认就开启三个，不是四个。实质关卡是一个粗粒度的正则检查，在调整期间从未触发，而一个会误判好补丁的关卡比一个未启用但待命的更糟。在批量工作前用 substance_gate=True 启用它。

曾有一个比较目标范围之外字节的“外围检查”，指定并实现，然后删除了：服务器重建文件时使用 original[:start] + block + original[end:]，因此外围通过构造得以保留，该检查永远不会失败。在实际验证中也得到了确认——在三个文件已经语法破碎的情况下，这一门仍报告 9/9。见 [RF-1](https直接 https github.com/FixemBCN/MCP-Bifrost/blob/main/docs/critical-review.md)。

回滚

Git 本身就是一个内容寻址数据库，所以也这样用它。每个 patch 前用 git hash-object -w 得到一个 blob SHA 放入日志；回滚就是通过 git cat-file blob。自动去重压缩，对脏工作树也有效，并且不需要维护专门的快照格式。

The worker

DeepSeek 只是手头可用的模型，而本仓库里每个数字都是拿它测的。它不是必需项，而且很可能也不是最有意思的用法。

The worker 的任务是刻意狭义的。它只接收一个单独的块和一个指令，然后返回一个块。它不选择文件、不做规划、不 decides which code to edit，也看不到代码库中其余项目。这是一个 7B编程模型 能做得好的任务——也正是这些闸门的存在才能让一个弱 worker 的错误在写到盘上之前而不是之后就被发现。

本机方案由此显得更具吸引力：

• 你的代码永不离开这台机器。 对于专有代码库来说，这已经不是“偏好”，而是前置条件。

• 成本降为零，恰好出现在本工具面向的负载上——一次运行数百个块是常态而不是例外。

• 上下文要求极低。 只有一个方法，不是整个文件。8k 窗口就完全够用；整个设计就是让 worker 永远不会超过它需要的范围。

• 一个弱的 worker 也是可接受的，只要每次输出在落盘前都被解析、语法检查、diff。一次坏块只导致重试一次，而不是文件损坏。

最后一点才是真正的论据。把代码生成委托给一个小型本地模型通常很不可取，原因是无法信任输出，而手动检查比直接写更费劲。Bifrost 的回答是：检查是机制性的，机器可以做。

任何兼容 OpenAI 的接口都可以——Ollama、llama.cpp、LM Studio、vLLM 的 server：Server：

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

如果接口不是默认的官方，就不需要 key。

端点的适用性评估

目前还没有本地模型被评测过。 端点本身可配置，协议也是最普通的 OpenAI 兼容聊天补全，但本仓库不发布未经过实际测量的声明——包括对我们自身有利的部分。

工具已经在这。把你的端点放进来：

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

如果你跑过，请用结果把这一行交给 PR。对模型表现难看的数据同样有用，和看起来漂亮的数据一样有用——这张表的作用是说明真正能跑的是什么，而不是在宣传。

有一点你要有准备。 DeepSeek 在 9 个响应里，0 个用 Markdown 围栏包住。而更小的模型几乎都会包，解析问题，而不是模型能力问题。Bifrost 已经会去掉围栏；如果你的模型其它部分没问题但总围栏失败，请在这里作为一个 bug 提交，而不要当作你对模型的结论。

哪些内容会离开你的机器

发送给 worker 的是解析过的单个块——即一个方法——而不是它所来自的下级文件。这是设计的结果，而不是额外加上的特征：如果替换代码不经过 orchestrator，上下文就不会，也就不会经过右边路径传过长度。

它“不”是什么意思。 这个块仍然，以明文方式，到达你所设的端点；指令也是一样的，而指令本身可能描述内部架构。

它目前是怎么被脱敏的。 Heimdall 会在进行发送之前，而不是写盘之前，执行保护。某个 secret 如果需要以独立 token 形式，则会把它换成一个占位符，worker 在周围对代码进行专项训练，然后在入盘前把原件放回——每个占位符必须恰好回来一次，否则什么都不写。不能安全屏蔽的东西，就干脆阻止发送。在真实代码库上，实测误报率：1291 个符号里 2 个，两个都正确地拒绝了操纵，而不是持有。

如果你的要求构成不允许任何内容离开，答案是本地 worker，而不是更低的有效载荷。

只在设计图上，还没实现

两个补充可以补上大部分剩余差距。都还没有存在，而这里写出来是因为设计本身有意思：

• 出向日志。 日志记录发送过的内容的大小，而不是字节。连同回传数据一并记下来几乎是不免费，它能把“信任我们”变成“可以审计”。

• 免密写和注释。 Hei 只对形似 secret 的东西做脱敏。而解析器已经产出了语法树，所以注释和字符串字面量——往往本质就是风险，且经常与本次转换无关——可以用不透明标记代替，等 return 后恢复。

第二个补充显然的反对理由是，当 worker 看不到到名字，质量受损。那是一个可度量的问题，不是论点：calibrage/calibra.py 里九个，九个不带脱敏。无论结论是什么，都会被发布。

快速开始

Python 3.11+。没有 Python 依赖 —— 服务依赖的是 标准库，各语言的解析由语言自身的解析方式完成，php 作为外部程序，ast 纯标准库：

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

把它加到项目要改写在 .mcp.json：

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

或者直接源码，不安装：

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

把 key 放在那个文件里。 放在项目根目录的 .bifrost.env 中，当运行环境中没有携带 key 时，服务端会读取它：

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

或者干脆不写 key，直接另设 BIFROST_WORKER_BASE_URL 指向一个本地模型的 endpoint。完整说明，以及这之前你还该做什么，都在 manual.

Tools

Brdis

校准

在写出一行服务端代码之前，必须先回答一个问题：

给定一个真实代码库中的真实方法，并在紧凑的 schema 中给出，worker 返回的代码能否被应用而不会破坏任何东西？

calibratge/ 中的测试装置回答了这个问题。零依赖 —— Python 标准库加上 php 二进制即可。

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

结果：前提成立。 9/9 份合法 JSON，恒等任务中 3/3 字节完全一致，3/3 没有丢失原始行，0/9 被包在 markdown 代码围栏中，平均延迟 2.6 秒。

它还发现了一个与 worker 无关的字节偏移 bug，这个 bug 会在生产环境中悄然破坏文件。完整总结：docs/calibration.md。

仓库布局

代码背后

坦白说：这个代码库没有一行是手动写的。 它是一种的人类引导的 AI 流程，概念化、定义、实现、测试并将质疑贯穿其中。下面尽可能精确地说这些到底意味着什么。

人类 —— 问题、决策、方向。 我提供了初始规格，并做了每一个产品层面的决定：选择哪个 worker 模型、哪些语言、该减去什么、下一步做什么、许可证、命名、何时停止。其中很几分更改过之前的决定——比如许可证最初是一个“禁止转售但源码可获取”的版本，后来我决定让“覆盖面”比“控制权”更重要，最终定为 Apache-2.0。我还规定了系统必须拒绝做什么，后来这被证明才是更关键的那一半。

Claude Opus —— 对抗式设计。 在实现之前，Claude 以局外人的身份检查规格，寻找会失败的原因，并提出了十二个威胁。力量推翻了项元素：规格所依赖的中央“外围检查”被视为无法失败的检查，而项目宣称的“令牌节省”在单次编辑中几乎微不足道，只有批量操作时才体现出决定性。这两条没有经过任何修改，保存在原样 brainstorm/ 中。

测量先于代码。 在没有相信设计的情况下，我们先构建了校准装置，并在真实代码上对真实 worker 运行。9 个例子中 6 个失败——没有一个是 worker 的问题。原因是一个字节偏移 bug，它会在生产环境中被静态引入所有的重音字符文件。这也反驳了 Claude 自己审查中的两条结论。这些修正信息原本被保留在那些声称的“上面”，而不是替换掉它们。

Claude Opus —— 核心代码；委托的模型 —— 外围。 解析、打补丁、验证门禁、密钥处理和引擎直接由 Claude 完成。两个外围模块和整个测试套件由更小的模型（Haiku 和 Sonnet）作为子代理完成。这些“分成”的人是对的，并不是为了省钱：一个对补丁代码“冷启动”的模型，极有可能重新引入 byte-offset 这个 bug，因为写这种代码的时"常自然的方式"恰恰是错了。

委托的模型在 Claude 写的代码中发现了四个真实 bug，其中一种 docblock／注释与其所注释的方法分离，另一个 case 里嵌套的 switch 静默丢分支。这两个 bug 都通过了所有验证门。唯一把它们找出来的是一个与代码没有任何利害关系的模型自己所作的对抗式审查。

人类 —— 检查、验收。 我安排顺序、检查结果、把声明拿出来追问，并决定保留什么。Claude 执行验证与校准运行；我读取结果，并确定它们意味着什么。

这个过程没有提供什么

没有任何人逐行通读完这个仓库的全部约 7,400 行代码——大约 4,100 行服务端、2,700 行测试和 600 行测量装置。这里的信心来自测试（与故意写坏的代码比对）、对真实代码库所有测量，以及一个不写入绝不把验证完成的东西的设计——说白了，并不是因为有人读一遍 manual。

如果你需要的那种信心的专业软件编辑工具不是这种，那你完全有资格拒绝。并且 责任章节 会明确写到哪些验证门能抓，哪些不会被抓。

为什么把它们放在 README 里

Bifrost 本身是对自己前提的一种展示。人类的真正贡献并不在于“打字”过程关于文本的那部分，而是：定义问题、控制上下文、挑战那肯定一定会出错的输出，并坚持做足够多的验证，让生成的代码最终也可信。

仓库里有预处理保留了很多疑问过程、被否掉的想法、对抗式审查和测量结果——包括 AI 自己出错并承认的部分。

文档

brainstorm/ 保存着工作记录：原始规格、跨越五次修改的设计日志、对抗性审查，以及测量结果。当两个文件的内容有出入时，docs/ 是参考依据并获胜。

责任

本工具使用语言 Model 自动编辑你的源码。Apache 2.0 意味着它按现状提供，不作任何担保：你都对其所对应你的代码负责。请阅读 diff，运行测试后再运行错误/DEC部署。在 手册 中明确列举了门禁能捕获和不能捕获什么。

贡献

欢迎各种形式的贡献——包括提出“这里有问题”的反对意见。这个项目已经因为一个验证门完全同理而删除了它，并且用实测反驳了自己的两条断言。

而真正重要的是：每一个测试都必须能够失败。 详细说明见 手册。

许可

Apache License 2.0。

集成 Model Context Protocol 参考，由 Anthropic, PBC 以 MIT 协议开放。MCP-Bifrost 是独立项目，与 Anthropic, PBC 没有任何关联、认可或赞助。