内容
# mcp-readitall
基于 Go 的 [模型上下文协议](https://modelcontextprotocol.io)（MCP）服务器，可以获取任何网站——包括需要真实浏览器渲染的现代单页应用（SPAs）——并将页面转换为干净的 Markdown。它还支持每个主机的认证会话，因此您可以读取位于登录墙后面的内容。
服务器通过 **stdio** 进行 MCP 通信，设计用于与任何支持 MCP 的客户端（Claude Desktop、Claude Code、Cursor 等）连接。
## 功能
- **真实浏览器渲染**，通过 [chromedp] （纯 Go Chrome DevTools 协议客户端）+ 系统 Chromium — 处理 SPA、JS 注入、延迟加载内容、客户端路由。无需 Node.js 桥接。
- **Markdown 转换**，使用 [html-to-markdown] 插件管道：表格、代码块（带有语言检测）、删除线、CommonMark 语义、相对 URL 解析。
- **每个主机的认证会话** — `login` 工具为您打开一个可见的浏览器窗口进行身份验证，然后保留 cookie + localStorage，以便未来读取自动重用会话。
- **会话生命周期工具** — `list_sessions` 和 `clear_session` 用于检查和撤销。
- **内容提取** — `extract` 和 `read_url` 上的 `selector` 参数，让您可以提取页面中您关心的部分。
- **跨进程安全** — 会话状态持久化到磁盘（0600），因此服务器可以在不丢失身份验证的情况下重启。
[html-to-markdown]: https://github.com/JohannesKaufmann/html-to-markdown
[chromedp]: https://github.com/chromedp/chromedp
## 工具
| 工具 | 用途 |
| --- | --- |
| `read_url` | 获取 URL（可选 CSS 选择器），渲染 JS，返回 Markdown。 |
| `login` | 打开浏览器，让操作员登录，持久化会话。 |
| `list_sessions` | 显示已保存会话的每个主机。 |
| `clear_session` | 删除已保存的会话。 |
| `extract` | 读取 URL 并返回 CSS 选择器下的部分内容。 |
### `read_url` 参数
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `url` | 字符串（必填） | 绝对 http(s) URL。 |
| `selector` | 字符串 | 可选 CSS 选择器，用于提取区域。 |
| `wait_for` | 字符串 | 可选 CSS 选择器，用于等待（适用于 SPA 在 `networkidle` 后注入）。 |
| `timeout_seconds` | 整数 | 总超时时间。默认 30。 |
| `max_chars` | 整数 | 截断返回的 Markdown。默认约 200k。 |
### `login` 参数
| 字段 | 类型 | 描述 |
| --- | --- | --- |
| `url` | 字符串（必填） | 要打开的 URL（通常是登录页面）。 |
| `success_url` | 字符串 | 登录后 URL 的子字符串（例如 `/dashboard`）。每秒轮询。 |
| `success_selector` | 字符串 | 一旦身份验证成功就会可见的 CSS 选择器（例如头像菜单）。 |
| `timeout_seconds` | 整数 | 等待操作员完成登录的时间。默认 300。 |
`success_url` **或** `success_selector` 是必需的，以便工具知道何时停止等待并保存会话。
## 构建和安装
要求：
- Go 1.22+
- 位于 `$PATH` 的 Chromium 家族浏览器或安装在标准位置 — `google-chrome`、`chromium`、`chromium-browser` 或 Edge。
macOS：`brew install --cask chromium` （或标准 Chrome 安装）。
Linux：`apt install chromium` / `dnf install chromium`。
```bash
# 构建服务器二进制文件
go build -o bin/mcp-readitall ./cmd/readitall
```
> 如果项目不在 git 下，您可能需要 `-buildvcs=false`：
> `go build -buildvcs=false -o bin/mcp-readitall ./cmd/readitall`
chromedp 将通过 [`exec.LookPath`] 和通常的 Chromium 环境变量（`CHROME_BIN`、`CHROMIUM_BIN` 等）自动发现 Chromium。如果您有非标准安装，请直接指向二进制文件：
```bash
CHROME_BIN=/Applications/Chromium.app/Contents/MacOS/Chromium ./bin/mcp-readitall
```
[`exec.LookPath`]: https://pkg.go.dev/os/exec#LookPath
## 连接到 MCP 客户端
### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
```json
{
"mcpServers": {
"readitall": {
"command": "/absolute/path/to/mcp-readitall/bin/mcp-readitall"
}
}
}
```
### Claude Code （项目中的 `.mcp.json`）
```json
{
"mcpServers": {
"readitall": {
"command": "/absolute/path/to/mcp-readitall/bin/mcp-readitall"
}
}
}
```
编辑配置后重启客户端。
## 使用流程
### 1. 读取公共页面
询问您的 MCP 客户端：
> “读取 https://news.ycombinator.com 并总结前 5 篇文章”
在底层，模型调用 `read_url`。服务器启动一个无头 Chromium，导航，等待正文准备好（加上一个短暂的注入宽限期，或如果提供 `wait_for` 选择器），转换 HTML 为 Markdown，然后返回。
### 2. 读取认证页面
> “请登录 GitHub，然后读取我的通知”
模型首先调用：
```json
{
"name": "login",
"arguments": {
"url": "https://github.com/login",
"success_url": "/",
"timeout_seconds": 300
}
}
```
您的机器上会弹出一个真正的浏览器窗口。正常登录。当 URL 更改为包含 `/` 时，工具会保存会话并关闭窗口。对 `github.com` 的后续 `read_url` 调用将自动重用保存的 cookie + localStorage。
要使会话失效：
> “清除我的 GitHub 会话”
模型调用 `clear_session`。
## 会话存储
保存的会话存储在：
- 默认情况下为 `~/.mcp-readitall/sessions/<host>/state.json`
- 使用 `READITALL_SESSIONS_DIR=/some/path` 覆盖
状态文件以模式 `0600` （仅所有者读/写）写入，并使用 Playwright 的标准存储状态形状（`{cookies:[…], origins:[{origin, localStorage:[…]}]}`）— 可以加载 Playwright 捕获的会话，反之亦然。请像对待机密一样对待它们 — 它们授予对您认证会话的访问权限。
## 测试
```bash
go test -race ./...
```
测试套件是密封的 — 不会启动浏览器。它涵盖了：
- 主机名规范化（好 / 差 / 边缘）。
- 存储状态验证。
- 会话存储 CRUD 和并发安全性。
- HTML→Markdown 转换（标题、列表、表格、代码、实体、URL 解析、安全敏感的 `<script>` / `<style>` / 注释剥离）。
- 工具助手（URL 主机提取、逗号分隔的选择器解析、输出格式化器）。
## 限制
- `login` 工具需要一个 **可见** 的浏览器窗口。在没有显示屏的远程/无头主机上运行（且没有 VNC / X 转发）将不起作用 — Chrome 在没有窗口可供绘制时立即退出。
- 需要主机上的 Chromium 家族浏览器。`chromedp` 不包含浏览器。
- 读取器每次调用时为单标签页。目前不支持在单个工具调用中并行读取多个页面。
- 我们将 `networkidle` 视为“正文准备好 + 500 毫秒宽限期”（或您在 `wait_for` 中传递的内容）。无限期发送后台请求的站点可能需要 `wait_for` 选择器而不是依赖自动结算。
## 许可证
MIT。
