chromiumfish_mcp

# chromiumfish_mcp `chromiumfish_mcp` 是一个独立的模型上下文协议（MCP）服务器，用于 [ChromiumFish](https://github.com/arman-bd/chromiumfish)。它允许 Claude Code、Claude Desktop、Cursor 等 MCP 客户端通过结构化工具驱动 ChromiumFish 浏览器。 它使用官方的 ChromiumFish npm 包，不包含任何 Chromium 源代码或二进制文件。在第一次需要页面的工具调用中，上游 SDK 会下载并缓存匹配的浏览器构建。有关详细工具用法，请参见 **[docs/USAGE.md](docs/USAGE.md)**。 ## 要求 - Node.js 20 或更高版本。 - 操作系统和架构支持 ChromiumFish。 - 初始浏览器下载所需的网络访问。如果没有预构建的资产与您的平台匹配，请在本地构建 ChromiumFish 并使用 `--chrome-path` 或 `CHROME_BIN` 指向它。 ## 安装 ```bash npm install --global github:LowOrbitLab/chromiumfish_mcp chromiumfish_mcp --persona-seed alice ``` 或在不安装的情况下运行：`npx --yes github:LowOrbitLab/chromiumfish_mcp --persona-seed alice`。 ## 配置 将服务器添加到您的 MCP 客户端配置中： ```json { "mcpServers": { "chromiumfish": { "command": "chromiumfish_mcp", "args": ["--persona-seed", "alice"] } } } ``` 要在 GitHub 上运行而不是全局安装，请设置 `"command": "npx"` 并在 `args` 中添加 `"--yes", "github:LowOrbitLab/chromiumfish_mcp"`。在 Windows 上，如果您的客户端无法解析 `npx`，请使用 `npx.cmd`。 ## 工具 | 工具 | 用途 | |------|---------| | `list_pages`, `open_page`, `select_page`, `close_page` | 通过稳定的 `pageId` 管理页面 | | `navigate`, `navigate_back`, `navigate_forward`, `reload` | 导航和浏览页面历史 | | `snapshot` | 列出可见的交互式元素，带有 `e1`/`e2` 引用 | | `get_text`, `take_screenshot` | 检索页面或框架内容；`take_screenshot` 裁剪到一个元素，带有 `target` | | `click`, `hover`, `type_text`, `select_option`, `set_checked`, `press_key`, `scroll`, `wait_for` | 与页面交互 | | `drag` | 拖动到另一个元素或按像素偏移，带有类似人类的路径 | | `upload_file` | 附加本地文件到文件输入 - 需要 `--upload-dir` | | `click_at` | 点击绝对坐标（用于小部件 `snapshot` 无法看到的情况） | | `list_frames` | 列出具有稳定 ID 的框架/iframe | | `find_challenge`, `solve_challenge` | 检测和清除 interstitial / 框架挑战；结果指示是否观察到、交互和验证 | | `evaluate` | 运行任意 JavaScript - 需要 `--allow-eval` | | `run_task` | 原生 ChromiumFish 代理 - 需要 `--allow-native-agent` | 每个导航和交互工具都会报告结果 `url`、`title`、`navigated` 和任何 `newPages`，因此客户端仅在页面实际更改时才需要后续 `snapshot`；`returnSnapshot: true` 返回操作结果和新的 snapshot，合二为一。导航等待新文档加载后报告，因此这些字段描述了到达的页面；如果导航在十秒后仍在进行，则报告 `navigationPending: true` 而不是描述正在离开的页面，好像什么也没发生。引用编号永远不会重复使用，因此在 snapshot 之间持有的引用失败并报错，而不是对不同元素执行操作；`snapshot` 还报告 ARIA 角色，因此 `role=button[name="Submit"]` 在任何 `target` 字段中都有效，作为重新渲染的替代方案。服务器提供 MCP `instructions`，描述此工作流、引用生命周期和挑战序列。 Snapshot 引用、框架感知交互、等待和跨源挑战工作流在 **[docs/USAGE.md](docs/USAGE.md)** 中涵盖。 ## 命令行选项 ```text --persona-seed VALUE 使用稳定的浏览器指纹标识 persona --chrome-path PATH 使用本地 ChromiumFish 可执行文件 --browser-version VERSION 选择上游 ChromiumFish 构建版本 --headed 显示浏览器窗口 --window-size WIDTHxHEIGHT 设置浏览器窗口大小 --timezone ZONE 使用 IANA 时区，自动或系统（默认：自动） --proxy URL 通过代理路由浏览器流量 --allowed-host HOST 允许顶级导航到主机及其子域名；可重复 --max-text-chars N 设置文本和 snapshot 输出的硬限制 --upload-dir PATH 允许 upload_file 读取此目录；可重复 --allow-eval 启用任意 JavaScript 执行 --allow-native-agent 启用原生 ChromiumFish 浏览器代理 ``` 代理凭证可以嵌入在代理 URL 中，但随后会在客户端配置中公开。永远不要提交包含代理密码、cookie 或 API 密钥的配置文件。 ## 安全 - 仅限 stdio - 请勿将 Chromium DevTools 端点暴露给公共互联网。 - `evaluate` 和原生代理默认禁用；仅在受信任的环境中启用它们。 - `--allowed-host example.com` 限制顶级 HTTP/HTTPS 导航（重定向、链接、表单帖子、弹出窗口）到主机及其子域名。第三方子框架和页面资产仍然可访问 - 它是一个导航守卫，而不是网络出口过滤器。 - `upload_file` 将主机文件发送到页面发布的任意来源，因此在 `--upload-dir` 命名至少一个目录之前，它是未注册的，并且每个路径必须在其中一个目录内解析。路径和根目录都通过符号链接解析，因此在根目录内植入的链接无法到达外部。 将根目录限制为任务实际需要的文件 - 页面可以影响模型选择的文件。 - 客户端可以点击和输入具有实际副作用的内容。对于购买、发布、删除和权限更改，请保留人工确认。 - `solve_challenge` 在页面未被阻止时返回 `ok: true`，包括从未面临挑战的页面。在记录或报告挑战被清除之前，请阅读 `challengeObserved`、`interactionPerformed` 和 `clearanceVerified` - 单独的 `ok` 会高估实际发生的情况。 - 每个进程运行一个独立的浏览器上下文；这不是一个共享的多租户服务。 ## 开发 ```bash npm ci npm test node dist/index.js --help ``` 该套件使用内存中的 MCP 传输来验证工具发现、危险工具选择和结果。它不会下载或启动浏览器。 ## 许可证 MIT。ChromiumFish 代码和商标归其各自贡献者所有；有关归属，请参见 [NOTICE](NOTICE)。这是独立的包装器，而不是官方的 ChromiumFish 版本。