Skip to main content
Glama
yuanbao-search-mcp

yuanbao-search-mcp

by Neglecton

@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 握手,仅在实际调用工具时返回清晰报错信息。


Related MCP server: Brave Jev MCP

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

在配置本 MCP Server 前,请确保:

  1. 已拥有腾讯云账号并完成个人实名认证或企业认证,且账号处于未欠费状态。

  2. 已前往 元宝搜索控制台 概览页面完成服务开通(可根据需求开通极速版、标准版或旗舰版资源包/后付费)。

  3. 本地运行环境已安装 Node.js >= 20.0.0。

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

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

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

  1. 开通服务:登录 元宝搜索控制台,在「概览」页开通元宝搜索服务。

  2. (若使用子账号)先授予 CAM 权限:

    • 使用子账号创建或管理服务 API KEY 前,必须由主账号前往 访问管理控制台(CAM) ->「用户列表」-> 找到目标子账号 ->「权限」->「关联策略」,为该子账号授予 元宝搜索(WSA)全读写访问权限。

  3. 创建 API KEY:

    • 进入 元宝搜索控制台 的「概览 > 服务 API KEY 方式」界面,点击 创建 API KEY。

    • 输入密钥名称并确认,在弹窗中立即复制或下载 CSV 保存。

    • 重要限制:

      • 每个主账号或子账号(subuin)最多同时持有 3 个 有效 API KEY。

      • 明文 API KEY 仅在创建时展示一次,关闭弹窗后无法再次查询,若遗失只能删除后重建。

  4. 配置环境变量:只需设置 TENCENTCLOUD_WSA_APIKEY=<你的 sk- 密钥>。

官方参考文档:元宝搜索 - 服务 API KEY 方式


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

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

  1. 开通服务:确保已在 元宝搜索控制台 开通服务。

  2. 获取 SecretId 与 SecretKey:

    • 使用主账号密钥(仅建议本地测试):登录 访问管理 - API 密钥管理,点击 新建密钥,保存生成的 SecretId(AKID... 开头)与 SecretKey(也可点击下载 CSV)。

      注:2023 年 11 月 30 日起新建的密钥,其 SecretKey 仅在创建时展示一次,后续不可查回。

    • 使用子账号密钥(推荐用于生产/团队分发):

      1. 主账号前往 CAM 用户列表 新建子用户,开启「编程访问」以生成子账号专属的 SecretId 与 SecretKey。

      2. 必须为子账号授权:新建子账号默认没有任何资源权限,直接调用会报 UnauthorizedOperation / 未授权错误。主账号需在「用户详情 > 权限 > 关联策略」中为该子账号授权:

        • 预设策略:搜索并关联 元宝搜索(WSA)全读写访问权限(或只读/对应产品策略)。

        • 自定义策略(最小权限):在 CAM 策略管理 中点击「新建自定义策略」->「按策略语法创建」-> 选择空白模板,授予 wsa:SearchPro 操作权限后关联到对应子账号。

        {
          "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)。

官方参考文档:


安装与使用

直接通过 npx 使用(推荐)

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

从源码构建

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 方式,推荐)

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

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

{
  "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:当前账号尚未在 元宝搜索控制台 开通元宝搜索服务。

  • ResourceUnavailable:账号可能存在欠费或资源包已耗尽,请检查腾讯云账号账单与资源包余量。

  • RequestLimitExceeded:触发 QPS 限频(参考文档:极速版 20 QPS、标准版 20 QPS、旗舰版 5 QPS)。


开发与测试

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

License

Apache License 2.0 — Copyright 2026 Wang Zefeng. 详见 LICENSE。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform intelligent web searches using the Baidu Wenxin API, supporting multiple models, search modes, and providing search results with reference sources.
      6
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI clients to perform web searches and receive intent-filtered LLM context snippets with unhelpful pages and navigation removed, while preserving source links for citation.
      8
      28 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables MCP clients to run web searches via DeepSeek's open platform API, with optional web page fetching that returns Markdown content, and supports query syntax for source, language, and time filters.
      1
      74 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP-capable AI clients to run web searches through DeepSeek's search engine and fetch individual webpages as Markdown. Search results include relevance scores, authority, and publication times, and support advanced query syntax such as site:, lang:, and date filters.
      2
      51 npm
      Apache 2.0