Odysseus Web MCP

Odysseus Web MCP — 面向 AI 助手的安全网页搜索与抓取服务

Odysseus Web MCP 是一个独立的模型上下文协议（MCP）服务，可安全地搜索公开网页并抓取 URL。它通过 stdio 在本地运行，为兼容 MCP 的 AI 助手提供两个检索工具：web_search 用于发现来源，web_fetch 用于抓取并提取公开 URL 的内容。

它专为 Claude Code、Cursor 和 Codex 等客户端打造，结合了搜索提供商回退机制、易读的 HTML/PDF/文本提取、可选的 JavaScript 渲染，以及包括 DNS 验证和重定向复查在内的 SSRF 防护。

功能

• 通过提供商回退机制搜索公开网页，并返回排序后的来源及其归属信息。
• 抓取公开 URL 并提取 HTML、PDF 和文本内容。
• 通过公共网络检查、DNS 验证和重定向重新验证来防范 SSRF。
• 返回有长度限制、以证据为导向的内容，包括游标、质量信号和发现的链接。
• 可选地在隔离的 Playwright 中渲染大量使用 JavaScript 的页面。

几分钟内完成安装

要求：Python 3.11+ 和 uv。

# after downloading/extracting this folder (or cloning your copy)
cd odysseus-web-mcp
uv venv .venv
uv pip install -e '.[dev]'
./run-web-mcp.sh

服务通过 stdio 通信，因此不会开放 Web 端口，也无需安装到宿主应用的 Python 环境中。 在 MCP 客户端中注册启动器的绝对路径：

{
  "name": "odysseus-web-mcp",
  "command": "/absolute/path/to/odysseus-web-mcp/run-web-mcp.sh",
  "args": [],
  "cwd": "/absolute/path/to/odysseus-web-mcp"
}

启动器会自动使用软件包的 .venv。状态默认存储在 ~/.local/share/odysseus-web-mcp；设置 WEB_MCP_DATA_DIR 可将其存放到其他位置。默认回退路径无需 API 密钥，不过也可以添加 Brave、Tavily 和 Serper 密钥以使用这些提供商。

两个工具

web_search

用于针对具体问题发现来源。它接受一到三个查询，以及可选的模式、垂直领域和时效性控制参数。

{
  "queries": "Model Context Protocol Python SDK",
  "mode": "discovery",
  "vertical": "general"
}

响应包含排序后的 URL、标题、摘要、提供商尝试情况、缓存状态、纯文本展示内容，以及一个 evidence_id。宿主可以将返回的任意 URL 直接传给 web_fetch。

web_fetch

用于读取已知的公开 URL，或批量读取数量受限的 URL。

{
  "url": "https://example.com",
  "focus": "the page's purpose",
  "render": "auto"
}

它会返回提取的文本、标题和文档类型、内容质量、发现的链接、重定向历史记录、HTTP 状态、截断/续传元数据，以及一个 evidence_id。默认情况下，在传输开始前会拒绝指向私有地址和特殊用途地址的请求。

示例：Agent 如何使用 MCP

Agent 通常会通过两步检索循环使用这些工具：先搜索，再抓取想要查看的来源。以下内容展示了一次真实 MCP 交互的结构；为便于阅读，ID 和结果文本均已缩略。

1. Agent 搜索来源

{
  "name": "web_search",
  "arguments": {
    "queries": "official Model Context Protocol architecture",
    "mode": "grounding",
    "vertical": "general"
  }
}

MCP 会返回一个包含结构化 JSON 的文本内容块：

{
  "status": "ok",
  "query": "official Model Context Protocol architecture",
  "sources": [
    {
      "title": "Architecture - Model Context Protocol",
      "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
      "snippet": "Understand the architecture and communication model...",
      "provider": "duckduckgo",
      "relevance_score": 1.0
    }
  ],
  "provider_attempts": {
    "searxng": "empty",
    "duckduckgo": "ok"
  },
  "evidence_id": "a1b2c3d4...",
  "exit_code": 0
}

2. Agent 抓取选定的来源

Agent 获取返回的 URL，并调用第二个工具：

{
  "name": "web_fetch",
  "arguments": {
    "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
    "focus": "How do clients and servers communicate?",
    "render": "auto"
  }
}

MCP 会返回有长度限制的提取证据：

{
  "success": true,
  "url": "https://modelcontextprotocol.io/docs/concepts/architecture",
  "final_url": "https://modelcontextprotocol.io/docs/concepts/architecture",
  "http_status": 200,
  "document_kind": "html",
  "content_quality": "good",
  "content": "The Model Context Protocol defines how clients and servers...",
  "links": [
    {
      "url": "https://modelcontextprotocol.io/docs/concepts/transports",
      "text": "Transports"
    }
  ],
  "evidence_id": "e5f6g7h8...",
  "exit_code": 0
}

现在，Agent 可以根据提取的内容回答用户，保留 evidence_id 以便追踪；如果页面长度超出输出预算，还可以使用返回的游标继续调用 web_fetch。

本地工作原理

MCP host ──stdio──▶ mcp_server.py
                       ├─ web_search → provider chain → ranked evidence
                       └─ web_fetch  → security → HTTP/extract/render → evidence

所有持久化状态都存储在 WEB_MCP_DATA_DIR 下。该软件包不会在运行时导入 Odysseus，也无法访问其凭据、数据库、记忆、浏览器配置文件、调度器或 Agent 循环。

请阅读完整的本地系统设计文档 docs/TECHNICAL_DESIGN.md，并查看 GIF 的录制方式 docs/INTERACTIVE_DEMO.md。

搜索提供方和配置

默认提供方链为：

SearXNG → Brave → Tavily → Serper → DuckDuckGo → Wikipedia → Bing

使用 WEB_MCP_SEARCH_PROVIDER_CHAIN 进行配置。可选凭据包括 DATA_BRAVE_API_KEY、TAVILY_API_KEY 和 SERPER_API_KEY。可参考 .env.example，但请将密钥保存在主机环境中，不要提交到代码库。

可选的浏览器路径默认处于禁用状态：

uv pip install -e '.[render]'
./.venv/bin/python -m playwright install chromium
export WEB_MCP_RENDER_ENABLED=true

分发与发现

该服务已发布在官方 MCP Registry 中，条目为 io.github.AceAtDev/odysseus-web-mcp。

对于 Claude Desktop 和其他兼容 MCPB 的客户端，请从 v0.1.0 GitHub Release 下载经过验证的 MCPB 发布包。 该软件包使用 uv 运行时解析声明的 Python 依赖项，不会附带特定机器的虚拟环境。

自行验证

该项目配有精简的测试套件和实时验证运行器：

./.venv/bin/python -m pytest -q
./.venv/bin/python tests/live_20_cases.py --output reports/live-20-cases.json

实时验证会通过真实 MCP 启动器执行 10 次搜索和 10 次抓取，并使用临时状态。最新的验证记录见 VERIFICATION.md。

如需通过新的实时调用重新录制终端预览（需要 ImageMagick 的 convert 命令）：

./.venv/bin/python demos/record_terminal_demos.py

每个 GIF 都特意控制在 10 秒以内，展示真实的 MCP 握手和结果格式，而非静态的产品示意图。

项目边界

此软件包是一个检索基础组件，不是 Agent 循环、通用爬虫、调度器、记忆存储、浏览器配置文件管理器或凭据保险库。它旨在作为独立 MCP 服务下载并连接。

许可证与状态

这是 Odysseus 网页搜索/抓取功能的独立提取工作区。源代码到模块的映射见 MIGRATION_MAP.md，当前基于证据的状态见 VERIFICATION.md。