convez.ai
MCP ServerDevOps & InfraestruturaAvançado
kquuen

Reasonix MCP Server

kquuen/reasonix-mcp-server

Modelos caros planejam, modelos baratos executam — economia de 80-90% em custos de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que otimiza custos de IA para programação ao delegar tarefas de execução para modelos mais baratos (DeepSeek) enquanto reserva modelos fortes para planejamento e revisão. Implementa isolamento de processos, persistência atômica de estado e orquestração inteligente de modelos por custo e complexidade.

Instalação

$npx convez-ai kquuen/reasonix-mcp-server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Reduzir custo de tarefas de programação assistida delegando execução a modelos mais baratos
  • Isolar falhas: cada tarefa roda em processo separado sem derrubar o servidor
  • Orquestrar diferentes modelos por complexidade: flash para fixes simples, pro para refatorações complexas

Veredito

Solução experimental bem arquitetada para reduzir custo de IA em desenvolvimento. Destaca-se pelo isolamento robusto de processos, persistência atomic-safe de estado e orquestração intelligente por custo. Necessita maturação em produção, mas o conceito de camadas (raciocínio caro + execução barata) é sólido para equipes que otimizam gastos com IA.

README

A tradução para o português deste README ainda está na fila.

Reasonix MCP Server

用便宜的模型干脏活,让贵的模型做大脑 — 一个基于 MCP 协议 的模型编排层,让宿主 Agent 负责规划,让 DeepSeek 负责落地执行。

License: MIT Node.js

Status: experimental MCP server, actively evolving.

Quickstart

git clone https://github.com/kquuen/reasonix-mcp-server.git
cd reasonix-mcp-server
cp config.toml.example config.toml
node src/server/index.mjs

配置 config.toml 里的 DeepSeek API 信息后,把该 server 作为 stdio MCP server 接入你的 MCP 客户端。

快速检查 MCP 工具列表:

npm run test:ping

为什么要做这个

用 AI 编程助手写代码时,最贵的部分不一定是“思考”,而是反复读文件、搜代码、跑命令、修小错。Reasonix 的目标是把这些执行型工作交给更便宜的模型,把强推理模型留给规划、审查和最终决策。

核心分工:强推理模型是大脑,DeepSeek 是手脚。


兼容性 — 任何支持 MCP 的客户端都能用

Reasonix MCP Server 是一个标准的 MCP 服务器,遵循 Model Context Protocol 规范,通过 stdio 传输层 与宿主 Agent 通信。

这意味着:只要你的编程工具支持 MCP,就能接入 Reasonix。

已验证兼容的客户端

客户端配置方式状态
Kimi Codemcp.json 配置文件✅ 已验证
VS Code + ClineMCP 设置面板✅ 协议兼容
Cursor.cursor/mcp.json✅ 协议兼容
Claude CodeCLAUDE.md 或启动参数✅ 协议兼容
任何自定义 MCP 客户端stdio 启动✅ 协议兼容

MCP 协议合规性

  • ✅ JSON-RPC 2.0 over stdio
  • ✅ MCP initialize / tools/list / tools/call 生命周期
  • ✅ 标准 shutdown / exit 消息处理
  • ✅ 无客户端专属硬编码(所有 tool description 均为通用表述)

如果你的客户端支持 MCP 但列表里没提到,欢迎提 Issue 补充。


架构概览

MCP Client / Host Agent
  plans task, reviews result, decides final merge
        |
        | JSON-RPC over stdio
        v
Reasonix MCP Server
  parses MCP messages, tracks tasks, manages workers
        |
        v
DeepSeek Worker
  reads files, edits code, runs commands, returns result

典型使用场景

  • 把大模型规划好的单文件/多文件修复交给低成本模型执行。
  • 用 review 模式做只读代码审查,避免审查过程误改文件。
  • 长任务拆成子任务,让 Worker 在限定范围内完成执行。

七大设计亮点

🔥 1. 零运行时依赖

整个 Server 基于 Node.js 原生 API 构建 — node:fs 做文件操作,node:child_process 做进程管理,global.fetch 调用 API。没有任何 npm 依赖。

