内容
9Router MCP 服务器
==================
[](https://github.com/k1rana/ninerouter-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/ninerouter-mcp)
[](https://www.npmjs.com/package/ninerouter-mcp)
MCP 服务器，暴露 9Router 功能，作为原生工具，供任何 MCP 客户端使用：模型发现、自动回退、Zod 验证输入。
> **状态：** 9Router 已经在单个 API 后隐藏了提供者特定的复杂性。此服务器通过 MCP 公开该 API，以便代理和应用程序可以调用网页搜索、网页获取、图像生成、TTS、STT 和嵌入，作为标准 MCP 工具 - 无需加载技能文件，无需每个提供者的胶水代码。
## 为什么使用它
- 工具始终已注册；无需手动加载技能（节省令牌和上下文）。
- 当主模型失败时自动回退。
- 在任何网络调用之前，具有清晰错误消息的 Zod 验证输入。
- 端点、身份验证和默认模型的一个配置文件，带有回退链。
- 单个传输（`stdio`）；与任何支持 MCP 的客户端一起使用。
聊天 / 代码生成故意 **不** 包括 - 这就是主机模型的作用。
## 目录
- [安装](#安装)
- [配置](#配置)
- [运行](#运行)
- [工具](#工具)
- [故障排除](#故障排除)
- [开发](#开发)
- [许可证](#许可证)
## 安装
软件包在 npm 上为 `ninerouter-mcp`。JSON 正文在每个 MCP 客户端上是相同的 - 只有顶级密钥和文件路径不同。将代码块粘贴到客户端配置中的正确密钥中：
```json
{
"ninerouter": {
"type": "stdio",
"command": "npx",
"args": ["-y", "ninerouter-mcp"],
"env": {
"NINEROUTER_URL": "http://localhost:20128"
}
}
}
```
客户端的顶级密钥：VS Code（`servers`），OpenCode（`mcp`，重命名 `env` → `environment`，设置 `type: "local"` 和 `enabled: true`），Claude Code / Cursor / Windsurf / Claude Desktop / Zed（`mcpServers` 或 `context_servers`，删除 `type` 行）。JetBrains 使用 **设置 → 工具 → AI 助手 → MCP** 中的 UI 对话框，带有相同的命令、参数和环境变量。
### Claude Code
```bash
claude mcp add --scope user ninerouter -e NINEROUTER_URL=http://localhost:20128 -- npx -y ninerouter-mcp
```
### Codex CLI
```bash
codex mcp add ninerouter --env NINEROUTER_URL=http://localhost:20128 -- npx -y ninerouter-mcp
```
### Hermes Agent
添加到 `~/.hermes/config.yaml`：
```yaml
mcp_servers:
ninerouter:
command: npx
args:
- -y
- ninerouter-mcp
env:
NINEROUTER_URL: http://localhost:20128
```
## 配置
服务器需要一个 9Router 基本 URL。可选地，它接受一个 API 密钥和每个工具的默认模型回退。
来源，按优先级顺序（最高优先）：
1. CLI 标志 `--config <path>`（或 `--config-file`，`-c`，`NINEROUTER_CONFIG` 环境变量）
2. `~/.config/ninerouter-mcp/config.toml`
3. 环境变量：`NINEROUTER_URL`，`NINEROUTER_KEY`
如果配置文件存在，它将覆盖环境变量。
### 快速设置
生成一个启动配置文件并编辑它：
```bash
npx ninerouter-mcp create-config
```
这将写入 `~/.config/ninerouter-mcp/config.toml` 并拒绝覆盖现有文件。
### 手动设置（环境变量）
**Windows（PowerShell）：**
```powershell
$env:NINEROUTER_URL = "http://localhost:20128"
$env:NINEROUTER_KEY = "sk-..." # 可选
```
**macOS / Linux：**
```bash
export NINEROUTER_URL=http://localhost:20128
export NINEROUTER_KEY=sk-... # 可选
```
`NINEROUTER_KEY` 是可选的，仅在您的 9Router 实例启用身份验证时需要。
### 手动设置（配置文件）
```toml
# 9Router 基本 URL（必填）
base_url = "http://localhost:20128"
# 可选的 API 密钥
# api_key = "sk-..."
# 默认模型，支持回退。
# 单个字符串 = 一个模型。
# 数组 = 按顺序尝试，第一个成功，错误被聚合。
[default_models]
web_search = ["tavily/search", "brave-search/search"]
web_fetch = ["firecrawl/fetch", "jina-reader/fetch"]
generate_image = "openai/dall-e-3"
text_to_speech = "openai/tts-1"
speech_to_text = ["openai/whisper-1", "groq/whisper-large-v3-turbo"]
embeddings = "openai/text-embedding-3-small"
```
`ninerouter` 表也接受顶级 `base_url` 和 `api_key` 的别名：
```toml
[ninerouter]
base_url = "http://localhost:20128"
api_key = "sk-..."
```
指向非默认配置文件：
```bash
npx -y ninerouter-mcp --config /path/to/config.toml
# 或
NINEROUTER_CONFIG=/path/to/config.toml npx -y ninerouter-mcp
```
## 运行
从此仓库运行 `npm install`：
```bash
npm run build
npm start
```
或在开发过程中以监视模式运行：
```bash
npm run dev
```
已发布包的用户可以直接运行：
```bash
npx -y ninerouter-mcp
```
## 工具
每个工具都在启动时在 MCP 服务器上注册。除非另有说明，否则所有工具都返回一个带有漂亮打印的 JSON 的单个文本内容块。
### `list_models`
在调用其他工具之前发现有效的模型 ID。
| 参数 | 类型 | 是否必填 | 描述 |
| --------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `kind` | 字符串 | 否 | `chat`、`image`、`tts`、`embedding`、`web`、`stt`、`image-to-text` 之一。省略为默认聊天模型。 |
### `web_search`
通过 9Router 搜索网页。
| 参数 | 类型 | 默认值 | 备注 |
| -------------- | ------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `query` | 字符串 | — | 必需。 |
| `model` | 字符串 | — | 9Router 模型 ID（例如 `tavily/search`）。回退到 `provider`，然后是 `default_models.web_search`。 |
| `provider` | 字符串 | — | `model` 的别名。 |
| `maxResults` | 数字 | `5` | 1–20。 |
| `searchType` | 字符串 | `web` | `web` 或 `news`。 |
| `country` | 字符串 | — | |
| `language` | 字符串 | — | |
| `timeRange` | 字符串 | — | |
| `domainFilter` | 字符串 | — | |
### `web_fetch`
获取一个 URL 并将其作为 Markdown、文本或 HTML 返回。
| 参数 | 类型 | 默认值 | 备注 |
| ---------------- | ------ | ---------- | -------------------------------------------- |
| `url` | 字符串 | — | 必需。必须是有效的 URL。 |
| `model` | 字符串 | — | 例如 `jina-reader/fetch`、`firecrawl/fetch`。 |
| `provider` | 字符串 | — | `model` 的别名。 |
| `format` | 字符串 | `markdown` | `markdown`、`text` 或 `html`。 |
| `maxCharacters` | 数字 | `8000` | 截断限制。 |
### `generate_image`
文本到图像生成。始终写入文件并返回图像作为 base64 内容块加上 `{ outputPath, bytes, contentType }`。省略 `outputPath` 以写入操作系统临时目录。
| 参数 | 类型 | 默认值 | 备注 |
| ------------ | ------ | ----------- | --------------------------------------------------------------------------------------------------- |
| `prompt` | 字符串 | — | 必需。 |
| `model` | 字符串 | — | 例如 `openai/dall-e-3`、`gemini/gemini-3-pro-image-preview`。 |
| `provider` | 字符串 | — | `model` 的别名。 |
| `n` | 数字 | `1` | 1–10。 |
| `size` | 字符串 | `1024x1024` | |
| `quality` | 字符串 | — | `standard` 或 `hd`。 |
| `outputPath` | 字符串 | 操作系统临时目录 | 写入文件的位置。默认 `os.tmpdir()/ninerouter-<slug>-<ts>.<ext>`。扩展名来自 content-type。 |
### `text_to_speech`
合成音频。始终写入文件并返回音频作为 base64 内容块加上 `{ outputPath, bytes, contentType }。` 省略 `outputPath` 以写入操作系统临时目录。
| 参数 | 类型 | 默认值 | 备注 |
| ------------ | ------ | --------- | --------------------------------------------------------------------------------------------------- |
| `input` | 字符串 | — | 必需。 |
| `model` | 字符串 | — | 例如 `openai/tts-1`、`edge-tts/vi-VN-HoaiMyNeural`。 |
| `provider` | 字符串 | — | `model` 的别名。 |
| `outputPath` | 字符串 | 操作系统临时目录 | 写入文件的位置。默认 `os.tmpdir()/ninerouter-<slug>-<ts>.<ext>`。扩展名来自 content-type。 |
### `speech_to_text`
转录音频。提供 `audioPath` 或 `audioBase64` 中的恰好一个。
| 参数 | 类型 | 默认值 | 备注 |
| ---------------- | ------ | ------- | ------------------------------------------------------- |
| `audioPath` | 字符串 | — | 本地文件路径。 |
| `audioBase64` | 字符串 | — | Base64 有效载荷。 |
| `fileName` | 字符串 | 派生 | 用于 multipart 上传的文件名。 |
| `model` | 字符串 | — | 例如 `openai/whisper-1`、`groq/whisper-large-v3-turbo`。 |
| `provider` | 字符串 | — | `model` 的别名。 |
| `language` | 字符串 | — | ISO-639-1 代码，例如 `en`、`vi`。 |
| `prompt` | 字符串 | — | |
| `responseFormat` | 字符串 | `json` | `json`、`text`、`verbose_json`、`srt`、`vtt`。 |
| `temperature` | 数字 | — | 0–1。 |
### `embeddings`
为字符串或字符串批生成嵌入。
| 参数 | 类型 | 默认值 | 备注 |
| ---------------- | --------------- | ------- | ------------------------------------------------------------- |
| `input` | 字符串 \| 数组 | — | 必需。单个字符串或非空字符串数组。 |
| `model` | 字符串 | — | 例如 `openai/text-embedding-3-small`。 |
| `provider` | 字符串 | — | `model` 的别名。 |
| `encodingFormat` | 字符串 | `float` | `float` 或 `base64`。 |
| `dimensions` | 数字 | — | 可选覆盖。 |
## 行为说明
- **回退链。对于每个使用模型的工具：** 如果设置了 `model`/`provider`，则只尝试该模型。否则，尝试 `default_models.<tool>` 中的链。如果所有条目都失败，则工具会抛出一个 `所有模型失败。错误：...` 错误，其中包括每个模型的错误消息。
- **`provider` 是 `model` 的别名**，在接受模型的每个工具上。设置哪一个在您的用例中读起来更好。
- **图像和音频始终写入文件并作为内容块返回。** `generate_image` 和 `text_to_speech` 请求 `b64_json` / `mp3` 来自上游，写入 `outputPath`（或省略时写入操作系统临时目录），并将资产作为 MCP `image` / `audio` 内容块返回，加上 `{ outputPath, bytes, contentType }`。主机可以显示内联或仅使用路径。扩展名源自上游 `content-type`。
- **配置文件优先于环境变量。** 如果您需要为单个运行设置不同的设置，请优先使用 `--config` 而不是导出环境变量。
- **STT 多部分上传。** 工具以 `multipart/form-data` 发送音频；`fileName` 仅在上游提供者检查文件名时相关。
- **配置文件在启动时读取一次。** 编辑 `config.toml` 或更改 `NINEROUTER_URL` / `NINEROUTER_KEY`，然后重启 MCP 服务器。热加载未实现。
## 故障排除
- **`NINEROUTER_URL 是必需的`** — 设置环境变量或创建 `~/.config/ninerouter-mcp/config.toml` 并设置 `base_url`。
- **`未指定模型且未配置 default_models.<tool>``** — 在调用中传递 `model` 或在配置中添加 `default_models` 条目。
- **`所有模型失败。错误：...`** — 每个备用模型都返回了一个错误；聚合消息包括每个模型的错误消息。
- **身份验证错误（401/403）** — 您的 9Router 实例需要一个密钥；设置 `NINEROUTER_KEY` 或配置文件中的 `api_key`。
- **STT 失败并显示“提供 audioPath 或 audioBase64”** — 必须设置这两个中的一个。
## 开发
```bash
npm install
npm run dev # tsx 监视模式
npm run build # tsc -> dist/
npm start # node dist/index.js
npm run check # typecheck + lint + prettier --check
```
项目布局：
```
src/
index.ts # bin 入口；调度 create-config 或 server
server.ts # McpServer 设置
ninerouter-client.ts # 配置 + HTTP 帮助程序
create-config.ts # `ninerouter-mcp create-config` 子命令
tools/
models.ts # list_models
web.ts # web_search, web_fetch
media.ts # generate_image, text_to_speech, speech_to_text
embeddings.ts # embeddings
common.ts # 共享回退 + json 帮助程序
config.example.toml # 示例配置（镜像 create-config 输出）
```
## 许可证
Apache-2.0。请参阅 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器