MCP Integration

MCP Integration

事实来源：主仓 pr-88 @ a312645 的 src/souwen/integrations/mcp_server.py、src/souwen/integrations/mcp_http.py、src/souwen/web/fetch_providers/mcp.py，以及 Feature MCP。

把 SouWen 接到 Model Context Protocol 上有两个方向：

flowchart LR
    subgraph A[方向 1: SouWen as MCP Server]
        Cli[Claude Code · Cursor · Windsurf] --> SW[SouWen MCP Server]
        SW --> Tools[5 内置工具]
    end

    subgraph B[方向 2: SouWen as MCP Client]
        SF[souwen fetch -p mcp] --> Ext[外部 MCP Server]
        Ext --> FT[fetch tool]
    end

Loading

---

1. 方向 1：把 SouWen 工具暴露给 AI Agent

1.1 安装

pip install "souwen[mcp]"

1.2 stdio 启动（最常用）

python -m souwen.integrations.mcp_server

stdio MCP server 会从环境变量读取 SouWen 配置；典型组合：

SOUWEN_OPENALEX_EMAIL=you@example.com \
SOUWEN_TAVILY_API_KEY=tvly-xxx \
python -m souwen.integrations.mcp_server

1.3 接入 Claude Code

~/.config/claude/claude_desktop_config.json（macOS：~/Library/Application Support/Claude/）：

{
  "mcpServers": {
    "souwen": {
      "command": "python",
      "args": ["-m", "souwen.integrations.mcp_server"],
      "env": {
        "SOUWEN_TAVILY_API_KEY": "tvly-xxx",
        "SOUWEN_OPENALEX_EMAIL": "you@example.com"
      }
    }
  }
}

重启 Claude Desktop → 看 🔌 图标确认工具加载。

1.4 接入 Cursor

Settings → Features → MCP Servers → Add new：

{
  "name": "souwen",
  "command": "python",
  "args": ["-m", "souwen.integrations.mcp_server"]
}

1.5 接入 Windsurf

Windsurf Settings → MCP → 同上结构。

1.6 5 个内置工具

工具	输入	默认源
search_papers	query / sources / limit=5	openalex+arxiv+crossref
search_patents	query / sources / limit=5	google_patents
web_search	query / engines / limit=10	duckduckgo+bing
get_status	—	—
fetch_content	urls / provider="builtin"	builtin

返回都是 JSON（SearchResponse / FetchResponse），AI Agent 可以直接 parse。

1.7 HTTP MCP 端点（可选）

如需远程 MCP（容器内 SouWen + 远端 IDE）：

mcp_http_enabled: true
mcp_http_enable_sse: true            # 兼容老 SSE 客户端
mcp_http_stateless: true             # 适合无会话部署
mcp_http_json_response: true

启用后访问 /mcp 与 /mcp/sse，复用 Authentication 的 User/Admin Bearer Token。

---

2. 方向 2：把外部 MCP fetch 当 SouWen 的 fetch provider

如果你的组织已经有一个 MCP Server 提供 fetch 工具（内部缓存 / 私有抓取 / 浏览器池）：

mcp_server_url: https://mcp.example.com/mcp
mcp_transport: streamable_http        # 或 sse
mcp_fetch_tool_name: fetch            # 远端工具名（默认 fetch）
mcp_extra_headers:
  Authorization: Bearer ext-token
  X-Tenant: my-team

调用：

souwen fetch https://example.com -p mcp

from souwen.facade import fetch_content
resp = await fetch_content(["https://example.com"], provider="mcp")

SouWen 会用 MCP 协议调用远端 fetch 工具，把响应封装成 FetchResult。

---

3. CLI 速查

souwen mcp                                  # 输出 MCP server 配置（JSON）
python -m souwen.integrations.mcp_server    # 启 stdio MCP server

---

4. 排障

现象	修复
AI Agent 工具列表里看不到 souwen	1) pip install souwen[mcp] 装了？2) python -m souwen.integrations.mcp_server 单独跑能否启？3) MCP Client 是否重启
工具调用 timeout	内部 SouWen 默认源被卡 → 配 Key / 切代理
mcp provider 报错	检查 mcp_server_url 可达；mcp_extra_headers 完整；mcp_transport 与远端协议匹配
HTTP MCP 端点 404	mcp_http_enabled=true 是否启用；POST /api/v1/admin/config/reload
AI 用工具时一直返回空	看 server 日志 event=mcp_call；多半是默认源都没 Key

---

5. 端到端示例：Claude Code 当文献调研助手

1. 配 Claude Code 接入 SouWen MCP（见 §1.3）。
2. 同时配 SOUWEN_OPENALEX_EMAIL、SOUWEN_TAVILY_API_KEY、SOUWEN_JINA_API_KEY 到环境。
3. 在 Claude Code 里说："帮我用 souwen 搜 5 篇关于 transformer attention 的论文，挑一篇用 souwen.fetch_content 抓全文，做摘要。"
4. Claude 会按顺序调 souwen.search_papers → souwen.fetch_content，得到结构化结果再做综合分析。

---

6. 接下来

• Feature MCP — 功能视角
• Plugin Development — 写自己的 SouWen 插件，让 AI Agent 调用
• 主仓 api-reference.md#mcp-工具