内容
# lean-chronoscope-mcp
**高效的浏览器MCP服务器**。使用Docker中的无头Chrome，捕获所有内容（控制台、网络、异常、IndexedDB、快照）到每个会话的SQLite存储，并提供57种查询该存储的工具——模型仅为所需内容付费。
为Claude Code、Claude Desktop和任何其他MCP客户端而建。替代[`@playwright/mcp`](https://github.com/microsoft/playwright-mcp)和[`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)，专注于每任务的token效率。
[](LICENSE)
[](#prerequisites)
[](https://modelcontextprotocol.io)
---
## 为什么？
其他浏览器MCP服务器会消耗大量上下文：它们在每次操作时都会重新发出完整的无障碍树，列出巨大的网络日志，并在导航时内联截图。对于快速组合的多步骤代理任务来说，这是一个问题。
本服务器采用不同的方式：
- **捕获数据流，按需查询**。一个长期运行的守护进程通过CDP拥有Chrome，并将每个控制台消息、网络请求、异常和快照写入每个会话的SQLite + 内容寻址的blob存储。工具是在此基础上查询的——列表返回摘要，详细工具获取主体。
- **紧凑，仅交互式快照**。`[e12] button "Save"`样式树 - 比Playwright在同一页面上的完整aria YAML小约2.8倍（[测量](docs/COMPARISON.md)）。
- **三种安装成本模式**。`full`（57种工具，约5.3k token），`slim`（5种核心工具，约547 token），或`gateway`（3种元工具，约321 token - 模型按需选择工具，模式仅在需要时加载）。
- **其他服务器缺乏的工具**：IndexedDB读写，网络拦截（中止/继续/响应），3种模式的机密编辑，跨控制台+网络历史的FTS5搜索，快照差异。
- **实时MCP资源**，具有真实的`listChanged`和每个部分的变更检测记忆 - （自修订版N以来未更改）折叠重复轮询。
## 快速开始
### 先决条件
- Docker + Docker Compose
- Node 22+（仅在主机上运行脚本/测试时需要）
### 运行守护进程
```bash
git clone https://github.com/yyhezkel/lean-chronoscope-mcp.git
cd lean-chronoscope-mcp
# 为HTTP网桥生成一个承载令牌：
echo "LEAN_CHRONOSCOPE_HTTP_TOKEN=$(openssl rand -base64 32)" > docker/.env
docker compose -f docker/docker-compose.yml up -d --build
docker exec lean-chronoscope-mcp ls /run/lean-chronoscope/daemon.sock # 应该存在
curl -s http://127.0.0.1:8780/health # {"ok":true,...}
```
### 使用MCP客户端注册
**Claude Code（HTTP传输 - 推荐）：**
```bash
claude mcp add lean-chronoscope -s user --transport http http://127.0.0.1:8780/mcp \
--header "Authorization: Bearer $(grep LEAN_CHRONOSCOPE_HTTP_TOKEN docker/.env | cut -d= -f2)"
```
重启您的客户端会话 - 工具列表在启动时加载。
**stdio（Claude Desktop等）：**
```jsonc
{
"mcpServers": {
"lean-chronoscope": {
"command": "docker",
"args": ["exec", "-i", "lean-chronoscope-mcp", "node", "/app/dist/bin/mcp.js", "--session", "default"]
}
}
}
```
工具在您的客户端中显示为`mcp__lean-chronoscope__*`（或您选择的任何别名）。Docker容器默认命名为`lean-chronoscope-mcp` - 这是一个本地名称；如果您愿意，可以通过`docker/docker-compose.yml`中的`container_name:`重命名。
**在重新连接时重用会话（HTTP）：** 默认情况下，HTTP网桥为每个连接创建一个新的浏览器会话。发送一个`x-lc-session: <id>`请求头来固定一个稳定的会话ID - 使用相同的头重新连接返回到同一个守护进程会话（如果较早的断开连接关闭了它，则从磁盘恢复），而不是一个新的随机会话。调用者的会话ID被验证（不允许/ `\`、`.`、NUL、空或> 200个字符）以防止路径遍历，因为ID成为文件系统路径。
## 工具表面（57种工具）
| 类别 | 工具 |
|---|---|
| 会话 | `session_list`, `session_new`, `session_attach`, `session_close` |
| 页面 | `page_navigate`, `page_list`, `page_new`, `page_select`, `page_close`, `page_back`, `page_forward`, `page_reload` |
| 感知 | `snapshot_take`, `snapshot_diff`, `screenshot_take`, `wait_for` |
| 输入 | `click`, `hover`, `type`, `fill_form`, `key`, `scroll`, `drag`, `upload_file` |
| 控制台 | `console_list`, `console_get`, `console_search` (FTS5) |
| 网络 | `network_list`, `network_get`, `network_search` (FTS5), `network_wait_for` |
| 拦截 | `intercept_add`, `intercept_list`, `intercept_remove` |
| 存储 | `cookies_*`, `localStorage_*`, `sessionStorage_*`, `indexeddb_*` |
| 模拟 | `emulate_viewport`, `emulate_useragent`, `emulate_network`, `emulate_geolocation` |
| 诊断 | `performance_metrics`, `daemon_status`, `script_evaluate` |
## 安装成本模式
| 模式 | 标志/环境变量 | 广告工具 | `tools/list`有效载荷 |
|---|---|---|---|
| `full` *(默认)* | — | 57 | 约5,350 token |
| `slim` | `--slim` / `LEAN_CHRONOSCOPE_SLIM=1` | 5种核心工具 | 约547 token |
| `gateway` | `--gateway` / `LEAN_CHRONOSCOPE_GATEWAY=1` | 3种元工具（`tools_catalog`, `tool_schema`, `tools_invoke`）- 57种工具仍可按名称调用 | 约321 token |
**网关模式** 广告一个3工具索引：模型读取`tools_catalog`，仅为需要的工具获取`tool_schema`，然后通过`tools_invoke`调用它们。对于已经在客户端延迟工具模式的MCP客户端非常有用。*注意：* Claude Code已经原生延迟MCP模式 - 网关主要适用于其他客户端或极端token预算。参见 [`docs/COMPARISON.md`](docs/COMPARISON.md) 了解完整的分解。
## 架构
```
┌─────────────────┐ Unix socket (NDJSON RPC) ┌──────────────────────────────┐
│ mcp-server │ ◀──────────────────────────▶ │ 守护进程（长期运行） │
│ （每个会话， │ │ ├─ 通过CDP的Chrome │
│ stdio / HTTP） │ │ ├─ 每个会话的SQLite │
└─────────────────┘ │ └─ 内容寻址的blob │
▲ └──────────────────────────────┘
│ MCP ▲
│ （stdio或 │
│ HTTP+SSE） │ CDP
▼ ▼
MCP客户端 Chromium
```
守护进程拥有浏览器，并将数据流写入SQLite。每个MCP客户端连接都会产生一个薄的每个会话的mcp-server，该服务器通过Unix套接字与守护进程通信。工具是存储上的查询；列表返回摘要，详细工具获取主体，大主体变为内容寻址的blob。
参见 [`docs/IMPLEMENTATION.md`](docs/IMPLEMENTATION.md) 了解更深入的设计原理。
## 会话生命周期和保留
会话在持久的跨会话索引`registry.sqlite`中跟踪，位于`<dataDir>/registry.sqlite`（一个`sessions`表：id，created_at，last_activity，status open/closed，source stdio/http，page_count，size_bytes，closed_at，data_dir）。它在守护进程重启时存活，并在启动时协调（孤立的`open`行翻转为`closed`，磁盘上的会话目录被重新索引）。`session_list`报告`lastActivity`，`sizeBytes`（db+wal+shm+blobs），`status`和`source`，并采用可选的`includeClosed`来显示注册表中已关闭的会话；`daemon_status`报告相同的会计信息以及`dbBytes`/`blobBytes`的细分。
会话可以携带一个可选的人类**标题**（`registry.sqlite`中的一列，在`session_list`上显示）。 **`session_attach`** 工具将连接指向现有会话 - 按ID或标题 - 并从磁盘**恢复已关闭会话的捕获历史** （BrowserContext启动时是新鲜的；浏览器状态不会被保留，但所有捕获的控制台/网络/快照历史都是可读的）。与不存在的标题匹配会启动一个带有它的新会话（**attach-or-create**）。
后台**回收者** 会自动保持边界：
- **空闲/大小驱逐** - 在会话空闲超过`LEAN_CHRONOSCOPE_IDLE_MS`（默认30分钟）或超过`LEAN_CHRONOSCOPE_SIZE_CAP_BYTES`（默认500MB，`0`禁用）时，释放浏览器上下文+内存（保留磁盘上的DB以进行年龄扫描）。
- **行修剪** - 保留最新的`LEAN_CHRONOSCOPE_MAX_CONSOLE`（50k）控制台行，`LEAN_CHRONOSCOPE_MAX_NETWORK`（50k）网络行和`LEAN_CHRONOSCOPE_MAX_SNAPSHOTS_PER_PAGE`（10）每个页面的快照；FTS通过触发器保持同步，释放的页面通过`incremental_vacuum`回收。修剪现在还会在删除行后**GC孤立的blob文件** - 内容寻址的blob（`blobs/<sha>.bin`）仅在没有存活的行引用其sha时被删除（安全复制），而不是在老化扫描之前。
- **老化扫描** - 会话目录超过`LEAN_CHRONOSCOPE_RETENTION_DAYS`（默认7天）时，大约每小时（不仅在启动时）删除，注册表保持同步。
回收间隔是`LEAN_CHRONOSCOPE_REAPER_INTERVAL_MS`（默认60000，`0`禁用回收器）。会话在关闭前检查点（`wal_checkpoint(TRUNCATE)`），因此持久的`db.sqlite`是完整和紧凑的。
> 环境变量使用`LEAN_CHRONOSCOPE_*`前缀；遗留的`BROWSER_MCP_*`名称作为后备以确保向后兼容。
## 与Playwright MCP / Chrome DevTools MCP的比较
| | lean-chronoscope-mcp | @playwright/mcp | chrome-devtools-mcp |
|---|---|---|---|
| 快照格式 | 紧凑，仅交互式 | 完整的aria YAML | aria + 额外内容 |
| 快照成本（HN，约token） | **约5,343** | 约14,756 | 类似于Playwright |
| 5步任务成本（约token） | **约5.6k** | 约24k | 类似于Playwright |
| 安装开销 | 57种工具，约5.3k token（或网关中的321） | 20种工具，约2k | 约30种工具 |
| IndexedDB工具 | ✅ | ❌ | ❌ |
| 网络拦截 | ✅ 中止/继续/响应 | ❌ | ❌ |
| 机密编辑 | ✅ 3种模式 | ❌ | ❌ |
| FTS5搜索（控制台/网络） | ✅ | ❌ | ❌ |
| 持久性 | 每个会话的SQLite | 内存中 | 内存中 |
完整数字+方法论见 [`docs/COMPARISON.md`](docs/COMPARISON.md) 。Token估计 = chars/4;比率与tokenizer无关。
## 文档
- [`CLAUDE.md`](CLAUDE.md) — 在存储库中工作的指南（也适用于任何基于代理的贡献）。
- [`docs/IMPLEMENTATION.md`](docs/IMPLEMENTATION.md) — 完整架构 + 基本原理。
- [`docs/SECURITY.md`](docs/SECURITY.md) — 信任模型 + 编辑选项。
- [`docs/COMPARISON.md`](docs/COMPARISON.md) — 与Playwright MCP相比的测量token。
- [`docs/TESTS.md`](docs/TESTS.md) + [`docs/TOOL_TESTS.md`](docs/TOOL_TESTS.md) — 每个测试涵盖的内容；每个工具的检查清单。
- [`docs/FOLLOWUPS.md`](docs/FOLLOWUPS.md) — 已知的延期事项，部署说明，MCP客户端集成提示。
- [`CHANGELOG.md`](CHANGELOG.md) — 版本说明。
## 开发
```bash
pnpm install
pnpm typecheck
pnpm build
docker compose -f docker/docker-compose.yml up -d --build
node scripts/test-all-tools.mjs # 57工具端到端套件（必须通过57/57）
node scripts/bench-tokens.mjs # 测量安装+每次调用的成本
node scripts/smoke-test-gateway.mjs # 网关模式冒烟测试
```
参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
## 许可证
[MIT](LICENSE) © Yossi Yehezkel
