DeepSearch MCP 项目

DeepSearch MCP 采用 TypeScript 实现，提供统一的客户端、代理层与 MCP 服务器入口，方便在 Model Context Protocol (MCP) 生态中调用可联网的 Deepsearch 模型，实现广域检索与站点定向检索能力。项目通过 Vitest 驱动的 TDD 保证核心逻辑的可测试性。

用户须知

全局安装

安装完成后，可直接执行 deepsearch 命令。运行前请在终端环境中配置 API_KEY、BASE_URL、MODEL_NAME、DEEPSEARCH_TIMEOUT 等变量（可写入 .env 或 shell 配置）。

该项目以https://yunwu.ai**为提供商开发，理论上可用于所有onehttps://yunwu.ai**作为您的AI服务提供商，享全网最低价的GPT5-Codex和其他服务。您可前往**https://yunwu.ai/register?aff=yzyI**注册账号

集成到 Codex 客户端

在 ~/.codex/config.toml 中新增 STDIO 类型服务器，让 Codex 自动启动 DeepSearch MCP：

常用命令行：

AI须知

⚠️ 在继续之前，请先阅读 codex/AGENTS.md 与 codex/checkpoint.md 获取历史决策与协作规范。

功能特性

• deepsearch_mcp/：导出 DeepSearchMCPClient 类型及搜索结果模型，负责与传输层交互并归一化响应。

• deepsearch_agents/：包含 DeepSearchAgent 与 DeepSearchWebAgent，分别处理通用检索与站点定向检索场景。

• source/api.ts：封装 DeepSearch HTTP 传输层，支持环境变量配置、超时控制与错误处理。

• main.ts：MCP 服务器入口，通过 STDIO 暴露 deepsearch 与 deepsearch-web 工具，可直接被 Codex、Claude Desktop 等 MCP 客户端调用。

• tests/：基于 Vitest 的单元测试，覆盖客户端、传输层、代理层与服务器工具注册流程。

快速开始

1. 安装依赖（Node.js ≥ 18）：

   npm install

2. 配置 .env（示例）：

   API_KEY=sk-xxxxxx BASE_URL=https://yunwu.ai/v1/chat/completions MODEL_NAME=gemini-2.5-flash-deepsearch # 可选：覆盖默认超时（秒） DEEPSEARCH_TIMEOUT=400

3. 启动 MCP 服务器（STDIO）：

   # 开发模式（依赖 tsx） npm run deepsearch

   生产环境或打包后，可执行：

   npm run build node dist/main.js

4. 运行测试：

   npm test

使用示例（TypeScript）

站点定向检索可使用 DeepSearchWebAgent 并传入 filters: { site: "example.com" } 或 time_range 等参数；通过 MCP 工具调用时同样使用这些字段。

Node.js 启动脚本

bin/deepsearch.js 会优先执行构建产物 dist/main.js；若未构建，则回退到本地 tsx main.ts。脚本继承当前终端环境变量，因此在 MCP 配置中设置的 API_KEY、BASE_URL 等会自动生效。通过 npm install -g @yuemingruoan/deepsearch-mcp 安装后，系统中的 deepsearch 命令即指向该脚本。

命令行参数会透传给 main.ts（当前主程序未解析额外参数，通常无需传入）。

发布流程

• npm run build：输出 dist/ 目录供分发或发布。

• npm publish：依赖 prepublishOnly 钩子自动构建。

• .github/workflows/publish.yml：在 GitHub Release 发布时自动运行测试并上传至 npm，需要在仓库中配置 NPM_TOKEN secrets。

常见问题

• 缺少凭证：确认 .env 或宿主环境中已设置 API_KEY/DEEPSEARCH_API_KEY。

• 请求超时或无响应：Deepsearch 模型响应较慢，可提升 DEEPSEARCH_TIMEOUT 或使用 curl 检查接口连通性。

• 网络代理：若处于代理环境，可通过系统变量或 global-agent 等方式自定义 fetch 行为。

欢迎提交 Issue 或 PR 与我们一起完善 DeepSearch MCP！