这不是为了炫技。依赖越少,不可控的崩溃点越少。你不需要担心某个 transitive dependency 被投毒、某个 package 突然删库。生产环境部署只需要 Node.js 本身。

🔥 2. 进程级任务隔离

每个编码任务都是一个独立的 Worker 进程。 如果某个任务陷入死循环、耗尽内存、或者调用了一个有问题的命令,它只会杀死自己,不会影响 Server 和其他任务。

Windows 下用 taskkill /T /F 做树级清理,POSIX 下先 SIGTERM 再 SIGKILL,平台感知的设计让终止操作总是有效。

崩溃隔离比崩溃恢复更重要 — 这是我从一开始就坚持的原则。

🔥 3. 原子状态持久化

任务状态不是存在内存里,而是写到磁盘上的 JSON 文件。而且我使用了 先写临时文件 → 再原子重命名 的方式:

const tmp = `${filePath}.${process.pid}.tmp`;
fs.writeFileSync(tmp, JSON.stringify(data));
fs.renameSync(tmp, filePath);   // 原子操作,不会留下半残文件

这意味着即使进程在写入中途被 kill -9,也不会留下损坏的 JSON。Server 重启后,会自动扫描所有状态文件,把之前还在 running 的任务标记为 orphaned(孤儿)并附带错误信息。

状态不会丢,进度不会乱。

🔥 4. 模型分层调度 — 省钱的精髓

这是整个设计的核心。强推理模型做规划,DeepSeek 做执行;复杂任务用 pro,简单任务用 flash。

具体编排逻辑:

环节谁来做为什么
需求分析、任务拆解、架构判断宿主 Agent(强推理模型)强推理能力,理解复杂业务逻辑
读文件、搜代码、改文件、跑测试DeepSeek Worker价格便宜;Reasonix 的固定系统提示词使 DeepSeek prompt cache 命中率极高,重复 token 几乎免费
结果审查、风险评估、最终决策宿主 Agent(强推理模型)综合判断能力强,不容易被忽悠

DeepSeek 内部也有分层:

场景模型原因
简单/范围明确的修复(加注释、修 typo、单文件重构)deepseek-v4-flash更快、更便宜
复杂跨文件重构、依赖分析、类型修复deepseek-v4-pro推理深度足够处理复杂依赖

成本对比(粗略估算):

  • 一个中等复杂度的重构任务,如果全程用强推理模型执行,可能需要 50K~100K token
  • 同样的任务,宿主只做规划和审查(约 5K10K token),DeepSeek 做执行(约 20K30K token,且大量命中缓存)
  • 整体成本可以降到原来的 1/5 ~ 1/10

而且因为 Worker 运行在独立进程中,宿主 Agent 的上下文始终保持干净 — 不会因为执行过程中的工具调用结果而膨胀。规划时的思路清晰,审查时的判断准确。

这不是简单的"传个参数调模型"。这是一个有意识的成本架构设计:把贵的能力用在刀刃上,把便宜的能力用在重复劳动上。

🔥 5. 三种执行模式的语义区分

我为 Worker 设计了三种执行模式,每种模式加载不同的工具子集和系统提示词约束:

模式工具权限用途
task全部 16 个工具,读写权限默认编码任务
review只读工具(read/search/run_command)代码审查,防止审查过程中意外改文件
subtask全部工具 + 范围约束提示词子任务 Worker,限定不越界

这种权限隔离让不同场景下的 AI 行为更可预测、更安全。review 模式本质上是给 AI 戴上了"只读手铐"。

🔥 6. 对抗性代码审查

我在提交代码前加了一道对抗性审查关卡。不是让 AI 说"看起来不错",而是让它扮演一个**"想找茬的安全审计员"** — 默认假设变更有问题,直到证据证伪。

提示词中定义了明确的攻击面优先级:

  • 认证隔离、数据丢失、回滚安全
  • 竞态条件、重试与幂等性缺口
  • 空状态、超时、降级依赖行为
  • 版本偏移、Schema 漂移、兼容性回退
  • 可观测性缺口

