# cn-llm-mcp

本地 MCP Server，用来让 Claude、Codex、Cursor 等支持 MCP 的 agent 把低风险小任务委托给低成本模型执行，主 agent 负责审核结果。

它按 OpenAI-compatible Chat Completions 接口实现，支持 DeepSeek、通义千问兼容模式、Kimi、智谱、豆包，也支持自定义兼容服务。

## 适合做什么

- 摘要、改写、文案初稿
- README、说明文档、邮件草稿
- 简单 HTML/CSS/JS 页面初稿
- 小范围测试草稿
- 低风险机械代码修改建议

不建议把安全、权限、支付、生产数据、复杂架构判断、密钥、cookie、令牌或隐私数据委托给这个工具。

## 客户本地安装

客户需要自己准备国内模型或代理服务的 API Key。API Key 留在客户自己的电脑上。

```bash
git clone https://github.com/ZhuoS62/cn-llm-mcp.git
cd cn-llm-mcp
npm run setup
```

`npm run setup` 会自动：

- 安装依赖
- 构建项目
- 询问模型服务商、API Key、Base URL 和模型名称
- 写入 `.env`
- 运行 `npm run doctor`
- 可选自动配置 Codex MCP 和 `AGENTS.md`

AI agent 自动安装时，也可以在询问用户后用环境变量非交互运行：

```bash
CN_LLM_SETUP_PROVIDER=deepseek \
CN_LLM_SETUP_MODEL=deepseek-chat \
CN_LLM_SETUP_API_KEY=客户自己的_API_Key \
npm run setup
```

自定义 OpenAI-compatible 代理：

```bash
CN_LLM_SETUP_PROVIDER=custom \
CN_LLM_SETUP_BASE_URL=https://example.com/v1 \
CN_LLM_SETUP_MODEL=your-model \
CN_LLM_SETUP_API_KEY=客户自己的_API_Key \
npm run setup
```

如果不想使用交互式安装，也可以手动配置 `.env`。

DeepSeek 示例：

```bash
CN_LLM_PROVIDER=deepseek
CN_LLM_API_KEY=replace_me
CN_LLM_MODEL=deepseek-chat
```

自定义 OpenAI-compatible 代理示例：

```bash
CN_LLM_PROVIDER=custom
CN_LLM_BASE_URL=https://example.com/v1
CN_LLM_MODEL=your-model
CN_LLM_API_KEY=replace_me
```

服务启动时会自动读取项目根目录的 `.env`。

## 自检

```bash
npm run doctor
```

自检会检查：

- Node.js 版本是否 >= 20
- `dist/index.js` 是否存在
- `.env` 是否存在
- `CN_LLM_API_KEY` 是否填写
- MCP 是否能列出 `run_cn_model` 和 `draft_code_patch`

`doctor` 不会真实调用模型生成内容。

## 常用 provider

```bash
# DeepSeek
CN_LLM_PROVIDER=deepseek
CN_LLM_MODEL=deepseek-chat

# 通义千问 OpenAI 兼容模式
CN_LLM_PROVIDER=qwen
CN_LLM_MODEL=qwen-plus

# Kimi
CN_LLM_PROVIDER=kimi
CN_LLM_MODEL=moonshot-v1-8k

# 智谱
CN_LLM_PROVIDER=zhipu
CN_LLM_MODEL=glm-4-flash

# 豆包，需要按火山方舟创建的 endpoint/model 调整
CN_LLM_PROVIDER=doubao
CN_LLM_MODEL=doubao-seed-1-6-250615
```

## Claude Desktop 配置

把下面配置加入 Claude Desktop 的 MCP 配置文件。把路径替换成客户本机的绝对路径。

```json
{
  "mcpServers": {
    "cn-llm-worker": {
      "command": "node",
      "args": ["/absolute/path/to/cn-llm-mcp/dist/index.js"]
    }
  }
}
```

模板文件：

[examples/claude-desktop.json](examples/claude-desktop.json)

## Codex 配置

把下面配置加入 `~/.codex/config.toml`。把路径替换成客户本机的绝对路径。

```toml
[mcp_servers.cn-llm-worker]
command = "node"
args = ["/absolute/path/to/cn-llm-mcp/dist/index.js"]
startup_timeout_sec = 30
```

模板文件：

[examples/codex-config.toml](examples/codex-config.toml)

## Cursor 配置

Cursor 的 MCP 配置通常也是 JSON。把路径替换成客户本机的绝对路径。

```json
{
  "mcpServers": {
    "cn-llm-worker": {
      "command": "node",
      "args": ["/absolute/path/to/cn-llm-mcp/dist/index.js"]
    }
  }
}
```

模板文件：

[examples/cursor-mcp.json](examples/cursor-mcp.json)

## 建议给 agent 的规则

可以把下面规则加入 Claude Project instructions、Codex `AGENTS.md` 或 Cursor rules：

```text
对于低风险、小范围、机械性任务，可以优先调用 `cn-llm-worker` 让低成本模型生成草稿，例如摘要、文案、README 初稿、简单测试草稿、小型 patch 或简单网页初稿。

不要把 secrets、API key、cookie、令牌、隐私数据或无关的大段上下文发送给 `cn-llm-worker`。

收到 `cn-llm-worker` 的结果后，必须由主 agent 审核；涉及安全、权限、支付、数据一致性、复杂架构判断或高风险代码时，不要委托给该工具。

如果调用了 `cn-llm-worker`，请告诉用户 provider、model 和 token usage。如果没有调用，不要假装调用。
```

模板文件：

[examples/agent-rule.md](examples/agent-rule.md)

## 暴露的工具

### run_cn_model

通用任务委托工具。适合摘要、文案、方案、简单代码草稿。

参数示例：

```json
{
  "task": "把下面内容整理成三点摘要",
  "context": "需要处理的内容",
  "output_format": "text"
}
```

### draft_code_patch

代码 patch 草稿工具。适合小范围、低风险代码任务。

参数示例：

```json
{
  "task": "给 add 函数补一个边界测试",
  "files": [
    {
      "path": "src/math.ts",
      "content": "export function add(a: number, b: number) { return a + b; }"
    }
  ],
  "constraints": "只返回 unified diff"
}
```

## 测试提示词

配置完成后，在 agent 里测试：

```text
优先使用 cn-llm-worker。请让低成本模型用三句话解释 MCP 是什么，然后你审核它的回答。
```

如果调用成功，agent 应该能看到 `provider`、`model` 和 `usage`。

## 常见问题

### 401 invalid credentials

API Key 无效、过期、填错，或代理服务不接受当前 key。重新生成 API Key 后更新 `.env`。

### 404 Not Found

通常是 `CN_LLM_BASE_URL` 不对。OpenAI-compatible 服务一般需要以 `/v1` 结尾，例如：

```bash
CN_LLM_BASE_URL=https://example.com/v1
```

### model not found

`CN_LLM_MODEL` 不在服务商支持列表里。改成服务商文档里的模型名。

### agent 看不到工具

先运行：

```bash
npm run doctor
```

如果 `doctor` 正常，重启 Claude/Codex/Cursor，确认 MCP 配置里的路径是绝对路径并且指向 `dist/index.js`。

## 安全说明

- `.env` 不要提交到仓库。
- 客户应使用自己的 API Key。
- 这个 MCP Server 不会直接修改文件，只返回文本或 patch 草稿。
- 最终应用 patch、运行测试和判断风险应由主 agent 完成。