MCP、浏览器与外部工具集成

本页说明仓库中 MCP 外部工具客户端、浏览器自动化能力及其相关实验性运行时的边界、组成和集成位置。由于本页的源代码读取预算已耗尽，以下内容仅陈述已从目录索引、交叉引用和工程配置中直接确认的事实；具体方法签名、传输协议细节和运行时错误处理需要在后续源代码审阅中补充。

Purpose and Scope

本页覆盖以下相互关联的能力：

• packages/mcp/mcp-client：MCP 客户端实现目录，已确认包含连接、传输、服务端上下文和工具定义相关模块。
• packages/browser-use/browser-use：浏览器使用能力的稳定包目录，已确认包含 brand.ts、index.ts 及注册表测试。
• 工程配置中声明的浏览器 MCP 实验包：packages/experimental/browser-use-playwright-mcp 与 packages/experimental/browser-use-chrome-devtools-mcp。
• 与上述能力相邻的浏览器运行时与原生实现入口：packages/experimental/browser-use-runtime、packages/experimental/browser-use-stagehand-native。

本页不展开桌面端 UI、计算机视觉/桌面交互、通用 API 控制器或具体 Web UI 测试流程；这些能力在仓库中有独立目录，应由相应目录或目录级 Wiki 页面说明。仓库的组织约定也明确将 browser-use/ 定义为浏览器交互，将 mcp/ 定义为外部工具。

Overview

该能力集合将外部工具调用分成两层：MCP 客户端负责与 MCP 服务端建立通信并暴露工具相关能力；浏览器使用包则提供浏览器交互领域的公共入口，实验性包将具体浏览器后端或协议适配器接入工程。

从当前可验证的工程结构看，设计意图是把协议/连接层与浏览器领域能力分开：mcp-client 目录承载通用 MCP 机制，而 Playwright、Chrome DevTools 等浏览器适配位于 experimental 下。这种分层允许浏览器实现快速迭代，同时避免把特定浏览器后端耦合进通用客户端。

Architecture

下图只表示已由工程配置确认的包级依赖关系和目录角色，不推断尚未读取的类、函数或具体调用顺序。

Source: tsconfig.host.json

工程配置将 mcp-client 及浏览器相关包纳入 host 项目引用；同时，仓库导航约定确认 mcp 是外部工具领域、browser-use 是浏览器交互领域。由于实现文件未能在预算内读取，图中的箭头应理解为“工程集成/包编排关系”，而不是未经证实的运行时调用链。

Main Content

MCP 客户端的已确认模块边界

packages/mcp/mcp-client/src 中已确认存在以下模块：

目录中同时存在针对 apply、egress、协议、协商生命周期、重连、服务端上下文和工具定义的测试文件。这些文件名表明该客户端关注生命周期协商、断线重连、出口行为、协议兼容性和工具定义；但在未读取测试正文前，不能把这些关注点提升为具体保证，也不能推断重试次数、超时或异常类型。

浏览器集成的包级分层

稳定浏览器包 packages/browser-use/browser-use 当前可确认包含公共入口 src/index.ts、品牌定义 src/brand.ts 和注册表测试。浏览器 MCP 的两个具体适配包位于 packages/experimental，名称分别指向 Playwright 和 Chrome DevTools；另有浏览器运行时与 Stagehand 原生实现包。

这种目录安排支持以下扩展边界：新增浏览器后端时，优先在 packages/experimental 中增加适配包；通用 MCP 连接机制应继续留在 packages/mcp/mcp-client；稳定的浏览器领域公共 API 则应通过 packages/browser-use/browser-use 暴露。具体扩展接口名称和注册流程尚未从实现中确认。

Core Flow

下图是基于已确认模块名称的保守流程图，重点展示包级职责，不伪造具体方法名或协议消息。

Sources:

• connection.ts
• transport.ts
• index.ts

上图中的具体消息格式、同步/异步方式、错误分支和结果映射均未读取源代码，因此不能作为 API 契约使用。

Usage Examples

代码示例可用性

No code example available。当前源代码工具预算在读取实现文件前已达到上限，因此不能安全提取可运行的 MCP 客户端或浏览器调用示例。根据“不得猜测 API 签名”的约束，本页不生成假定的导入路径、构造函数或调用代码。

Configuration Options

当前已确认的配置证据是 tsconfig.host.json 中的项目引用，而不是运行时配置键。未读取 package.json、环境变量定义或各包配置文件，因此无法可靠列出选项、类型或默认值。

API Reference

具体 API 参考暂不可提供：虽然 mcp-client/src/index.ts 和 browser-use/src/index.ts 已被文件发现，但实现正文未能读取，无法确认导出符号、参数、返回类型或异常。请勿根据文件名推断 API。

Failure Modes, Edge Cases & Concurrency

目录与测试文件名确认该能力存在重连、协商生命周期、协议、出口和工具定义测试关注点，但没有足够源代码证据描述其行为。以下项目因此明确标记为待补充，而非假定结论：

• 连接失败与重连：存在 reconnect.spec.ts，但重连触发条件、退避策略和最大次数未确认。
• 协议协商：存在 negotiation-lifecycle.spec.ts 与 protocol.spec.ts，但兼容性规则和失败响应未确认。
• 出口/安全边界：存在 egress.spec.ts，但允许/拒绝策略未确认。
• 工具输入与返回值：存在 tool-definition.spec.ts，但校验和序列化约束未确认。
• 并发行为：当前证据不足以判断连接是否可并发复用、工具调用是否排队，或上下文是否线程/任务安全。

Performance, Operations and Extension Points

工程配置把浏览器 MCP 后端放在实验性包中，说明这些后端与稳定公共包之间存在明确的演进边界；但不能据此推断性能目标或生产可用性等级。

可确认的扩展方向是包级扩展：浏览器后端适配可以沿用 browser-use-playwright-mcp 或 browser-use-chrome-devtools-mcp 所代表的独立包边界，通用 MCP 机制则应复用 mcp-client。实际接口、注册机制、资源释放要求和观测指标需要基于实现与测试进一步确认。

Related Links

• AGENTS.md — 仓库对 browser-use 与 mcp 领域的目录约定。
• tsconfig.host.json — MCP、浏览器及实验性浏览器包的 host 项目引用。
• MCP client connection.ts — 连接模块入口（实现细节待审阅）。
• MCP client transport.ts — 传输模块入口（实现细节待审阅）。
• Browser-use index.ts — 浏览器使用包公共入口（实现细节待审阅）。