Skip to main content
Glama
yuanbao-search-mcp

yuanbao-search-mcp

by Neglecton
README.md
# @suhoan/yuanbao-search-mcp

对接腾讯云元宝搜索(产品代号 `wsa`,接口 `SearchPro`)的独立 MCP(Model Context Protocol)Server,基于 TypeScript / Node.js 实现,通过标准 `stdio` 传输与 ZCode、Claude Desktop、Cursor 等 AI 客户端集成。

## 特性

- **双鉴权自动适配**:
  - **服务 API KEY 方式(推荐)**:仅需配置 `TENCENTCLOUD_WSA_APIKEY`,通过 `Authorization: Bearer <API_KEY>` 直连 `https://api.wsa.cloud.tencent.com/SearchPro`,免签名配置最简单。
  - **腾讯云标准方式(TC3-HMAC-SHA256)**:配置 `TENCENTCLOUD_SECRET_ID` + `TENCENTCLOUD_SECRET_KEY`(可选 `TENCENTCLOUD_TOKEN`),自动完成云 API v3 签名并请求 `https://wsa.tencentcloudapi.com/`。
- **零重型云 SDK 依赖**:基于 Node.js 原生 `node:crypto` 与 `fetch` 实现,安装体积小、进程启动快。
- **完整参数与结果解析**:支持 `SearchPro`(版本 `2025-05-08`)全部检索参数,自动解析 `Pages` 中的 JSON 条目,支持通过 `include_content` 控制是否返回完整正文以节省上下文 Token。
- **延迟校验凭证**:未配置密钥时仍可正常完成 MCP `initialize` 与 `tools/list` 握手,仅在实际调用工具时返回清晰报错信息。

---

## 前置准备与两种对接方式详解

