Skip to main content
Glama
yuemingruoan

DeepSearch MCP

by yuemingruoan
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

DeepSearch MCP 项目

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

用户须知

全局安装

npm install -g @yuemingruoan/deepsearch-mcp

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

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

集成到 Codex 客户端

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

[mcp_servers.deepsearch]
command = "node"
args = ["/absolute/path/to/DeepSearch-MCP/bin/deepsearch.js"]
env = {
  "API_KEY" = "<你的 Deepsearch API Key>",
  "BASE_URL" = "https://yunwu.ai/v1/chat/completions",
  "MODEL_NAME" = "gemini-2.5-flash-deepsearch",
  "DEEPSEARCH_TIMEOUT" = "400"
}
startup_timeout_sec = 30
tool_timeout_sec = 120

常用命令行：

codex mcp list
codex mcp get deepsearch
codex mcp remove deepsearch

Related MCP server: qsearch

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）

import { DeepSearchAgent } from "deepsearch-mcp/deepsearch_agents/deepsearch";

const agent = new DeepSearchAgent();

const result = await agent.search("OpenAI 最新发布", { top_k: 3 });
for (const item of result.items) {
  console.log(item.title, item.url);
}

agent.close();

站点定向检索可使用 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 命令即指向该脚本。

npm run deepsearch -- --top_k 3
# 或者直接调用脚本
node ./bin/deepsearch.js
# 全局安装后可直接调用
deepsearch --top_k 3

命令行参数会透传给 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！

Available Tools

2 tools
deepsearchDeepSearch 通用检索B

使用 DeepSearch 模型执行广域检索并返回结构化结果,拥有比AI Agent内置搜索更好的搜索效果但更耗时，需要平衡需求

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
top_kNo
localeNo
filtersNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
itemsYes
metadataYes
usageYes

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full burden. It only mentions time-consuming nature. Lacks details on authentication, rate limits, or behavioral side effects. Minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with core action. Efficient and to the point. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no schema descriptions, and no output schema? Actually there is an output schema, but description only says 'structured results'. Missing details on parameter usage and result format. Incomplete for effective tool use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and description adds no parameter-specific information. The query parameter is implied but not explained. No guidance on top_k, locale, or filters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it uses DeepSearch model for broad search and returns structured results. It compares to built-in search, indicating its scope. However, it does not explicitly distinguish from sibling deepsearch-web.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description provides trade-off guidance: better results but more time-consuming, advising balance. This helps decide when to use vs. built-in search. No explicit exclusion or alternative mention for sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

deepsearch-webDeepSearch 定向检索B

针对站点或时间范围的 DeepSearch 定向检索，拥有比AI Agent内置搜索更好的搜索效果但更耗时，需要平衡需求

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
top_kNo
localeNo
filtersYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
itemsYes
metadataYes
usageYes

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It only notes the tool is slower, but does not disclose whether it is read-only, destructive, or other side effects. There is no mention of authentication or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but lacks structure. It does not use bullet points or separate sections for clarity, and it omits important details that could be included without much length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of 4 parameters including a nested object, and the presence of an output schema, the description is insufficient. It does not describe the output format, provide usage examples, or cover all parameters adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. It only hints at filters for site/time range, but does not explain query, top_k, locale, or the structure of the filters object. Users are left to infer parameter meanings from names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a targeted search for site or time range, and contrasts with built-in AI agent search in terms of quality and time cost. It distinguishes from sibling 'deepsearch' by implying this is more specialized.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions it is more time-consuming but better, implying use when quality is preferred over speed. However, it does not explicitly state when to avoid using it or directly compare to the sibling tool 'deepsearch'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv1.0.0
    • Changeddeepsearch2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
    • Changeddeepsearch-web2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
  2. 2 tool updates
    • First observeddeepsearch
    • First observeddeepsearch-web
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.2/5.0
Disambiguation4/5

The two tools are mostly distinct (one for broad search, one for site/time-targeted search), but both share the 'deepsearch' prefix and perform search operations, which could cause some confusion for an agent.

Naming Consistency5/5

Both tools follow a consistent 'deepsearch' prefix pattern, with the second adding a '-web' suffix to indicate specialization. Naming is predictable and clear.

Tool Count2/5

With only 2 tools for a search-focused server, the surface is extremely thin. A typical search server would require more tools for different query types, result handling, or configuration.

Completeness2/5

The server only offers two search variants, lacking obvious features like result retrieval, pagination, search history, or advanced filters. This is severely incomplete for a search domain.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • web-search-mcp

    hbhszy
    A
    license
    A
    quality
    D
    maintenance
    Enables real-time web search via DeepSeek's search-enhanced dialogue, providing search results as answers through MCP tools.
    1
    MIT

  • qsearch

    theYahia
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to perform web searches with full content retrieval and multi-engine provenance, including trust scoring and local corpus persistence, via MCP integration.
    3
    2
    Apache 2.0

  • groundlink-mcp

    ohhavefun
    A
    license
    A
    quality
    C
    maintenance
    Enables MCP hosts to perform cited web searches and receive source-bearing results with titles, URLs, snippets, and sources for evidence-grounded answers.
    1
    95
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yuemingruoan/DeepSearch-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server