内容
# mcp-media-9router
`mcp-media-9router` 是一个本地的 MCP（模型上下文协议）服务器，适用于需要网络智能的 AI 代理。它连接 OpenCode 和其他兼容 stdio 的 MCP 客户端到 9router API 进行网络搜索和网页提取。
它在用户机器上本地运行，而搜索和获取请求则通过 HTTPS 发送到 9router 或本地的 9router 实例，地址为 `http://localhost` 任意端口。提供商凭证保留在 9router 后端；用户的 9router API 密钥在设置后存储在 macOS 钥匙串中。
```text
OpenCode 或其他 MCP 客户端
|
| MCP 通过 stdio
v
mcp-media-9router
|
| HTTPS 或本地 HTTP
v
9router API
|
v
Exa, Firecrawl, Jina Reader, Tavily, Brave, GPSE, OpenAI
```
## 用途
在以下情况下使用此服务器：
- 需要搜索网络并接收结构化结果而非非结构化页面。
- 需要获取公共 URL 并接收适合 LLM 上下文的干净 Markdown。
- 选择特定的 9router 提供商，例如 Exa 或 Firecrawl。
- 在提供商暂时不可用时使用已配置的备用链。
- 在一个本地配置中保留提供商选择、API 访问和限制。
## 安装
### 要求
- 具有钥匙串访问权限的 macOS。
- Node.js 22 或更高版本。
- Git 和 npm。
- 有效的 9router API 密钥。
对于托管的 9router，请使用 HTTPS 基本 URL，例如 `https://9router.mibp.me`。本地开发也支持 `http://localhost`，任意端口，例如 `http://localhost:20128` 或 `http://localhost:8080`。其他 HTTP 主机将被拒绝。
检查 Node.js 版本：
```bash
node --version
```
### 从 GitHub 安装
安装程序将项目克隆到 `~/.mcp-media-9router`，安装依赖项，构建它，并在 `~/.local/bin` 中创建 `mm9` 命令。
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/mhiqrambg/mcp-media-9router/main/install.sh)"
```
安装后打开一个新的终端。如果安装程序要求您重新加载 shell，请运行它打印的命令，例如：
```bash
source ~/.zshrc
```
配置 9router 并在 OpenCode 中注册 MCP 服务器：
```bash
mm9 setup --opencode
```
按 Enter 键接受默认值。设置向导会询问：
- 9router 基本 URL。
- 您的 9router API 密钥。
- 用于获取的默认、允许和备用提供商。
- 用于搜索的默认、允许和备用提供商。
选择与您的部署匹配的 9router 基本 URL：
```text
# 主机 9router：需要 HTTPS
https://9router.mibp.me
# 本地 9router：localhost 在任意端口上允许
http://localhost:20128
http://localhost:8080
http://localhost:3000
```
纯 HTTP 故意被拒绝用于除本地主机之外的所有主机。
非机密配置写入：
```text
~/.config/mcp-media-9router/config.json
```
API 密钥存储在 macOS 钥匙串中，不写入 `opencode.json`。
运行设置后的本地验证：
```bash
mm9 check
```
运行一个真实的身份验证请求以验证 9router 连接。这可能会消耗提供商配额：
```bash
mm9 check --online
```
在 `mm9 setup --opencode` 后退出并重新启动 OpenCode。OpenCode 仅在启动时加载 MCP 配置。
### 从本地检查安装
用于开发或测试：
```bash
git clone https://github.com/mhiqrambg/mcp-media-9router.git
cd mcp-media-9router
npm install
npm run build
npm link
mm9 setup --opencode
```
当不再需要时，请删除本地命令链接：
```bash
npm unlink -g mcp-media-9router
```
## 更新
对于由 `install.sh` 创建的安装，请使用以下命令更新到最新的 `main` 分支：
```bash
mm9 update
```
该命令：
1. 拒绝在安装的检查有本地更改时更新。
2. 运行 `git pull --ff-only origin main`。
3. 运行 `npm ci` 并重建项目。
4. 刷新 OpenCode MCP 注册。
在成功更新后重新启动 OpenCode。
`mm9 update` 故意不更新开发检查。请手动更新：
```bash
git pull --ff-only
npm install
npm run build
```
## 功能
### 网络搜索
`web_search` MCP 工具通过 9router 调用 `POST /v1/search` 并返回具有标题、URL、摘要、来源、作者、发布日期和排名的规范结果。
默认搜索提供商：
```text
exa -> gpse -> brave -> openai
```
### 网络获取
`web_fetch` MCP 工具通过 9router 调用 `POST /v1/web/fetch` 并返回提供商提取的 Markdown。
默认获取提供商：
```text
exa -> firecrawl -> jina-reader -> tavily
```
### 提供商策略
获取和搜索具有独立的提供商策略。设置配置每个工具的默认提供商、允许列表和备用顺序。
| 请求的 `model` | 行为 |
|---|---|
| 省略 | 使用配置的默认提供商一次。 |
| 特定提供商 | 使用该提供商一次。它必须在相关的允许列表中。 |
| `auto` | 按顺序尝试配置的备用提供商。 |
仅当上游超时、速率限制和提供商暂时不可用时，才会发生备用。无效输入、无效 URL、身份验证失败和缺少内容不会触发备用。
### 安全性和限制
- 获取仅接受公共 HTTP 和 HTTPS URL。
- 本地主机、私有 IP 范围、URL 凭证和不安全的 URL 方案在请求到达 9router 之前被拒绝。
- `max_characters: 0` 可以从 9router 请求完整内容。
- `MCP_MEDIA_MAX_OUTPUT_CHARS` 仍然限制传递给 AI 代理的输出。
- 搜索和获取结果是不可信的外部内容。请将它们视为参考资料，而不是指令。
## 用法
### CLI
```bash
mm9 setup --opencode # 配置 9router 并注册 OpenCode
mm9 list # 显示活动提供商策略而不显示 API 密钥
mm9 check # 验证本地配置和钥匙串访问
mm9 check --online # 测试身份验证的 9router 请求
mm9 update # 更新 install.sh 安装
mm9 uninstall # 删除 GitHub 安装程序安装和保存的设置
mm9 --help # 显示命令帮助
mm9 --version # 显示已安装的版本
```
`mm9 start` 通常由 OpenCode 启动。它使用保存的配置启动 stdio MCP 服务器。
### 在 OpenCode 中
设置并重启 OpenCode 后，请代理直接使用工具。
使用配置的默认提供商搜索：
```text
使用 web_search 查找印度尼西亚最新的 AI 新闻。返回五条结果。
```
使用选定的提供商搜索：
```text
使用 web_search with model brave 查找官方模型上下文协议文档。
```
使用备用搜索：
```text
使用 web_search with model auto 查找最近的 AI 安全新闻。
```
使用选定的提供商获取：
```text
使用 web_fetch with model firecrawl 获取并总结 https://example.com。
```
使用备用获取：
```text
使用 web_fetch with model auto 获取 https://example.com 作为 Markdown。
```
### MCP 工具输入
`web_search`:
```json
{
"query": "什么是最新的 AI 新闻？",
"model": "exa",
"search_type": "web",
"max_results": 5,
"country": "indonesia",
"language": "indonesia"
}
```
| 字段 | 必需 | 描述 |
|---|---:|---|
| `query` | 是 | 搜索查询，1 到 500 个字符。 |
| `model` | 否 | 允许的搜索提供商或 `auto`。 |
| `search_type` | 否 | 9router 搜索类型。默认值：`web`。 |
| `max_results` | 否 | 结果数量，1 到 20。默认值：`5`。 |
| `country` | 否 | 转发到 9router 的国家偏好。 |
| `language` | 否 | 转发到 9router 的语言偏好。 |
`web_fetch`:
```json
{
"url": "https://example.com",
"model": "firecrawl",
"format": "markdown",
"max_characters": 0
}
```
| 字段 | 必需 | 描述 |
|---|---:|---|
| `url` | 是 | 公共 HTTP 或 HTTPS URL。 |
| `model` | 否 | 允许的获取提供商或 `auto`。 |
| `format` | 否 | 仅支持 `markdown`。 |
| `max_characters` | 否 | 从 9router 请求的最大字符数。`0` 请求完整内容。 |
## 卸载
对于由 `install.sh` 创建的安装：
```bash
mm9 uninstall
```
交互式卸载程序删除 `mm9` 启动器、`~/.mcp-media-9router`、`media-9router` OpenCode 条目、提供商配置和 macOS 钥匙串 API 密钥。因此，后续的 `mm9 setup` 将从干净的设置开始。
要保留配置和钥匙串 API 密钥以便后续重新安装：
```bash
bash ~/.mcp-media-9router/uninstall.sh --keep-config
```
对于非交互式卸载：
```bash
bash ~/.mcp-media-9router/uninstall.sh --yes
```
## 安全
请勿提交 API 密钥或将其粘贴到公共问题、聊天或文档中。如果 API 密钥已公开，请旋转它。有关漏洞报告，请参阅 [SECURITY.md](./SECURITY.md)。
## 许可证
[Apache-2.0](./LICENSE)
