Browse Together MCP

Browse Together MCP

使用 MCP 服务的 Playwright 浏览器代理

在桌面上运行 Playwright 浏览器和 MCP 服务。你可以启动一个有头浏览器（供人类交互使用）及配套的 MCP 服务，通过 HTTP API 或 MCP 服务控制浏览器。

本项目提供两项互补的服务，用于浏览器自动化和共同浏览：

• 浏览器代理服务：通过 HTTP 控制持久运行的 Playwright 浏览器实例。让你像平常一样登录所使用的服务。
• MCP 服务：通过 FastMCP 框架向 MCP 客户端（如 Claude Desktop）提供浏览器功能。它可以在你提供的已认证会话中运行，让你的 MCP 命令以已认证用户的身份拥有更强大的功能和更广泛的用途。

这两项服务均使用 Deno 和 TypeScript 构建，可无缝协同工作。

功能

• 多浏览器支持：可使用 Chromium（默认）或 Firefox 运行。
• 持久浏览器会话：单个浏览器实例在服务运行期间持续运行。
• 命名标签页：使用唯一 ID 控制单个浏览器会话中的多个页面（标签页）。
• HTTP API：通过 HTTP 使用简单的 JSON 命令与浏览器交互。
• MCP 集成：通过 Cline、Windsurf、Claude Desktop 或其他 MCP 客户端使用浏览器。
• 类型安全：使用 Zod 对传入命令进行可靠验证。
• 使用 API 令牌保护浏览器代理服务（HTTP）端点。

注意：目前支持 Mac OS，但只需稍作修改即可扩展至其他平台。

这是 Computer Use / Operator 吗？

目前还不是。这是一个有头网页浏览器，其行为与普通的人工控制浏览器相同，但也允许你通过 HTTP API 或 MCP 客户端控制会话。虽然你可以获取屏幕截图、下载文档等，但它并不是 Computer Use / Operator 服务。

可以把它看作基于 MCP 的浏览器会话远程控制工具，用于在编码时下载文档或执行其他任务。

核心组件

• 浏览器服务：

  • browser.ts：浏览器代理服务的主要实现
  • types.ts：使用 Zod 定义命令结构和类型

• MCP 服务：

  • mcp.ts：连接浏览器服务的 FastMCP 实现

使用方法

开发者快速入门

0. 安装先决条件： 安装 Playwright 的浏览器包（假设你已安装 npx）：

   # Install all browsers
   npx playwright install
   
   # Or install specific browsers
   npx playwright install chromium
   npx playwright install firefox
   

   安装 Deno：

   curl -fsSL https://deno.land/install.sh | sh
   

   更多详情请参阅 Deno 安装指南。

1. 启动浏览器服务：

   deno task browser
   

   这会在 http://localhost:8888（或你在环境中指定的端口）启动浏览器代理

2. 配置 MCP 客户端：

   {
       "mcpServers": {
    	   "browse-together": {
    		   "command": "deno",
    		   "args": ["run", "-A", "/Users/duane/Projects/browse-together-mcp/mcp.ts"]
         },
     }
   }
   

   你也可以直接启动 MCP 服务进行测试：

   deno task mcp
   

浏览器选择

你可以通过设置 BROWSER_TYPE 环境变量或使用 --browser-type 标志来选择要使用的浏览器：

# Use Firefox via environment variable
BROWSER_TYPE=firefox deno task browser

# Or via CLI flag
deno task browser --browser-type firefox

选项 1：通过 HTTP API 交互

向 /api/browser/:pageId 发送 POST 请求，并在 JSON 请求体中描述操作。

示例：导航至 URL

curl -X POST http://localhost:8888/api/browser/myTab \
  -H "Content-Type: application/json" \
  -d '{"action":"goto","url":"https://example.com"}'

示例：点击元素

curl -X POST http://localhost:8888/api/browser/myTab \
  -H "Content-Type: application/json" \
  -d '{"action":"click","selector":"#submit-button"}'

更多详情请参阅 002-browser.md 中的 API 参考。

选项 2：与 MCP 客户端搭配使用

1. 通过编辑 claude_desktop_config.json，在 MCP 客户端（例如 Cline、Windsurf、Claude Desktop）中配置 MCP 服务：

{
  "mcpServers": {
    "browse-together": {
      "command": "/path/to/deno", 
      "args": [
        "run",
        "--allow-read",
        "--allow-net",
        "--allow-env",
        "--allow-sys",
        "/path/to/browse-together-mcp/mcp.ts"
      ],
      "env": {
        "PORT": "8888" 
      }
    }
  }
}

2. 在客户端中使用 MCP 工具执行如下命令：

Let's browse to jsr.io together.

可用的 MCP 工具

MCP 服务向客户端提供以下工具：

• goto：导航至 URL
• click：点击元素
• fill：填写表单字段
• content：获取页面 HTML 内容
• fetch：在浏览器上下文中执行 fetch 请求
• listPages：列出所有活动的浏览器页面
• closePage：关闭指定页面

文档

本项目通过一系列描述渐进式规划步骤的文档进行氛围编程：

• 初始设计决策（注意：项目结构描述可能已过时）
• 浏览器代理服务概览（多会话——历史版本）
• 单会话架构重构
• 类型安全计划（Zod）
• 页面韧性计划
• 所用库
• 测试策略
• 配置
• 安全注意事项
• Deno 最佳实践
• MCP 服务实现计划
• FastMCP 重构

其中一些步骤可能已过时或不再适用，但仍作为参考，帮助了解项目的构建过程。

另请参阅 vibe-coders.org，了解更多关于我们位于犹他州桑迪市的本地氛围编程小组的信息。

开发

• 运行浏览器代理： deno task browser
• 运行 MCP 服务： deno task mcp
• 格式化代码： deno fmt
• 检查依赖项： deno check --all browser.ts mcp.ts types.ts

架构

+----------------+      +--------------+      +------------------+
|                |      |              |      |                  |
| Cline/LLM      | ---- | MCP Server   | ---- | Browser Service  |
| (MCP Client)   |      | (mcp.ts)     | HTTP | (browser.ts)     |
|                |      |              |      |                  |
+----------------+      +--------------+      +------------------+
                               |                       |
                          FastMCP API            Playwright API
                               |                       |
                           STDIO/SSE            Chromium Browser

系统的工作方式如下：

1. 浏览器服务（browser.ts）使用 Playwright 管理持久运行的 Chromium 浏览器实例
2. MCP 服务（mcp.ts）使用 FastMCP 提供标准 MCP 接口
3. MCP 服务通过 HTTP 将命令转发给浏览器服务
4. Claude Desktop 等 MCP 客户端可通过简单的工具调用使用所有浏览器功能