内容
<a id="readme-top"></a>
<!-- 项目徽章 -->
[![MIT License][license-shield]][license-url]
[![领英][linkedin-shield]][linkedin-url]
<!-- 项目标志 -->
<br />
<div align="center">
<a href="https://github.com/Nagell/vscode-integrated-browser-mcp">
<img src="assets/icon.png" alt="Logo" width="80" height="80">
</a>
<h3 align="center">集成浏览器 MCP</h3>
<p align="center">
一个 VS Code 扩展，将集成浏览器作为 MCP 服务器暴露给 AI 代理
<br />
<a href="./docs/DEVELOPMENT.md"><strong>探索文档 »</strong></a>
<br />
<br />
<a href="https://github.com/Nagell/vscode-integrated-browser-mcp/issues/new?labels=bug&template=bug_report.md">报告问题</a>
·
<a href="https://github.com/Nagell/vscode-integrated-browser-mcp/issues/new?labels=enhancement&template=feature_request.md">请求功能</a>
</p>
</div>
<!-- 目录 -->
<details>
<summary>目录</summary>
<ol>
<li>
<a href="#关于项目">关于项目</a>
<ul>
<li><a href="#构建工具">构建工具</a></li>
</ul>
</li>
<li>
<a href="#快速入门">快速入门</a>
<ul>
<li><a href="#先决条件">先决条件</a></li>
<li><a href="#安装">安装</a></li>
<li><a href="#克劳德代码">克劳德代码</a></li>
<li><a href="#克莱恩">克莱恩</a></li>
<li><a href="#继续开发">继续开发</a></li>
</ul>
</li>
<li><a href="#可用工具">可用工具</a></li>
<li><a href="#设置">设置</a></li>
<li><a href="#命令">命令</a></li>
<li><a href="#已知限制">已知限制</a></li>
<li><a href="#路线图">路线图</a></li>
<li><a href="#许可证">许可证</a></li>
<li><a href="#联系方式">联系方式</a></li>
<li><a href="#致谢">致谢</a></li>
</ol>
</details>
<!-- 关于项目 -->
## 关于项目
VS Code 1.112+ 提供强大的浏览器代理工具 — 打开页面，读取可访问性树，截图，点击元素，输入文本 — 但仅对 VS Code 内置的 Copilot 聊天代理开放。外部 AI 代理无法访问这些工具。
该扩展填补了这一空白。它在 VS Code 扩展主机（可访问 VS Code API）中运行 MCP 服务器，并将工具调用从任何 MCP 兼容的 AI 代理代理到 VS Code 的内部浏览器功能 — 无需重复实现浏览器或丢失集成面板的视觉反馈。
与支持 MCP 流式 HTTP 传输的任何代理配合使用，在同一台机器上运行：**克劳德代码**，**克莱恩**，**继续开发**等。
### 构建工具
[![TypeScript][TypeScript]][TypeScript-url] [![VS Code 扩展 API][VSCode]][VSCode-url] [![模型上下文协议 SDK][MCP]][MCP-url] [![Express][Express]][Express-url] [![Zod][Zod]][Zod-url]
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 快速入门 -->
## 快速入门
### 先决条件
- VS Code 1.112 或更高版本
- MCP 兼容的 AI 代理（克劳德代码，克莱恩，继续开发等）
### 安装
1. 从 VS Code 市场安装扩展
2. 在 VS Code 设置中启用浏览器工具
```json
"workbench.browser.enableChatTools": true
```
3. 至少打开一次集成浏览器面板
浏览器工具仅在打开面板后注册。
通过命令面板（`Ctrl+Shift+P`）打开它 → **集成浏览器：打开**，
然后输入任何 URL（例如 `https://example.com`）。
4. 连接您的 MCP 客户端 — 请参阅下面的章节获取您的代理。
> [!NOTE]
> VS Code 在会话中首次使用每个工具时显示同意对话框。单击 **允许** 继续 — 在同一会话中后续调用将静默运行。
>
> 要完全消除对话框，请在安装后从命令面板运行 **集成浏览器 MCP：启用 CDP**。它修改 `argv.json` 并需要重启 VS Code。
### 克劳德代码
扩展程序在首次激活时自动向克劳德代码注册。无需手动配置 — 启动时，它将正确的 URL（包括会话令牌）写入 `~/.claude.json` 并提示您确认。
在您的项目中运行 `claude` — `integratedBrowser` MCP 服务器将自动列出。
> [!TIP]
> 如果您需要 URL（例如重新安装后），请从命令面板运行 **集成浏览器 MCP：复制 MCP URL** 以将其复制到剪贴板。
### 克莱恩
服务器需要一个唯一的会话令牌，每个机器一个。从命令面板获取您的 URL：
1. 打开 **集成浏览器 MCP：复制 MCP URL** — 完整的 URL（带有令牌）被复制到您的剪贴板。
2. 打开克莱恩的 MCP 设置并通过 UI 添加 **远程服务器** （从传输下拉菜单中选择 *流式 HTTP*），或直接编辑配置文件。
配置文件位置：
- Linux/macOS：`~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- Windows：`%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
```json
{
"mcpServers": {
"integratedBrowser": {
"type": "streamableHttp",
"url": "http://127.0.0.1:3100/mcp?token=<您的令牌>"
}
}
}
```
用 **复制 MCP URL** 命令中的值替换 `<您的令牌>`。
> [!IMPORTANT]
> 必须包含 `"type": "streamableHttp"` 字段。 如果没有它，克莱恩将静默地回退到旧的 SSE 传输，连接将失败。
### 继续开发
从命令面板获取您的 URL（**集成浏览器 MCP：复制 MCP URL**），然后添加到 `~/.continue/config.yaml`:
```yaml
mcpServers:
- name: integratedBrowser
type: streamable-http
url: http://127.0.0.1:3100/mcp?token=<您的令牌>
```
用 **复制 MCP URL** 命令中的值替换 `<您的令牌>`。
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 可用工具 -->
## 可用工具
### 页面管理
| 工具 | 描述 |
| --- | --- |
| `open_browser_page` | 打开一个 URL。返回所有其他工具所需的 `pageId`。传递 `forceNew: true` 以打开第二个选项卡。 |
| `list_pages` | 列出此会话中打开的所有页面及其 ID 和 URL。 |
| `close_page` | 关闭页面并从会话中删除它。 |
| `navigate_page` | 导航到 URL，或转到 `back` / `forward` / `reload`。 |
| `get_url` | 获取页面的当前 URL。 |
| `list_visible_pages` | 列出当前在 VS Code 中可见的浏览器选项卡（不限于此会话）。 |
| `attach_visible_page` | 通过 URL 将可见选项卡附加到会话，返回 `pageId`。 |
### 读取
| 工具 | 描述 |
| --- | --- |
| `read_page` | 读取页面作为可访问性树（标题，URL，元素引用）。 |
| `get_dom` | 获取页面的原始 HTML 或特定元素（`selector`）。 |
| `markdown` | 提取页面内容为干净的 Markdown。可选地限定为 CSS `selector`。 |
| `eval_js` | 评估 JavaScript 表达式并返回结果。与 DevTools 控制台相同的信任模型 — 不要传递不受信任的输入。 |
### 交互
| 工具 | 描述 |
| --- | --- |
| `click_element` | 通过 `ref`（来自 `read_page`）或 `selector` 点击元素。 |
| `type_in_page` | 输入文本或按键（例如 `"Enter"`，`"Control+a"`）。用 `ref` 或 `selector` 定位。 |
| `hover_element` | 悬停在元素上。 |
| `drag_element` | 从一个元素拖动到另一个元素。 |
| `handle_dialog` | 接受或拒绝浏览器对话框（警报/确认/提示）。 |
| `scroll` | 按增量或绝对位置滚动。 |
### 视觉
| 工具 | 描述 |
| --- | --- |
| `screenshot_page` | 截图。支持 `fullPage`，`waitMs`，`ref` 和 `selector`。 |
| `screenshot_slice` | 截取特定滚动切片的视口大小的截图（支持负索引）。 |
| `emulate` | 设置浏览器视口大小。 |
### 控制台
| 工具 | 描述 |
| --- | --- |
| `get_console` | 读取捕获的 `console.log / warn / error / info / debug` 输出。按 `levels` 过滤。 |
| `clear_console` | 清除控制台捕获缓冲区。 |
### 元素选择
| 工具 | 描述 |
| --- | --- |
| `get_element_selection` | 返回通过 **为代理选取元素** 按钮捕获的最后一个元素 — 标签，文本，HTML 和边界矩形。该按钮出现在每个浏览器页面的右下角。需要 CDP（首先运行 **启用 CDP**）。 |
| `clear_element_selection` | 清除存储的元素选择。 |
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 设置 -->
## 设置
| 设置 | 默认值 | 描述 |
| --- | --- | --- |
| `integratedBrowserMcp.port` | `3100` | MCP 服务器监听的端口 |
| `integratedBrowserMcp.autoStart` | `true` | 自动启动服务器 |
| `integratedBrowserMcp.extendedLogging` | `false` | 将详细的 CDP/元素选择器诊断信息发出到输出通道（在扩展开发主机上始终启用） |
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 命令 -->
## 命令
所有命令都可通过命令面板（`Ctrl+Shift+P`）访问。
| 命令 | 描述 |
| --- | --- |
| `集成浏览器 MCP：启动服务器` | 手动启动 MCP 服务器。在禁用 `autoStart` 时很有用。 |
| `集成浏览器 MCP：停止服务器` | 停止正在运行的 MCP 服务器。 |
| `集成浏览器 MCP：复制 MCP URL` | 将完整的 MCP 服务器 URL（包括会话令牌）复制到剪贴板。用于配置克莱恩，继续开发或其他 MCP 客户端。 |
| `集成浏览器 MCP：为代理选取元素` | 在活动浏览器选项卡中激活元素选择器（与单击浮动 **为代理选取元素** 按钮相同）。单击任何元素以捕获它；通过 `get_element_selection` 检索。需要 CDP。 |
| `集成浏览器 MCP：启用 CDP（无对话框浏览器工具）` | 将 `enable-proposed-api` 写入 `argv.json`，以便在 VS Code 重启后，所有浏览器工具无需同意对话框即可运行。 |
| `集成浏览器 MCP：列出可用的 LM 工具（调试）` | 将 VS Code 中注册的所有 LM 工具打印到 *浏览器 MCP 调试* 输出通道。有助于在排查问题时验证浏览器工具是否处于活动状态。 |
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 已知限制 -->
## 已知限制
- **`list_pages` URL 在页面内导航后过期** — 链接点击和表单提交不会更新存储的 URL。使用 `get_url` 或 `read_page` 获取实时 URL。
- **`open_browser_page` 默认导航现有选项卡** — 无需 `forceNew: true`，VS Code 重用当前集成浏览器选项卡而不是打开新选项卡。需要 `forceNew: true` 时，请同时打开两个选项卡。
- **无多窗口支持** — 工具调用始终针对扩展激活的窗口中的浏览器。
- **MCP 服务器安全** — 服务器绑定到 `127.0.0.1` 并要求所有 `/mcp` 请求提供会话令牌。令牌自动写入 `~/.claude.json`。请勿将 3100 端口暴露在外部；任何本地进程学习令牌后，可以调用 `eval_js` 并在浏览器中执行任意 JavaScript。
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 路线图 -->
## 路线图
- [x] 具有状态会话管理的 MCP HTTP 服务器
- [x] 通过 `vscode.lm.invokeTool` 的浏览器桥
- [x] 页面管理：`open_browser_page`，`list_pages`，`close_page`，`navigate_page`，`get_url`，`list_visible_pages`，`attach_visible_page`
- [x] 读取：`read_page`，`get_dom`，`markdown`，`eval_js`
- [x] 交互：`click_element`，`type_in_page`，`hover_element`，`drag_element`，`handle_dialog`，`scroll`
- [x] 视觉：`screenshot_page`（全页/等待毫秒），`screenshot_slice`，`emulate`
- [x] 控制台捕获：`get_console`，`clear_console`
- [x] CDP 层 — 启用提案的 `browser` API 后，无对话框工具执行
- [x] 首次激活时自动配置 `~/.claude.json`
- [x] 通过 `启用 CDP` 命令一键设置 CDP
- [x] 元素选择 — 每个浏览器页面中的浮动“为代理选取元素”按钮；代理通过 `get_element_selection` 检索
- [ ] 可靠的多选项卡支持 — 多个打开的选项卡的稳定 CDP 会话跟踪和元素选择器（进行中）
- [ ] 多窗口支持 — 每个窗口的 MCP 服务器/端口注册表（延期）
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 许可证 -->
## 许可证
在 MIT 许可证下分发。有关更多信息，请参见 `LICENSE`。
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 联系方式 -->
## 联系方式
达维德·尼特卡 - [领英][linkedin-url]
项目链接：[https://github.com/Nagell/vscode-integrated-browser-mcp](https://github.com/Nagell/vscode-integrated-browser-mcp)
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- 致谢 -->
## 致谢
- [模型上下文协议 SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [VS Code 扩展 API — 语言模型工具](https://code.visualstudio.com/api/references/vscode-api#lm)
- [最佳 README 模板](https://github.com/othneildrew/Best-README-Template)
<p align="right">(<a href="#readme-top">回到顶部</a>)</p>
<!-- Markdown 链接和图片 -->
[license-shield]: https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge
[license-url]: ./LICENSE
[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
[linkedin-url]: https://www.linkedin.com/in/dawidnitka
[TypeScript]: https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white
[TypeScript-url]: https://www.typescriptlang.org/
[VSCode]: https://img.shields.io/badge/VS%20Code%20API-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white
[VSCode-url]: https://code.visualstudio.com/api
[MCP]: https://img.shields.io/badge/MCP%20SDK-000000?style=for-the-badge&logo=modelcontextprotocol&logoColor=white
[MCP-url]: https://github.com/modelcontextprotocol/typescript-sdk
[Express]: https://img.shields.io/badge/Express-000000?style=for-the-badge&logo=express&logoColor=white
[Express-url]: https://expressjs.com/
[Zod]: https://img.shields.io/badge/Zod-3E67B1?style=for-the-badge&logo=zod&logoColor=white
[Zod-url]: https://zod.dev/
