mobius-mcp

<div align="center"> <img src="./apps/browser-extension/public/icons/icon-128.png" alt="mobius-mcp" width="72" height="72" /> <h1>mobius-mcp</h1> <a href="https://www.npmjs.com/package/mobius-mcp"><img alt="npm 版本" src="https://img.shields.io/npm/v/mobius-mcp.svg"></a> <a href="https://www.npmjs.com/package/mobius-mcp"><img alt="npm 下载量" src="https://img.shields.io/npm/dm/mobius-mcp.svg"></a> <a href="./LICENSE"><img alt="许可证" src="https://img.shields.io/badge/license-MIT-blue.svg"></a> <a href="https://github.com/Topman-14/console-stream-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Topman-14/console-stream-mcp/actions/workflows/ci.yml/badge.svg"></a> </div> 为 AI 编程代理（Claude Code、Codex CLI、Gemini CLI 等）提供实时访问您的 Web 应用运行时 — 控制台日志、错误、网络请求和导航事件 — 无需复制粘贴任何内容到聊天中。 本地优先。无云服务，无遥测，无外部 API。 ## 工作原理 ``` Web 应用 │ 扩展程序或 npm 包 │ WebSocket │ localhost │ mobius-mcp │ MCP │ Claude Code / Codex / Gemini CLI ``` 浏览器客户端（扩展程序或 npm 包）捕获运行时事件 — `console.*`、未捕获的错误、未处理的拒绝、`fetch`/`XHR` 调用和导航（包括通过 `pushState`/`replaceState`/哈希值的 SPA 路由更改）— 并通过 WebSocket 将它们流式传输到本地 MCP 服务器。MCP 服务器保留一个滚动的内存历史记录，并将其作为 MCP 工具暴露给 AI 代理。 ## 软件包 | 路径 | 描述 | | --- | --- | | `apps/mcp-server` | Node.js MCP 服务器；WebSocket 中心 + MCP 工具实现 | | `apps/browser-extension` | 捕获并流式传输浏览器事件的 Chromium 扩展程序 | | `apps/npm-client` | 用于直接应用集成的 `mobius-client` npm 包 | | `packages/protocol` | 版本化的事件模式和消息信封（私有，捆绑到已发布的软件包中） | | `packages/capture-core` | 扩展程序和 npm 客户端共享的运行时钩子补丁（私有，捆绑） | | `skill` | 描述何时/如何使用 MCP 工具调试 Web 应用的代理技能 | | `examples` | 展示集成的示例应用 | ## 快速入门 `mobius-mcp` 已发布到 npm — 无需克隆即可使用它。 1. **将 MCP 服务器注册到您的代理。** 对于 Claude Code： ```bash claude mcp add mobius-mcp -- npx -y mobius-mcp ``` 或直接将其添加到您的 MCP 客户端配置文件中（Claude Code、Codex CLI、Gemini CLI 等都读取此格式的 JSON 配置文件）： ```json { "mcpServers": { "mobius-mcp": { "command": "npx", "args": ["-y", "mobius-mcp"] } } } ``` 2. **将您的应用运行时流式传输到它**，要么通过浏览器扩展程序（从 `apps/browser-extension/dist` 加载解压后的版本，参见下文），要么将 npm 客户端放入您的应用中： ```bash npm install mobius-client ``` ```ts import { startMobiusStream } from "mobius-client"; startMobiusStream(); ``` 3. 请求您的代理通过下面的 MCP 工具检查标签页的控制台/错误/网络/导航。 ### 在本地开发此仓库 ```bash npm install npm run build # 从源代码启动 MCP 服务器，而不是使用 npx npm run start --workspace=apps/mcp-server ``` ### 启用捕获（扩展程序） 扩展程序默认情况下永远不会捕获任何内容。单击其工具栏图标，然后在您要调试的标签页上点击“启用标签页” — 这是唯一的选项卡。多个标签页可以独立启用。对于您始终想要捕获的开发服务器，请在扩展程序的设置页面上添加一条规则（例如 `localhost:5173`）（右键单击图标 → 选项）— 匹配的标签页将在导航时自动启用。 ## MCP 工具 * `get_recent_logs` * `get_recent_errors` * `get_network_requests` * `get_logs_since` * `clear_logs` * `get_connected_tabs` * `get_capture_settings` — 已连接标签页正在积极捕获的事件类别（控制台/错误/网络/导航/dom），以便可以区分另一个工具的空结果和“该类别已关闭” * `set_active_tab` * `navigate_to`、`switch_tab`、`reload_tab` — 浏览器控制（仅限扩展程序） * `list_tabs` — 每个打开的标签页，而不仅仅是启用捕获的标签页（需要某个地方连接的扩展程序） * `get_job_status`、`get_job_result`、`cancel_job` — 用于稍后阶段添加的较长时间运行的操作（录制、分析） * `start_debug_session`、`end_debug_session` — 记录控制台/网络/导航/DOM 事件的时间顺序时间线，而不是手动关联单独的快照（单个标签页，在整个页面导航期间不会存活） * `wait_for_console_error`、`wait_for_navigation`、`wait_for_request`、`wait_for_element` — 阻止（带有超时）直到发生某个条件，而不是在循环中轮询 `get_logs_since` * `take_screenshot`、`capture_full_page`、`capture_element` — 仅限扩展程序，需要 `chrome.debugger`（CDP） * `capture_dom`、`capture_accessibility_tree` — 仅限扩展程序，需要 CDP * `evaluate_js` — 在标签页中运行任意 JS 并获取结果；仅限扩展程序，需要 CDP，完全开放（无只读强制执行） * `get_response_body`、`export_har` — 仅限扩展程序的 `get_response_body`（需要 CDP）；`export_har` 从存储的网络事件中工作，适用于任一客户端，但永远不包括正文 * `start_cpu_profile`、`start_memory_profile` — 仅限扩展程序，需要 CDP，基于作业（参见 `get_job_status`/`get_job_result`） CDP 工具（上面标记为“需要 CDP”）会使 Chrome 在使用后显示一个持续的“正在调试”横幅 — 调试器会在第一次使用时附加并保持附加状态，它不会在每次调用时附加/分离。这是 Chrome 级别的指示，而不是扩展程序可以抑制的。`start_cpu_profile`/`start_memory_profile` 持续时间上限为 60 秒，超出 ~25-30 秒后为尽力而为 — Chrome 可以终止空闲的 MV3 后台服务工作线程，这可能会缩短长时间的配置文件。 ## 客户端功能 两个浏览器客户端的事件摄取（控制台/错误/网络）相同 — 服务器无法区分它们。命令功能并非如此：许多后期功能需要 Chrome DevTools Protocol 访问权限，而只有扩展程序具有此权限。该协议通过在连接时在 `capabilities` 字段中报告此信息，因此不支持客户端无法执行的命令会以清晰的错误信息失败，而不是挂起。 | 功能 | 浏览器扩展程序 | npm 客户端 (`mobius-client`) | | --- | --- | --- | | 控制台/错误/网络/导航事件流 | ✅ | ✅ | | `get_recent_logs` / `get_recent_errors` / `get_network_requests` / `get_logs_since` | ✅ | ✅ | | 多标签页感知（`get_connected_tabs`、`set_active_tab`、`get_capture_settings`） | ✅ | ✅ （每个应用实例一个条目） | | 选项卡捕获（弹出窗口切换/设置页面规则） | ✅ | 不适用 — 捕获在 `startMobiusStream()` 运行后立即开始 | | 浏览器控制（`navigate_to`、`reload_tab`、`switch_tab`） | ✅ | ❌ | | 调试会话（`start_debug_session`/`end_debug_session`） | ✅ | ✅ （仅控制台/网络/导航事件类型 — 无 DOM 突变） | | 截图、DOM/可访问性快照 | ✅ （需要 CDP） | ❌ | | CPU/内存分析 | ✅ （需要 CDP） | ❌ | | `evaluate_js`、网络响应正文 | ✅ （需要 CDP） | ❌ | | React/Redux/Zustand 状态、存储检查 | ❌ （计划中） | ❌ （计划中） | 在 [ROADMAP.md](./ROADMAP.md) 中查看“计划中”内容对应的阶段。 ## 设计原则 * 本地优先，零云依赖，零遥测 * 框架无关 * 扩展程序和 npm 客户端发出相同的、版本化的协议 — 服务器无法区分它们 在 [PROJECT.md](./PROJECT.md) 中查看完整的设计文档，在 [ROADMAP.md](./ROADMAP.md) 中查看分阶段的未来工作。 ## 贡献 欢迎贡献。请先打开一个问题讨论重大更改，然后再提交 PR。请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 许可证 [MIT](./LICENSE)