qwenpaw-deepseek-search-mcp

QwenPaw 的 DeepSeek 搜索与抓取 MCP 服务器。安装后，QwenPaw 里的 agent 会多出两个工具：

如果 QwenPaw 里已经配置好 DeepSeek 提供商（能正常对话即可），安装后不需要再填 API key。服务器会读取 QwenPaw 保存的 provider key 并解密使用。实现方式见 免填 key 的处理。

目录

• 工作原理

• 安装到 QwenPaw

• 验证

• key 解析

• 工具参考

• 计费

• 排障

• 复用与改造

• 目录结构

• 安全

Related MCP server: tinyfish-web-mcp

工作原理

QwenPaw 如何加载

┌──────────────────────────┐
│ QwenPaw                  │
│  agent（default / 其他） │
│    │                     │
│    ├─ drivers/mcp/*.yaml │  配置启动命令、参数、env、暴露策略
│    │        │            │
│    │        ▼            │
│    │   QwenPaw 管理 → MCP 卡片（显示为 deepseek）
│    │        │            │
│    │        ▼  按需启动子进程
│    │   ┌──────────┐  stdin/stdout  ┌──────────────────┐
│    └──►│ server.py│◄──────────────►│ Agent 的工具列表 │
│        │ FastMCP  │   JSON-RPC     └──────────────────┘
│        └────┬─────┘
└─────────────┼──────────────┘
              │ HTTPS POST
              ▼
      api.deepseek.com/v1/tools/search | /v1/tools/fetch

• 服务器按需启动。QwenPaw 在需要时运行 python server.py，通过 stdio 收发 JSON-RPC，调用结束后进程退出，不占端口，也不需要守护进程或反向代理。

• 管理页里一张卡片对应一个服务器进程。deepseek 卡片包含 deepseek_search 和 deepseek_fetch 两个工具，可以在卡片的「配置」中查看。

• 工具名会带前缀，agent 侧看到的是 deepseek__deepseek_search。前缀来自 MCP 客户端名，同时安装多个同类服务器时不会冲突。

一次工具调用的过程

以 deepseek_search 为例，相关代码都在 server.py：

1. 注册：@mcp.tool() 装饰 deepseek_search()，FastMCP 根据函数签名和 docstring 生成 tools/list 的 JSON Schema。参数名、类型、默认值和描述都来自函数定义，不需要手写 schema。

2. 参数整理：lang 拼成 lang:<值> 追加到 query；count 限制在 1 到 50；ori_question 截断到 128 字符。

3. 发起请求：_post("/v1/tools/search", payload) 带上 Authorization: Bearer <key>，以 JSON 形式 POST。超时由 DEEPSEEK_TIMEOUT 控制，默认 60 秒。

4. 错误处理：HTTP 4xx/5xx 保留上游返回的 body，输出 {"error": "HTTP 401", "detail": {...}}；网络异常输出 {"error": "URLError: ..."}。agent 可以直接读到失败原因。

5. 裁剪字段：上游每条结果有十几个字段，这里只保留 8 个（title、url、summary、snippet、site_name、date、authority、rerank_score），减少上下文占用。

6. 序列化：json.dumps(..., ensure_ascii=False)，中文按原样输出。

deepseek_fetch 使用同样的流程，请求体只有 {"url": ...}，返回 {"title", "content"}。

key 解析

resolve_api_key() 按以下顺序查找，命中即返回：

免填 key 的处理

QwenPaw 将 provider 的 key 加密保存在：

~/.qwenpaw.secret/providers/builtin/deepseek.json
        └── { "api_key": "ENC:xxxx..." }

带 ENC: 前缀的内容是密文，直接用于请求会返回 401。_decrypt_if_needed() 按以下逻辑处理：

1. 没有 ENC: 前缀，按明文返回。

2. 有前缀且本机安装了 QwenPaw，调用 qwenpaw.security.secret_store.decrypt 解密。

3. 有前缀但解密失败（缺少 master key 或版本不匹配），返回空字符串，继续尝试下一个来源。

resolve_api_key() 只有在前两级都为空时才会读取这份 secret。没有配置 DeepSeek 提供商的环境不会命中第 3 级，最终会进入第 4 级并给出明确的错误信息。

安装到 QwenPaw

准备

git clone https://github.com/BillYuan01/qwenpaw-deepseek-search-mcp.git
cd qwenpaw-deepseek-search-mcp

python3 -m venv .venv
. .venv/bin/activate            # Windows: .venv\Scripts\activate
pip install -r requirements.txt

需要 Python 3.10 以上版本。

配置 driver

每个 agent 有独立的 MCP 配置目录：

~/.qwenpaw/workspaces/<agent-id>/drivers/mcp/<名字>.yaml

例如 default agent 对应 ~/.qwenpaw/workspaces/default/drivers/mcp/deepseek_search.yaml。新建该文件：

name: deepseek_search
protocol: mcp
endpoint:
  transport: stdio
  command: /absolute/path/to/qwenpaw-deepseek-search-mcp/.venv/bin/python
  args:
    - /absolute/path/to/qwenpaw-deepseek-search-mcp/server.py
  cwd: /absolute/path/to/qwenpaw-deepseek-search-mcp
  env: {}
credentials: {}
config:
  display_name: deepseek
  description: DeepSeek 官方 Search / Fetch API（网页检索 + 正文抓取）
enabled: true
policy:
  default_effect: deny
  rules:
    - subject: '*'
      effect: ask
      target:
        kind: tool
        name: '*'
      principal:
        source_type: '*'
        source_value: '*'
        subject_type: '*'
        subject_value: '*'
      condition: null

• env 留空。如果 QwenPaw 已配置 DeepSeek 提供商，第 3 级会自动命中。

• command 和 args 使用绝对路径。QwenPaw 启动子进程时的工作目录不确定。

• policy 控制工具暴露和审批。上面的配置是默认拒绝、调用时询问，可以按需要调整。

界面确认

打开 QwenPaw 管理 → MCP，应看到名为 deepseek 的卡片：

• 标注「本地 stdio」

• 开关处于打开状态

• 点「配置」可以看到 deepseek_search 和 deepseek_fetch 两项，均为勾选状态

该页面不会自动轮询。从外部修改 yaml 后，需要刷新页面才能看到新卡片。

重启会话

MCP 工具在会话启动时注入。已经在运行的会话看不到新工具，新建会话即可，不需要重启 QwenPaw 服务。

验证

按成本从低到高：

# 只检查 key 来源，不产生调用费用
python server.py --check-key
# OK   来源: qwenpaw:provider   长度: 35

# 完整链路：list_tools + search + fetch，约 ¥0.01
python test_client.py
# key 来源: qwenpaw:provider（长度 35）
# tools: ['deepseek_fetch', 'deepseek_search']
# search ok: 3 results
# fetch ok: Example Domain

# 在 QwenPaw 新建会话中测试
# 「用 deepseek_search 查一下今天的 AI 新闻」

--check-key 只打印来源和长度，不打印 key 本身。test_client.py 使用官方 mcp 客户端加 stdio_client，连接方式与 QwenPaw 一致。

工具参考

deepseek_search

返回：

{
  "results": [
    {
      "title": "…",
      "url": "https://…",
      "summary": "…",
      "snippet": "…",
      "site_name": "…",
      "date": "2026-01-01",
      "authority": "…",
      "rerank_score": 0.87
    }
  ]
}

deepseek_fetch

返回：

{ "title": "页面标题", "content": "# Markdown 正文……" }

两个工具出错时都返回 {"error": "...", "detail": ...}。

计费

• 官方定价：5 元 / 1000 次成功请求，search 与 fetch 同价，单次约 ¥0.005。

• 计费规则以 DeepSeek 官方文档 为准。本项目只做封装，不加价，也不转发到第三方。

• count 和 need_content 不影响单价，一次请求计一次。

排障

复用与改造

这套结构可以复用到其他 HTTP API：

1. 更换后端：修改 BASE_URL（也支持环境变量 DEEPSEEK_BASE_URL）和 _post() 中的 path。

2. 增加工具：新增一个 @mcp.tool() 函数，签名和 docstring 会直接生成 schema。

3. 修改 key 来源：在 resolve_api_key() 中插入一级，保持先具体后通用的顺序。

4. 多实例：同一个 server.py 可以配置多次，用不同的 env（不同 key 或 base_url）区分，界面中显示为两张独立卡片。

目录结构

.
├── server.py                   # key 解析、两个工具、错误处理
├── test_client.py              # 冒烟测试，使用官方 mcp 客户端直连 stdio
├── requirements.txt            # mcp>=1.0.0
├── examples/
│   └── qwenpaw-driver.yaml     # driver 配置模板
├── AGENTS.md                   # 代码修改约定
├── LICENSE                     # MIT
└── README.md

安全

• key 通过环境变量、文件或 QwenPaw secret 注入，代码中没有硬编码凭据。

• .gitignore 包含 .env、.venv/、__pycache__/。

• 服务器除读取 key 外不访问本地文件，网络请求只发往 api.deepseek.com。

License

MIT

标准 stdio MCP 服务器，任何 MCP 客户端都可以运行 python server.py。