Agent Bridge

概览

Agent Bridge 让 AI Agent（Claude Code、Cursor、Cowork 等）远程控制 Web2MD Chrome 扩展批量转换 URL——尤其是 Reddit、JS 渲染页面和需要登录的页面，这些页面服务端 API 都拿不到。 AI Agent 不走 Web2MD API（Reddit 会拦截），而是通过 Native Messaging 向你本地的 Chrome 扩展发指令。扩展用你的真实浏览器会话——带着你的 cookie 和登录状态——在后台标签页打开每个页面，提取内容、转成 Markdown 并返回结果。

Agent Bridge 需要 PRO 套餐，并在你的机器上安装 native messaging host。扩展需要在 Chrome 中处于启用状态。

架构

AI Agent ←MCP/stdio→ MCP Server ←TCP:12315→ Native Host ←NM→ Chrome Extension → Any Website

组件	角色
AI Agent	Claude Code、Cursor、Cowork——调用 MCP 工具
MCP Server	把 MCP 工具调用翻译成 TCP 消息
Native Host	在 TCP 和 Chrome Native Messaging 之间做中继
Chrome 扩展	打开标签页、提取 HTML、转成 Markdown

所有通信都是本地的——不会有任何数据离开你的机器。Native Host 只监听 localhost:12315。

安装配置

第一步：构建 MCP Server

cd packages/mcp-server
pnpm build

第二步：安装 Native Messaging Host

cd packages/mcp-server
./install.sh <your-extension-id>

在 chrome://extensions 开启开发者模式后可以找到扩展 ID。找到 Web2MD，复制 ID 字符串（例如 ijmgpkkfgpijifldbjafjiapehppcbcn）。

安装完成后必须完全退出 Chrome（Mac 上按 Cmd+Q）再重新打开。Chrome 只在启动时读取 Native Messaging 清单——仅仅重载扩展是不够的。

安装脚本会：

把 host 文件复制到 ~/.web2md/（避开 macOS 对 ~/Desktop 的 TCC 限制）
解析 node 的绝对路径（Chrome 启动时 PATH 极简）
把 NM 清单写入 Chrome 的 NativeMessagingHosts 目录

第三步：配置 MCP

Claude Code
Cursor
Claude Desktop

添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

添加到你的 Claude Desktop 配置：

{
  "mcpServers": {
    "web2md-agent": {
      "command": "node",
      "args": ["/path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "WEB2MD_API_KEY": "w2m_your_key_here"
      }
    }
  }
}

第四步：验证

在 Chrome 打开 chrome://extensions → 点击 Web2MD 的 “Service Worker” 链接 → 查看 Console：

[Web2MD] Service worker started
[Web2MD] Connected to native host
[Web2MD] Native host TCP relay ready on port 12315

看到这三行，Agent Bridge 就跑通了。

可用工具

agent_convert

用 Chrome 扩展转换单个 URL。

参数	类型	说明
`url`	string	要转换的 URL

返回： Markdown 内容，附带标题、来源 URL、字数和阅读时长。 最适合： Reddit 帖子、需要登录的页面、JS 渲染的站点。

agent_batch_convert

批量转换最多 50 个 URL。URL 会依次处理——扩展在后台标签页打开一个页面，提取内容后关掉标签页，再处理下一个。

参数	类型	说明
`urls`	string[]	要转换的 URL 数组（最多 50 个）

返回： 每个 URL 的结果完成即流式返回，最后附上汇总。 最适合： 调研类工作流——批量转换 Reddit 帖子、HN 讨论或竞品页面，交给 AI 分析。

所有成功的转换都会自动存进你的控制台历史记录，并附带 AI 生成的摘要和标签。

使用示例

转换 Reddit 帖子

你： Convert this Reddit thread to Markdown: https://www.reddit.com/r/LangChain/comments/1siwh6q/…Agent： （调用 agent_convert） 这是转换后的帖子，含 7 条讨论法律文档 RAG 精度的评论……

批量转换做调研

