内容
# 模型顾问 MCP
<p align="center">
<a href="README.en.md">英文版</a>
·
<a href="guia_gentle_ai.md">选择标准（指南）</a>
</p>
> **📢 社区贡献** — 本 MCP 的推荐设计适用于 [Gentle AI](https://github.com/Gentleman-Programming/gentle-ai) 的代理。这是为帮助社区选择每个代理的最佳模型而创建的独立项目。 它与 Gentle AI 或 OpenCode 没有官方关联。
MCP 服务器，帮助 LLMs 为每个 coding 代理选择最佳 AI 模型。从 OpenCode 订阅中获取实时数据，并将其与 OpenRouter 的基准和推理能力相结合。
> ⚠️ **注意**：该软件包尚未发布到 npm。 目前仅可通过克隆存储库进行安装（参见 [选项 B：手动](#选项-b-手动开发））。 `npm install -g model-advisor-mcp` 的支持即将到来。
## 功能
- 列出 OpenCode Go 和/或 Zen 订阅中所有可用的模型
- 丰富 OpenRouter 基准（智能、编码、代理）、价格和上下文窗口
- 显示推理支持 — 如果模型具有明确的级别（`xhigh`、`high`、`low`）或仅具有开关
- 读取 Gentle AI 指南的选择标准，以便 LLM 在选择模型之前了解每个代理的需求
- 根据实际数据而非假设，为每个代理推荐模型
## 安装
### 选项 A：npm（推荐）
```bash
npm install -g model-advisor-mcp
```
然后，在 OpenCode 中配置（参见 [配置](#配置)）。
### 选项 B：手动（开发）
```bash
git clone https://github.com/AlonsoSG0/model-advisor-mcp.git
cd model-advisor-mcp
pnpm install
pnpm build
```
## 要求
- **Node.js 18+**
- **OpenCode API 密钥** — 在 [opencode.ai](https://opencode.ai) 上获取（必填）
- **OpenRouter API 密钥** — 在 [openrouter.ai/keys](https://openrouter.ai/keys) 上获取（可选；公共目录无需密钥即可使用）
## 配置
在配置 OpenCode 之前，请确保您的 OpenCode API 密钥作为环境变量在您的 shell 中可用。将其添加到您的 `~/.zshrc`、`~/.bashrc` 或等效配置文件中：
```bash
export OPENCODE_API_KEY="sk-your-api-key"
```
添加后，重启您的终端或运行 `source ~/.zshrc` 以使变量生效。
> **注意**：`OPENROUTER_API_KEY` 是可选的。如果您想使用它，请以相同方式添加：`export OPENROUTER_API_KEY="sk-your-key"`.
将以下内容添加到您的 `opencode.json` 或 `opencode.jsonc` 中：
```jsonc
{
"mcp": {
"model-advisor": {
"type": "local",
"command": [
"node",
"/path/to/model-advisor-mcp/dist/server.js"
],
"cwd": "/path/to/model-advisor-mcp",
"enabled": true,
"timeout": 30000,
"environment": {
"OPENCODE_API_KEY": "{env:OPENCODE_API_KEY}",
"OPENROUTER_API_KEY": "{env:OPENROUTER_API_KEY}"
}
}
}
}
```
如果您通过 npm 安装（`npm install -g model-advisor-mcp`）：
```jsonc
{
"mcp": {
"model-advisor": {
"type": "local",
"command": ["model-advisor-mcp"],
"enabled": true,
"timeout": 30000,
"environment": {
"OPENCODE_API_KEY": "{env:OPENCODE_API_KEY}"
}
}
}
}
```
> **注意**：`OPENROUTER_API_KEY` 是可选的。服务器在没有凭证的情况下查询公共目录；如果您定义了密钥，它将作为身份验证发送到增强请求中。
## 快速入门和示例
安装和配置 MCP 后：
1. 在终端中验证全局安装的可执行文件是否可用：
```bash
command -v model-advisor-mcp
```
命令应返回可执行文件的路径。如果您进行了手动安装，则此步骤不适用：OpenCode 使用上面配置的 `dist/server.js` 路径。
2. 重启 OpenCode 以加载配置并验证连接状态：
```bash
opencode mcp list
```
`model-advisor` 应显示已连接。
3. 将以下提示之一发送到您的代理或 AI 调度器。**这些不是终端命令**：
> 使用 MCP model-advisor，请告诉我 OpenCode Go 和 Zen 订阅中有哪些模型可用。
> 使用 MCP model-advisor，请使用 OpenCode Go 模型提供低成本的推荐。
如果代理可以使用 MCP 数据列出模型或生成推荐，则连接正确。
## 工具
### `list_available_models`
获取 OpenCode 订阅（Go 和/或 Zen）中的所有 AI 模型，并使用 OpenRouter 丰富模型。
**参数：**
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `subscription` | `"go"` \| `"zen"` \| `"both"` | `"both"` | 要查询的订阅 |
| `enrich` | `boolean` | `true` | 设置为 `false` 以省略 OpenRouter（更快） |
**每个模型返回：**
| 字段 | 描述 |
|-------|-------------|
| `ocId` / `ocName` / `ocProvider` | 模型标识 |
| `pricing` | 每 1M 个令牌的输入/输出成本（美元） |
| `contextLength` | 最大上下文窗口（令牌） |
| `benchmarks` | 智能、编码和代理评分（Artificial Analysis） |
| `reasoning` | 可用的努力级别（`supportedEfforts`）和默认值 |
| `subscription` | 模型所属的订阅 |
**推理示例：**
```json
// 具有明确努力级别的模型
"reasoning": {
"supportedEfforts": ["xhigh", "high"],
"defaultEffort": "high",
"mandatory": false,
"defaultEnabled": true
}
// 具有开关的模型
"reasoning": {
"supportedEfforts": [],
"defaultEffort": null,
"mandatory": false,
"defaultEnabled": true
}
// 没有推理的模型
"reasoning": null
```
### `get_agent_criteria`
读取 Gentle AI 指南中的代理选择标准。在选择模型之前使用此工具：每个代理都有特定的需求（上下文、推理、速度和成本）。
**参数：**
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `agent` | `string` | （完整指南） | 要过滤的代理 ID。省略以获取所有代理。 |
**代理 ID：** `gentle-orchestrator`、`sdd-init`、`sdd-onboard`、`sdd-explore`、`sdd-propose`、`sdd-spec`、`sdd-design`、`sdd-tasks`、`sdd-apply`、`sdd-verify`、`sdd-archive`、`review-risk`、`review-readability`、`review-reliability`、`review-resilience`、`review-refuter`、`jd-judge-a`、`jd-judge-b`、`jd-fix-agent`
**代理组（按此顺序显示推荐）：**
1. 调度器
2. SDD 代理
3. 审查（4R）
4. 判决日
### `get_model_benchmarks`
在 OpenRouter 上查找特定模型的详细信息的实用工具。当 `list_available_models` 未为模型带来基准时很有用。
**参数：**
| 参数 | 类型 | 描述 |
|-----------|------|-------------|
| `query` | `string`（必填） | 模型 ID 或名称（例如 `"deepseek-v4-pro"`、`"kimi"`） |
## LLM 如何使用这些工具
典型流程：
1. **`list_available_models`** → 查看可用模型、基准和推理支持
2. **`get_agent_criteria`**（每个代理）→ 了解每个代理的需求
3. **`get_model_benchmarks`**（可选）→ 特定模型的更深入数据
4. **LLM 推理** → 根据标准 + 基准 + 成本将模型与代理匹配
## 开发
```bash
# 安装依赖
pnpm install
# 编译 TypeScript
pnpm build
# 直接运行（用于测试）
pnpm start
# 监视模式（自动重新加载）
pnpm dev
```
