# Reasonix Mcp Server

> Cost-aware MCP server for AI coding: expensive models plan, cheaper models execute.

- **Type:** MCP server
- **Install:** `agentstack add mcp-kquuen-reasonix-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kquuen](https://agentstack.voostack.com/s/kquuen)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kquuen](https://github.com/kquuen)
- **Source:** https://github.com/kquuen/reasonix-mcp-server

## Install

```sh
agentstack add mcp-kquuen-reasonix-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Reasonix MCP Server

**用便宜的模型干脏活，让贵的模型做大脑** — 一个基于 [MCP 协议](https://modelcontextprotocol.io) 的模型编排层，让宿主 Agent 负责规划，让 DeepSeek 负责落地执行。

[](LICENSE)
[](https://nodejs.org/)

> Status: experimental MCP server, actively evolving.

## Quickstart

```bash
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 工具列表：

```bash
npm run test:ping
```

---

## 为什么要做这个

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

核心分工：**强推理模型是大脑，DeepSeek 是手脚。**

---

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

Reasonix MCP Server 是一个**标准的 MCP 服务器**，遵循 [Model Context Protocol](https://modelcontextprotocol.io) 规范，通过 **stdio 传输层** 与宿主 Agent 通信。

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

### 已验证兼容的客户端

| 客户端 | 配置方式 | 状态 |
|--------|----------|------|
| **Kimi Code** | `mcp.json` 配置文件 | ✅ 已验证 |
| **VS Code + Cline** | MCP 设置面板 | ✅ 协议兼容 |
| **Cursor** | `.cursor/mcp.json` | ✅ 协议兼容 |
| **Claude Code** | `CLAUDE.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 文件。而且我使用了 **`先写临时文件 → 再原子重命名`** 的方式：

```js
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
- 同样的任务，宿主只做规划和审查（约 5K~10K token），DeepSeek 做执行（约 20K~30K 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 不仅能做单点修复，还能处理需要多步骤协作的复杂重构。

---

## 快速开始 — 一键插拔

### 前置要求

- **Node.js >= 18.0.0**（需要原生 `fetch`）
- **DeepSeek API Key**（[注册即送额度](https://platform.deepseek.com)）

### 1. 安装

```bash
npm install -g @reasonix/mcp-server
```

### 2. 注册（自动检测 + 写入配置）

```bash
reasonix register
```

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

### 3. 验证

```bash
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](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](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/.json`，Server 重启后自动回收孤儿任务。

---

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kquuen](https://github.com/kquuen)
- **Source:** [kquuen/reasonix-mcp-server](https://github.com/kquuen/reasonix-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kquuen-reasonix-mcp-server
- Seller: https://agentstack.voostack.com/s/kquuen
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.