你： Batch convert these 5 Reddit URLs and summarize the key takeaways:

Agent： （调用 agent_batch_convert） 5/5 个 URL 全部转换成功。以下是核心结论……

转换需要登录的页面

你： Convert my company’s internal wiki page at https://wiki.internal.com/architectureAgent： （调用 agent_convert） 由于你在 Chrome 里已登录该站点，我成功提取了完整内容……

支持的站点

Agent Bridge 使用与扩展相同的 16 个站点专用提取器：

站点	方式	需要标签页？
Reddit	JSON API	否
Hacker News	Algolia API	否
YouTube	Transcript API	否
arXiv	HTML 抓取	否
Twitter/X	DOM 提取	是
GitHub Issues/PRs	REST API	否
Medium	DOM 提取	是
Substack	DOM 提取	是
Wikipedia	DOM 提取	是
Stack Overflow	SE API	否
其他任意站点	完整页面 HTML	是

标记「否」的站点通过 API 调用转换——更快也更稳定，其余的走后台标签页。

故障排查

'Native host not installed' 或 'not found'

Chrome 还没加载 NM 清单。完全退出 Chrome（Cmd+Q）再重新打开。 仅仅重载扩展是不够的。

'Native host has exited' 立刻退出

Chrome 无法执行 host 脚本。常见原因：

找不到 node——重新运行 ./install.sh，它会使用 node 的绝对路径
host 在 TCC 受保护目录（~/Desktop、~/Documents）里——重新运行安装脚本把它移到 ~/.web2md/

MCP 报 'Agent connection error'

Native Host 的 TCP 服务没在运行。确认：

Chrome 已打开
Web2MD 扩展已加载
Service Worker 控制台显示 “TCP relay ready on port 12315”

'Failed to extract content from the page'

扩展未登录。在 Chrome 里打开 Web2MD 弹窗，登录你的 PRO 账户。

'Tab load timeout'

目标页面加载太慢，慢站点出现这种情况很正常。扩展每个标签页最多等 15 秒。Reddit 走 JSON API 提取器不需要标签页，所以 Reddit 上的超时通常意味着帖子 URL 无效（404）。

转换没出现在控制台历史记录里

历史保存需要扩展以 PRO 账户登录。保存是 fire-and-forget 的——如果 API 调用静默失败，转换就不会出现。检查你的认证 token 是否有效。

与 MCP Server 的区别

特性	MCP Server（`convert_url`）	Agent Bridge（`agent_convert`）
运行位置	服务端 API 调用	你本地的 Chrome 浏览器
Reddit 支持	❌ 被 Reddit 拦截	✅ 使用真实浏览器会话
需要登录的页面	❌ 无法访问	✅ 使用你的 cookie
JS 渲染页面	❌ 不执行 JavaScript	✅ 完整 Chrome 渲染
速度	更快（无标签页开销）	较慢（要打开真实标签页）
是否需要 Chrome 打开	否	是

经验法则： 公开页面用 convert_url；Reddit、需要认证的页面和重度依赖 JS 的站点用 agent_convert / agent_batch_convert。

快速上手

核心功能

进阶用法

套餐

概览

架构

安装配置

第一步：构建 MCP Server

第二步：安装 Native Messaging Host

第三步：配置 MCP

第四步：验证

可用工具

agent_convert

agent_batch_convert

使用示例

支持的站点

故障排查

与 MCP Server 的区别

​概览

​架构

​安装配置

​第一步：构建 MCP Server

​第二步：安装 Native Messaging Host

​第三步：配置 MCP

​第四步：验证

​可用工具

​agent_convert

​agent_batch_convert

​使用示例

​支持的站点

​故障排查

​与 MCP Server 的区别

概览

架构

安装配置

第一步：构建 MCP Server

第二步：安装 Native Messaging Host

第三步：配置 MCP

第四步：验证

可用工具

agent_convert

agent_batch_convert

使用示例

支持的站点

故障排查

与 MCP Server 的区别