在配置本 MCP Server 前,请确保:
1. 已拥有腾讯云账号并完成**个人实名认证或企业认证**,且账号处于**未欠费**状态。
2. 已前往 **[元宝搜索控制台](https://console.cloud.tencent.com/wsapi/index)** 概览页面完成服务开通(可根据需求开通极速版、标准版或旗舰版资源包/后付费)。
3. 本地运行环境已安装 **Node.js `>= 20.0.0`**。

> **注意**:腾讯云元宝搜索的两套凭证**不可混用**:`sk-` 开头的是「服务 API KEY」,`AKID` 开头的是云 API「SecretId」。本工具会根据你配置的环境变量自动匹配正确的请求地址与鉴权方式。

### 方式一:服务 API KEY 方式(推荐,最简单)

适合个人开发者快速接入、AI 客户端本地配置,无需计算云 API 签名。

1. **开通服务**:登录 [元宝搜索控制台](https://console.cloud.tencent.com/wsapi/index),在「概览」页开通元宝搜索服务。
2. **(若使用子账号)先授予 CAM 权限**:
   - 使用子账号创建或管理服务 API KEY 前,必须由**主账号**前往 [访问管理控制台(CAM)](https://console.cloud.tencent.com/cam) ->「用户列表」-> 找到目标子账号 ->「权限」->「关联策略」,为该子账号授予 **元宝搜索(WSA)全读写访问权限**。
3. **创建 API KEY**:
   - 进入 [元宝搜索控制台](https://console.cloud.tencent.com/wsapi/index) 的「概览 > 服务 API KEY 方式」界面,点击 **创建 API KEY**。
   - 输入密钥名称并确认,在弹窗中**立即复制或下载 CSV 保存**。
   - **重要限制**:
     - 每个主账号或子账号(`subuin`)最多同时持有 **3 个** 有效 API KEY。
     - 明文 API KEY 仅在创建时展示一次,关闭弹窗后无法再次查询,若遗失只能删除后重建。
4. **配置环境变量**:只需设置 `TENCENTCLOUD_WSA_APIKEY=<你的 sk- 密钥>`。

官方参考文档:[元宝搜索 - 服务 API KEY 方式](https://cloud.tencent.com/document/product/1806/130615)

---

### 方式二:腾讯云标准方式(SecretId + SecretKey)

适合已有腾讯云云 API 密钥体系、需要接入 STS 临时安全凭证或通过 CAM 精细化管控接口权限的场景。

1. **开通服务**:确保已在 [元宝搜索控制台](https://console.cloud.tencent.com/wsapi/index) 开通服务。
2. **获取 `SecretId` 与 `SecretKey`**:
   - **使用主账号密钥(仅建议本地测试)**:登录 [访问管理 - API 密钥管理](https://console.cloud.tencent.com/cam/capi),点击 **新建密钥**,保存生成的 `SecretId`(`AKID...` 开头)与 `SecretKey`(也可点击下载 CSV)。
     > 注:2023 年 11 月 30 日起新建的密钥,其 `SecretKey` 仅在创建时展示一次,后续不可查回。
   - **使用子账号密钥(推荐用于生产/团队分发)**:
     1. 主账号前往 [CAM 用户列表](https://console.cloud.tencent.com/cam/user) 新建子用户,开启「编程访问」以生成子账号专属的 `SecretId` 与 `SecretKey`。
     2. **必须为子账号授权**:新建子账号默认没有任何资源权限,直接调用会报 `UnauthorizedOperation` / 未授权错误。主账号需在「用户详情 > 权限 > 关联策略」中为该子账号授权:
        - **预设策略**:搜索并关联 **元宝搜索(WSA)全读写访问权限**(或只读/对应产品策略)。
        - **自定义策略(最小权限)**:在 [CAM 策略管理](https://console.cloud.tencent.com/cam/policy) 中点击「新建自定义策略」->「按策略语法创建」-> 选择空白模板,授予 `wsa:SearchPro` 操作权限后关联到对应子账号。
        ```json
        {
          "version": "2.0",
          "statement": [
            {
              "effect": "allow",
              "action": ["wsa:SearchPro"],
              "resource": ["*"]
            }
          ]
        }
        ```
   - **(可选)使用 STS 临时凭证**:若通过角色扮演获取临时密钥,需同时提供临时 `TENCENTCLOUD_SECRET_ID`、`TENCENTCLOUD_SECRET_KEY` 以及 `TENCENTCLOUD_TOKEN`。
3. **配置环境变量**:设置 `TENCENTCLOUD_SECRET_ID` 与 `TENCENTCLOUD_SECRET_KEY`(注意不要同时设置 `TENCENTCLOUD_WSA_APIKEY`,或显式设置 `TENCENTCLOUD_WSA_AUTH_MODE=tc3`)。

官方参考文档:
- [元宝搜索 - 腾讯云标准方式](https://cloud.tencent.com/document/product/1806/121802)
- [元宝搜索 - 请求结构与接入域名](https://cloud.tencent.com/document/product/1806/121814)

---

## 安装与使用

### 直接通过 npx 使用(推荐)

无需手动克隆或构建,在支持 MCP 的客户端配置中直接通过 `npx -y @suhoan/yuanbao-search-mcp` 启动即可。

### 从源码构建

```bash
npm install
npm run build
```

构建完成后会在 `dist/` 目录生成入口文件 `dist/index.js`。

---

## 环境变量说明

| 变量名 | 必填 | 默认值 | 说明 |
| :--- | :--- | :--- | :--- |
| `TENCENTCLOUD_WSA_APIKEY` | 方式一必填 | - | 服务 API KEY(`sk-` 开头)。配置后默认优先走 API KEY 方式 |
| `TENCENTCLOUD_SECRET_ID` | 方式二必填 | - | 腾讯云 API `SecretId`(`AKID` 开头) |
| `TENCENTCLOUD_SECRET_KEY` | 方式二必填 | - | 腾讯云 API `SecretKey` |
| `TENCENTCLOUD_TOKEN` | 否 | - | 临时安全凭证 STS Token(仅方式二使用临时密钥时填写) |
| `TENCENTCLOUD_WSA_AUTH_MODE` | 否 | 自动推断 | 强制指定鉴权方式:`apikey` 或 `tc3`。默认:有 `TENCENTCLOUD_WSA_APIKEY` 时走 `apikey`,否则走 `tc3` |
| `TENCENTCLOUD_WSA_ENDPOINT` | 否 | 按模式自动选择 | 自定义接入域名:`apikey` 模式默认为 `api.wsa.cloud.tencent.com`;`tc3` 模式默认为 `wsa.tencentcloudapi.com`(可按需替换为区域域名,如 `wsa.ap-guangzhou.tencentcloudapi.com`) |
| `TENCENTCLOUD_TIMEOUT_MS` | 否 | `15000` | HTTP 请求超时时间(毫秒) |

---

## MCP 客户端接入配置

在 ZCode、Claude Desktop、Cursor 等支持 `stdio` MCP 的客户端配置中加入以下内容(如使用本地源码构建,也可将 `command` 设为 `node`、`args` 设为本机 `dist/index.js` 的绝对路径):

### 使用方式一(API KEY 方式,推荐)

```json
{
  "mcpServers": {
    "yuanbao-search-mcp": {
      "command": "npx",
      "args": ["-y", "@suhoan/yuanbao-search-mcp"],
      "env": {
        "TENCENTCLOUD_WSA_APIKEY": "your_wsa_api_key"
      }
    }
  }
}
```

### 使用方式二(SecretId + SecretKey 标准签名方式)

```json
{
  "mcpServers": {
    "yuanbao-search-mcp": {
      "command": "npx",
      "args": ["-y", "@suhoan/yuanbao-search-mcp"],
      "env": {
        "TENCENTCLOUD_SECRET_ID": "your_secret_id",
        "TENCENTCLOUD_SECRET_KEY": "your_secret_key"
      }
    }
  }
}
```

---

## 工具说明:`yuanbao_search`

| 参数 | 类型 | 必填 | 说明 |
| :--- | :--- | :--- | :--- |
| `query` | `string` | 是 | 搜索关键词,例如 `"今天北京的天气"` |
| `mode` | `0 \| 1 \| 2` | 否 | 检索类型(极速版不可用):`0` 全网检索(默认)、`1` 权威垂类、`2` 混合检索 |
| `site` | `string` | 否 | 域名过滤:指定单个域名(如 `"qq.com"`),或排除最多 5 个域名(如 `"exclude:qq.com\|sohu.com"`) |
| `cnt` | `10 \| 20 \| 30 \| 40 \| 50` | 否 | 返回结果条数(极速版不可用) |
| `industry` | `'gov' \| 'news' \| 'acad' \| 'finance'` | 否 | 垂直行业过滤(极速版不可用):政务、新闻、学术、金融 |
| `freshness` | `string` | 否 | 时间过滤(不可叠加):`d[1-30]`(近 N 天)、`m[1-12]`(近 N 月)、`y[1-5]`(近 N 年)、`yyyy-mm-dd`(单日)、`yyyy-mm-dd,yyyy-mm-dd`(日期区间) |
| `deeplinks` | `boolean` | 否 | 是否返回站点子链接(仅旗舰版支持,默认 `false`,最多 10 条) |
| `include_content` | `boolean` | 否 | 是否输出完整网页正文 `content`(若接口返回),默认 `false`(仅输出精简摘要以节省上下文) |

> **档位提示**:元宝搜索分为极速版(`lite`)、标准版(`standard`)和旗舰版(`flagship`)。极速版仅支持基础检索与 `site` / `freshness` 等基础能力,`mode`、`cnt`、`industry`、`deeplinks` 在极速版下会被服务端忽略或不可用。

---

## 常见错误排查

- **`UnauthorizedOperation` / `AuthFailure.*`**:
  - API KEY 模式:检查 `TENCENTCLOUD_WSA_APIKEY` 是否正确且未被删除,或确认环境变量没有意外误填成 `SecretId`。
  - 标准签名模式:检查 `SecretId` / `SecretKey` 是否正确、本机系统时间与标准 UTC 时间差是否超过 5 分钟、子账号是否已在 CAM 授权元宝搜索(`wsa`)权限。
- **`ResourceNotFound`**:当前账号尚未在 [元宝搜索控制台](https://console.cloud.tencent.com/wsapi/index) 开通元宝搜索服务。
- **`ResourceUnavailable`**:账号可能存在欠费或资源包已耗尽,请检查腾讯云账号账单与资源包余量。
- **`RequestLimitExceeded`**:触发 QPS 限频(参考文档:极速版 20 QPS、标准版 20 QPS、旗舰版 5 QPS)。

---

## 开发与测试

```bash
# 编译并运行全部单元测试与内存 MCP 集成测试
npm test
```

## License

Apache License 2.0 — Copyright 2026 Wang Zefeng. 详见 [LICENSE](./LICENSE)。