每个 finding 必须回答四个问题:能出什么问题?为什么脆弱?影响多大?怎么降低风险?

输出采用严格的紧凑合约:第一行必须是 ALLOW: 或 BLOCK:,后续才是详情。这让审查结果可以被机器解析,宿主 Agent 可以直接据此决定通过或拦截。

审查的默认姿态应该是怀疑,而不是捧场。

🔥 7. 任务续跑与递归委派

我设计了两个让任务可扩展的机制:

续跑(Resume):完整保存对话历史(包括工具调用和结果)。任务中断后,可以从断点继续,不用从头再来。这在长任务场景下非常关键 — 你不会因为一次网络抖动就损失几十轮的对话上下文。

委派(Delegate):一个 Worker 可以把子问题拆给另一个 Worker,形成树状的任务结构。父任务可以通过 get_status 的 children 字段监控所有子任务的状态。这让 Reasonix 不仅能做单点修复,还能处理需要多步骤协作的复杂重构。


快速开始 — 一键插拔

前置要求

1. 安装

npm install -g @reasonix/mcp-server

2. 注册(自动检测 + 写入配置)

reasonix register

CLI 会自动检测你机器上安装的 MCP 客户端(Kimi Code / Cursor / Claude Code / 项目级 .mcp.json),并将 Reasonix 条目写入它们的配置文件。API Key 优先从 DEEPSEEK_API_KEY 环境变量读取,没有则交互式询问。

3. 验证

reasonix setup

检查 Node 版本、API Key 配置、DeepSeek API 连通性。三项全绿即可用。

4. 使用

跟 AI 说「用 Reasonix 调查这个 bug」
或直接调用 reasonix_start_task
或 spawn reasonix-rescue 子代理后台跑

完成了! 不需要 clone 仓库、不需要手动编辑 JSON、不需要重启测试。
reasonix unregister 一键移除;reasonix status 查看注册状态。

CLI 命令速查

命令功能
reasonix register自动检测客户端并写入 MCP 配置
reasonix unregister从所有客户端中移除 Reasonix
reasonix status查看各客户端的注册状态
reasonix setup检查环境(Node/API Key/连通性)

手动配置(备选)

如果你更愿意手动配置,参考 examples/ 目录下的客户端配置示例,或阅读 docs/COMPATIBILITY.md。


MCP 工具速查

工具功能同步/异步
reasonix_start_task启动后台编码任务异步,立即返回 job_id
reasonix_get_status查询任务实时进度同步
reasonix_get_result获取任务最终结果同步(任务完成后)
reasonix_cancel_task取消运行中的任务同步
reasonix_review_changes对抗性审查当前未提交的代码变更同步(内部异步等待 Worker)
reasonix_resume_task从历史断点续跑任务异步

详见 docs/API.md。


项目结构

reasonix-mcp-server/
├── src/
│   ├── server/
│   │   └── index.mjs         ← MCP stdio 网关(客户端无关)
│   ├── worker/
│   │   └── index.mjs         ← 后台任务执行器
│   ├── core/
│   │   ├── config.mjs        ← TOML + 环境变量配置加载
│   │   ├── state.mjs         ← 任务状态管理(原子写入)
│   │   └── review.mjs        ← 对抗性审查提示词与解析
│   └── tools/
│       └── registry.mjs      ← 16 个文件操作工具
├── docs/
│   ├── ARCHITECTURE.md       ← 架构全景
│   ├── DESIGN.md             ← 设计决策记录
│   └── API.md                ← 完整接口文档
├── examples/
│   └── kimi-code-config.json ← Kimi Code MCP 配置示例
├── config.toml.example       ← 配置模板
├── package.json
└── README.md

任务状态机

queued → running (initializing → executing → done)
                                      ↓ (error)
                                   failed
                                      ↓ (user)
                                cancelled

状态持久化到 .reasonix/jobs/<jobId>.json,Server 重启后自动回收孤儿任务。


License

MIT

Ver o original no GitHub

Bom para

Relacionados