# https://github.com/browserbase/mcp-server-browserbase 项目说明书
生成时间: 2026-05-21 16:34:02 UTC
## 目录
- [项目介绍](#page-introduction)
- [安装指南](#page-installation)
- [系统架构](#page-architecture)
- [核心组件](#page-core-components)
- [工具集概述](#page-tools-overview)
- [会话管理](#page-session-management)
- [配置参数](#page-configuration)
- [部署指南](#page-deployment)
- [MCP 客户端集成](#page-mcp-integration)
- [模型配置](#page-model-configuration)
## 项目介绍
### 相关页面
相关主题：[系统架构](#page-architecture), [安装指南](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)
- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)
- [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json)
# 项目介绍
## 1 项目概述
`@browserbasehq/mcp` 是一个基于 Model Context Protocol (MCP) 的服务器实现，专门用于通过 Browserbase 和 Stagehand 实现 AI 驱动的 Web 浏览器自动化操作。该项目为 AI 助手提供了与浏览器交互的能力，支持导航网页、执行操作、观察页面元素以及提取数据等核心功能。
项目基本信息如下：
| 属性 | 值 |
|------|-----|
| 项目名称 | @browserbasehq/mcp |
| 当前版本 | 3.0.0 |
| 许可证 | Apache-2.0 |
| MCP 协议名称 | io.github.browserbase/mcp-server-browserbase |
| 开发者 | Browserbase, Inc. |
| 仓库地址 | https://github.com/browserbase/mcp-server-browserbase |
资料来源：[package.json:1-15]()
## 2 核心功能
该项目作为 MCP 协议的服务器实现，提供了一套完整的浏览器自动化工具集。根据 README.md 的说明，服务器暴露以下核心工具：
| 工具名称 | 功能描述 | 参数 |
|---------|---------|------|
| `start` | 创建新的浏览器会话 | _(none)_ |
| `end` | 关闭浏览器会话 | _(none)_ |
| `navigate` | 导航到指定 URL | `{ url: string }` |
| `act` | 在页面上执行操作 | `{ action: string }` |
| `observe` | 观察页面上的可操作元素 | `{ instruction: string }` |
| `extract` | 从页面提取数据 | `{ instruction?: string }` |
资料来源：[README.md:48-54]()
### 2.1 工具功能详解
#### start 工具
用于启动一个新的浏览器会话。在 3.0.0 版本中，该工具不再接受 `sessionId` 参数，这与之前版本的 `browserbase_session_create` 工具存在差异。
#### end 工具
用于关闭当前活动的浏览器会话，对应旧版本的 `browserbase_session_close`。
#### navigate 工具
通过接收 URL 参数，将浏览器导航到指定网页地址。
#### act 工具
在当前页面执行指定的操作。该操作由 AI 模型理解并转换为实际的浏览器操作。注意：在 3.0.0 版本中，`act` 工具不再接受 `variables` 参数。
#### observe 工具
根据给定的指令观察页面上的可操作元素，帮助 AI 理解页面结构。
#### extract 工具
从当前页面提取数据。`instruction` 参数现在变为可选，与 Browserbase 托管服务保持一致。
资料来源：[CHANGELOG.md:1-30]()
## 3 技术架构
### 3.1 架构概览
项目采用模块化架构设计，主要包含以下核心模块：
```mermaid
graph TD
A[MCP 客户端] --> B[MCP 服务器]
B --> C[工具注册层]
C --> D[上下文管理]
D --> E[会话管理器]
E --> F[Stagehand 实例]
F --> G[Browserbase 云服务]
G --> H[远程浏览器]
```
### 3.2 核心模块职责
#### 入口模块 (src/index.ts)
作为应用程序的主入口，负责初始化 MCP 服务器、注册工具、处理请求路由等核心功能。服务器通过 `server.tool()` 方法注册各个工具，每个工具都关联到对应的处理函数。
```typescript
tools.forEach((tool) => {
if (tool.schema.inputSchema instanceof z.ZodObject) {
server.tool(
tool.schema.name,
tool.schema.description,
tool.schema.inputSchema.shape,
async (params: z.infer) => {
const result = await context.run(tool, params);
return result;
}
);
}
});
```
资料来源：[src/index.ts:1-30]()
#### 配置模块 (src/config.ts)
负责管理和解析应用配置，支持多种配置来源的合并：
- 默认配置
- 环境变量
- 命令行参数
- 配置文件
默认模型为 `google/gemini-2.5-flash-lite`，这与托管 MCP 服务器保持一致。
#### 会话管理器 (src/sessionManager.ts)
负责管理浏览器会话的生命周期，包括：
- 创建新的浏览器会话
- 验证会话状态
- 清理过期会话
- 批量关闭所有会话
- 默认会话的自动维护
会话管理器包含以下关键功能：
| 方法 | 功能 |
|------|------|
| `getOrCreateSession` | 获取或创建会话 |
| `createNewBrowserSession` | 创建新的浏览器会话 |
| `cleanupSession` | 清理指定会话 |
| `closeAllSessions` | 关闭所有会话 |
| `ensureDefaultSession` | 确保默认会话存在 |
资料来源：[src/sessionManager.ts:1-80]()
#### 资源模块 (src/mcp/resources.ts)
实现了 MCP 协议的资源相关接口：
- `listResources()` - 列出可用资源
- `listResourceTemplates()` - 列出资源模板
- `readResource(uri)` - 读取指定资源
当前实现中，资源功能返回空列表。
#### 传输层 (src/transport.ts)
支持两种传输方式：
1. **STDIO** - 标准输入输出传输
2. **SHTTP** - Streamable HTTP 传输
服务器可以监听指定端口，提供 HTTP 服务供支持 SHTTP 的 MCP 客户端连接。
## 4 依赖关系
### 4.1 主要生产依赖
| 依赖包 | 版本 | 用途 |
|--------|------|------|
| @browserbasehq/sdk | ^2.6.0 | Browserbase SDK |
| @browserbasehq/stagehand | ^3.3.0 | 浏览器自动化框架 |
| @modelcontextprotocol/sdk | ^1.13.1 | MCP 协议实现 |
| commander | ^14.0.0 | 命令行参数解析 |
| dotenv | ^16.4.6 | 环境变量加载 |
| zod | ^3.25.67 | 数据验证 |
资料来源：[package.json:27-35]()
### 4.2 关键外部服务
- **Browserbase** - 提供云端浏览器基础设施
- **Stagehand** - AI 驱动的浏览器自动化框架
- **Gemini** - 默认使用的 AI 模型（由 GEMINI_API_KEY 或 GOOGLE_API_KEY 配置）
## 5 部署方式
项目支持两种部署方式：
### 5.1 直接安装
```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build
```
### 5.2 Docker 部署
```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .
```
## 6 配置说明
### 6.1 环境变量
| 变量名 | 必填 | 说明 |
|--------|------|------|
| BROWSERBASE_API_KEY | 是 | Browserbase API 密钥 |
| BROWSERBASE_PROJECT_ID | 是 | Browserbase 项目 ID |
| GEMINI_API_KEY | 是 | Gemini API 密钥（默认模型使用） |
| GOOGLE_API_KEY | 否 | Google API 密钥（备用） |
### 6.2 命令行参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `--proxies` | boolean | 启用代理 |
| `--verified` | boolean | 启用验证模式 |
| `--advancedStealth` | boolean | 启用高级隐身模式 |
| `--contextId` | string | 指定上下文 ID |
| `--persist` | boolean | 持久化会话 |
| `--port` | number | HTTP 服务器端口 |
| `--host` | string | HTTP 服务器主机 |
| `--browserWidth` | number | 浏览器宽度 |
| `--browserHeight` | number | 浏览器高度 |
| `--modelName` | string | 使用的模型名称 |
| `--modelApiKey` | string | 模型 API 密钥 |
| `--keepAlive` | boolean | 保持连接活跃 |
| `--experimental` | boolean | 启用实验性功能 |
资料来源：[src/config.ts:10-28]()
### 6.3 MCP 客户端配置示例
#### STDIO 模式（自托管）
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": ["/path/to/mcp-server-browserbase/cli.js"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
#### NPM 模式
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
#### SHTTP 模式（托管服务）
```json
{
"mcpServers": {
"browserbase": {
"type": "http",
"url": "https://mcp.browserbase.com/mcp"
}
}
}
```
资料来源：[README.md:20-70]()
## 7 版本演进
### 7.1 3.0.0 版本重大变更
v3.0.0 版本带来了多项重大变更：
- **工具重命名**：所有工具名称与托管服务保持一致
- `browserbase_session_create` → `start`
- `browserbase_session_close` → `end`
- `browserbase_stagehand_navigate` → `navigate`
- `browserbase_stagehand_act` → `act`
- `browserbase_stagehand_observe` → `observe`
- `browserbase_stagehand_extract` → `extract`
- **移除的工具**：
- `browserbase_screenshot`
- `browserbase_stagehand_get_url`
- `browserbase_stagehand_agent`
- **参数变更**：
- `act` 工具不再接受 `variables` 参数
- `start` 工具不再接受 `sessionId` 参数
- `extract` 工具的 `instruction` 参数变为可选
- **默认模型变更**：从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`
- **依赖更新**：Stagehand 版本升级至 3.3.0
资料来源：[CHANGELOG.md:1-30]()
## 8 传输协议支持
项目同时支持两种 MCP 传输协议：
```mermaid
graph LR
A[MCP 客户端] --> B{传输协议选择}
B --> C[STDIO]
B --> D[SHTTP]
C --> E[本地服务器]
D --> F[远程托管服务]
E --> G[自托管 MCP 服务器]
F --> H[mcp.browserbase.com]
```
### 8.1 STDIO 传输
适用于本地运行场景，服务器通过标准输入输出与客户端通信。推荐使用 NPM 包 `@browserbasehq/mcp` 或直接运行构建后的代码。
### 8.2 SHTTP 传输
适用于使用托管服务场景。Browserbase 提供托管的 MCP 服务器，地址为 `https://mcp.browserbase.com/mcp`。这种方式可以免除本地运行和 LLM 成本。
## 9 项目结构
```
mcp-server-browserbase/
├── src/
│ ├── index.ts # 主入口
│ ├── context.ts # 上下文管理
│ ├── config.ts # 配置管理
│ ├── sessionManager.ts # 会话管理
│ ├── transport.ts # 传输层
│ ├── mcp/
│ │ └── resources.ts # 资源接口
│ └── tools/
│ └── extract.ts # 提取工具
├── cli.js # 命令行入口
├── package.json # 包配置
├── server.json # 服务器元数据
└── README.md # 项目文档
```
## 10 相关资源
- [Browserbase MCP 文档](https://docs.browserbase.com/integrations/mcp/introduction)
- [MCP 协议文档](https://modelcontextprotocol.io/docs)
- [MCP 协议规范](https://spec.modelcontextprotocol.io/)
- [Stagehand 文档](https://docs.stagehand.dev/)
---
## 安装指南
### 相关页面
相关主题：[项目介绍](#page-introduction), [部署指南](#page-deployment)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
- [Dockerfile](https://github.com/browserbase/mcp-server-browserbase/blob/main/Dockerfile)
- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)
# 安装指南
本页面详细介绍如何安装和配置 mcp-server-browserbase。MCP 服务器（Model Context Protocol Server）是 Browserbase 提供的 AI 网页自动化解决方案，通过集成 Stagehand 实现智能浏览器操作功能。
## 系统要求
### 运行环境
| 要求项 | 最低版本 | 推荐版本 |
|--------|----------|----------|
| Node.js | 18.x | 20.x LTS |
| npm/pnpm | 8.x | 最新稳定版 |
| Docker | 24.x | 最新稳定版 |
| Git | 2.x | 最新稳定版 |
### 环境变量配置
在开始安装前，需要准备以下环境变量：
| 环境变量 | 必填 | 说明 |
|----------|------|------|
| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |
| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目 ID |
| `GEMINI_API_KEY` | 是 | Gemini 模型 API 密钥（用于默认模型） |
> [!TIP]
> 如需使用其他模型，可通过 `--modelName` 参数指定，并提供对应的 API 密钥。
资料来源：[README.md:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
## 安装方式
mcp-server-browserbase 支持三种安装方式，适用于不同的使用场景：
| 安装方式 | 适用场景 | 复杂度 | 更新维护 |
|----------|----------|--------|----------|
| NPM（推荐） | 快速集成、主流用户 | 低 | 自动 |
| 直接安装 | 本地开发、自定义修改 | 中 | 手动 |
| Docker | 生产环境、隔离部署 | 中 | 手动 |
资料来源：[README.md:40-80](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
### 方式一：NPM 安装（推荐）
NPM 安装是最简洁的方式，适合大多数用户快速上手。
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
#### 安装步骤
1. 确保已安装 Node.js 18+ 和 npm
2. 在 MCP 配置文件中添加上述配置
3. 填写对应的环境变量值
4. 重启 MCP 客户端即可使用
### 方式二：直接安装
直接安装适合需要自定义修改或本地开发的用户。
#### 前置条件
- Git 已安装
- Node.js 18+ 已安装
- npm 或 pnpm 包管理器
#### 安装命令
```bash
# 克隆仓库
git clone https://github.com/browserbase/mcp-server-browserbase.git
# 进入项目目录
cd mcp-server-browserbase
# 安装依赖并构建
npm install && npm run build
```
#### MCP 配置
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": ["/path/to/mcp-server-browserbase/cli.js"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
资料来源：[README.md:10-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
### 方式三：Docker 安装
Docker 安装提供完整的隔离环境，适合生产部署。
#### 构建镜像
```bash
# 克隆仓库
git clone https://github.com/browserbase/mcp-server-browserbase.git
# 进入项目目录
cd mcp-server-browserbase
# 构建 Docker 镜像
docker build -t mcp-browserbase .
```
#### MCP 配置
```json
{
"mcpServers": {
"browserbase": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"BROWSERBASE_API_KEY",
"-e",
"BROWSERBASE_PROJECT_ID",
"-e",
"GEMINI_API_KEY",
"mcp-browserbase"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
资料来源：[README.md:20-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
## 传输方式配置
MCP 服务器支持两种传输协议，根据 MCP 客户端能力选择合适的传输方式：
| 传输方式 | 说明 | 端口 | 推荐场景 |
|----------|------|------|----------|
| SHTTP（Streamable HTTP） | 推荐方式，性能最优 | 动态 | 支持 HTTP 的客户端 |
| STDIO | 标准输入输出 | 无 | 命令行工具、本地开发 |
资料来源：[src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)
### SHTTP（托管服务）
使用 Browserbase 托管的 MCP 服务器地址 `https://mcp.browserbase.com/mcp`，这是最简便的启动方式。
#### 支持 SHTTP 的客户端配置
```json
{
"mcpServers": {
"browserbase": {
"type": "http",
"url": "https://mcp.browserbase.com/mcp"
}
}
}
```
#### 不支持 SHTTP 的客户端配置
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
}
}
}
```
资料来源：[README.md:60-90](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
### STDIO（自托管）
STDIO 方式允许完全本地运行服务器。
#### NPM 方式运行
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
#### 本地完全自托管
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": [
"-y",
"@anthropic/mcp-remote",
"node",
"/path/to/mcp-server-browserbase/dist/index.js",
"--apiKey",
"your-anthropic-api-key"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": ""
}
}
}
}
```
> [!NOTE]
> 如需使用不同的模型，需要添加 `--modelName` 参数并提供对应的密钥。
资料来源：[README.md:95-130](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
## 命令行参数配置
服务器支持丰富的命令行参数，用于自定义部署行为：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--proxies` | boolean | false | 启用代理功能 |
| `--verified` | boolean | false | 启用验证模式 |
| `--advancedStealth` | boolean | false | 启用高级隐身模式 |
| `--contextId` | string | - | 指定上下文 ID |
| `--persist` | boolean | false | 持久化会话 |
| `--port` | number | - | HTTP 服务端口 |
| `--host` | string | - | HTTP 服务主机 |
| `--browserWidth` | number | 1024 | 浏览器窗口宽度 |
| `--browserHeight` | number | 768 | 浏览器窗口高度 |
| `--modelName` | string | google/gemini-2.5-flash-lite | 使用的模型名称 |
| `--modelApiKey` | string | - | 模型 API 密钥 |
| `--keepAlive` | boolean | false | 保持连接活跃 |
| `--experimental` | boolean | false | 启用实验性功能 |
资料来源：[src/config.ts:1-40](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
### 配置合并优先级
系统配置采用分层合并策略，优先级从低到高如下：
1. **默认配置** - 代码中的硬编码默认值
2. **文件配置** - 配置文件中的设置
3. **CLI 参数** - 命令行传入的参数（最高优先级）
```mermaid
graph TD
A[默认配置] --> B[合并文件配置]
B --> C[合并CLI参数]
C --> D[最终配置]
```
资料来源：[src/config.ts:45-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
## 项目结构与构建
### 项目依赖
主要生产依赖包括：
| 依赖包 | 版本 | 用途 |
|--------|------|------|
| `@browserbasehq/sdk` | ^2.6.0 | Browserbase SDK |
| `@browserbasehq/stagehand` | ^3.3.0 | 浏览器自动化框架 |
| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP 协议实现 |
| `commander` | ^14.0.0 | 命令行工具 |
| `dotenv` | ^16.4.6 | 环境变量加载 |
| `zod` | ^3.25.67 | 数据验证 |
资料来源：[package.json:30-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
### 构建命令
| 命令 | 说明 |
|------|------|
| `npm run build` | 编译 TypeScript 并设置权限 |
| `npm run watch` | 监听模式编译 |
| `npm test` | 运行测试 |
| `npm run inspector` | 启动 MCP 检查器 |
#### 构建流程
```bash
# 开发构建
npm install && npm run build
# 监听模式（开发时使用）
npm run watch
# 运行测试
npm test
```
资料来源：[package.json:20-35](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
## 完整配置示例
### 开发环境配置
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "bb-api-key-dev",
"BROWSERBASE_PROJECT_ID": "project-dev-123",
"GEMINI_API_KEY": "gemini-dev-key"
}
}
}
}
```
### 生产环境配置（Docker）
```json
{
"mcpServers": {
"browserbase": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"BROWSERBASE_API_KEY",
"-e",
"BROWSERBASE_PROJECT_ID",
"-e",
"GEMINI_API_KEY",
"mcp-browserbase"
],
"env": {
"BROWSERBASE_API_KEY": "bb-api-key-prod",
"BROWSERBASE_PROJECT_ID": "project-prod-456",
"GEMINI_API_KEY": "gemini-prod-key"
}
}
}
}
```
### 自定义模型配置
如需使用不同的 AI 模型：
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": [
"@browserbasehq/mcp",
"--modelName",
"anthropic/claude-sonnet-4"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"ANTHROPIC_API_KEY": ""
}
}
}
}
```
> [!WARNING]
> 使用的模型必须在 Stagehand 支持的模型列表中。详情请参阅 [Stagehand 文档](https://docs.stagehand.dev/examples/custom_llms#supported-llms)。
资料来源：[README.md:130-160](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
## 验证安装
安装完成后，可以通过 MCP 检查器验证服务器是否正常工作：
```bash
# 使用 npm 脚本启动检查器
npm run inspector
```
检查器将启动可视化界面，可以测试 MCP 服务器的各项功能和工具。
资料来源：[package.json:24](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
## 故障排除
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 连接失败 | 环境变量未设置 | 检查 `BROWSERBASE_API_KEY` 等变量 |
| 模型调用失败 | API 密钥无效 | 验证 `GEMINI_API_KEY` |
| 浏览器启动失败 | 权限问题 | 确保 Docker 有足够权限 |
| 构建失败 | Node 版本过低 | 升级到 Node.js 18+ |
### 环境变量验证
在启动服务器前，可以创建 `.env` 文件管理环境变量：
```bash
# 创建 .env 文件
cat > .env << EOF
BROWSERBASE_API_KEY=your_api_key_here
BROWSERBASE_PROJECT_ID=your_project_id_here
GEMINI_API_KEY=your_gemini_key_here
EOF
```
资料来源：[src/config.ts:1-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
## 相关资源
- [Browserbase MCP 官方文档](https://docs.browserbase.com/integrations/mcp/introduction)
- [MCP 协议文档](https://modelcontextprotocol.io/docs)
- [MCP 协议规范](https://spec.modelcontextprotocol.io/)
- [Stagehand 文档](https://docs.stagehand.dev/)
- [GitHub 仓库](https://github.com/browserbase/mcp-server-browserbase)
---
## 系统架构
### 相关页面
相关主题：[项目介绍](#page-introduction), [核心组件](#page-core-components)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)
- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)
- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)
- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)
- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)
# 系统架构
## 概述
mcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 模型提供网页自动化能力。该服务器通过集成 Browserbase 基础设施和 Stagehand 浏览器自动化框架，使 LLM 能够通过标准化接口执行网页操作。
资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
## 核心架构组件
### 组件层次结构
```mermaid
graph TB
subgraph "客户端层"
MCP_CLIENT[MCP 客户端]
end
subgraph "传输层"
STDIO[STDIO 传输]
HTTP[HTTP/SHTTP 传输]
end
subgraph "核心服务层"
MCP_SERVER[MCP 服务器]
SERVER_LIST[ServerList 管理器]
end
subgraph "业务逻辑层"
CONTEXT[Context 上下文]
SESSION_MANAGER[SessionManager 会话管理器]
end
subgraph "工具层"
START[start 工具]
END[end 工具]
NAVIGATE[navigate 工具]
ACT[act 工具]
OBSERVE[observe 工具]
EXTRACT[extract 工具]
end
subgraph "外部集成"
STAGEHAND[Stagehand 框架]
BROWSERBASE[Browserbase SDK]
end
MCP_CLIENT --> STDIO
MCP_CLIENT --> HTTP
STDIO --> MCP_SERVER
HTTP --> MCP_SERVER
MCP_SERVER --> CONTEXT
CONTEXT --> SESSION_MANAGER
SESSION_MANAGER --> STAGEHAND
STAGEHAND --> BROWSERBASE
START --> SESSION_MANAGER
END --> SESSION_MANAGER
NAVIGATE --> CONTEXT
ACT --> CONTEXT
OBSERVE --> CONTEXT
EXTRACT --> CONTEXT
```
### 组件职责表
| 组件名称 | 文件位置 | 职责描述 |
|---------|---------|---------|
| MCP_SERVER | src/index.ts | 注册 MCP 协议处理器，注册工具，处理请求路由 |
| ServerList | src/server.ts | 管理多个服务器实例的生命周期 |
| SessionManager | src/sessionManager.ts | 管理浏览器会话创建、验证、清理和复用 |
| Context | src/context.ts | 提供工具执行上下文，集成 Stagehand 实例 |
| Transport | src/transport.ts | 处理 HTTP 服务器启动和请求分发 |
资料来源：[src/index.ts:1-100](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)
## 传输层架构
### 支持的传输方式
该服务器支持两种传输协议，通过命令行参数指定：
| 传输类型 | 配置方式 | 使用场景 |
|---------|---------|---------|
| STDIO | 命令行直接运行 | 本地部署，推荐用于 Claude Desktop |
| HTTP/SHTTP | 启动 HTTP 服务器 | 远程部署，支持流式 HTTP |
### HTTP 传输实现
```mermaid
graph LR
A[MCP 客户端] -->|HTTP POST /mcp| B[HTTP Server]
B --> C[handleStreamable 函数]
C --> D[ServerList]
D --> E[MCP Server]
E --> F[工具执行]
```
HTTP 服务器在指定端口启动，监听 `/mcp` 端点处理 MCP 请求：
```typescript
httpServer.listen(port, hostname, () => {
const message = [
`Listening on ${url}`,
"Put this in your client config:",
JSON.stringify({
mcpServers: {
browserbase: {
type: "http",
url: `${url}/mcp`,
},
},
}, undefined, 2),
].join("\n");
console.log(message);
});
```
资料来源：[src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)
## 会话管理架构
### SessionManager 设计
SessionManager 是核心的会话管理组件，负责浏览器实例的生命周期管理。
```mermaid
graph TB
subgraph "SessionManager"
browsers[Map]
activeSessionId[当前活动会话ID]
defaultSessionId[默认会话ID: __default__]
cleaningUpSessions[正在清理的会话集合]
defaultSessionCreationPromise[创建互斥锁]
end
subgraph "BrowserSession"
stagehand[Stagehand 实例]
config[会话配置]
end
```
### 会话状态管理
| 状态 | 描述 | 处理逻辑 |
|-----|------|---------|
| VALID | 会话有效且可用 | 直接返回使用 |
| STALE | 会话过期或无响应 | 关闭并重建 |
| MISSING | 会话不存在 | 创建新会话 |
| CREATING | 正在创建中 | 等待创建完成 |
### 关键方法
| 方法 | 功能 | 线程安全 |
|-----|------|---------|
| `ensureDefaultSession()` | 确保默认会话存在 | 使用互斥锁 |
| `getSession()` | 获取或创建指定会话 | 支持并发 |
| `cleanupSession()` | 清理指定会话 | 幂等操作 |
| `closeAllSessions()` | 关闭所有会话 | 批量处理 |
会话验证通过执行简单操作检测可用性：
```typescript
const pages = this.defaultBrowserSession.stagehand.context.pages();
if (!pages || pages.length === 0) {
throw new Error("No pages available");
}
```
资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
## 工具系统架构
### 工具注册流程
```mermaid
graph TD
A[TOOLS 数组] --> B[遍历工具]
B --> C{schema 类型检查}
C -->|ZodObject| D[server.tool 注册]
C -->|非 ZodObject| E[警告日志输出]
D --> F[MCP 服务器就绪]
```
### 内置工具列表
| 工具名称 | 功能 | 必填参数 | 可选参数 |
|---------|------|---------|---------|
| start | 创建新浏览器会话 | 无 | proxies, modelName |
| end | 关闭指定会话 | sessionId | 无 |
| navigate | 导航到指定 URL | url | 无 |
| act | 执行页面操作 | action | 无 |
| observe | 观察可交互元素 | instruction | 无 |
| extract | 提取页面数据 | 无 | instruction |
### 工具执行流程
```mermaid
sequenceDiagram
participant MCP as MCP 客户端
participant Server as MCP Server
participant Context as Context
participant Tool as Tool Handler
participant Stagehand as Stagehand
MCP->>Server: 工具调用请求
Server->>Context: context.run(tool, params)
Context->>Tool: 调用 handle 方法
Tool->>Stagehand: 执行实际操作
Stagehand-->>Tool: 返回结果
Tool-->>Context: 返回 ToolResult
Context-->>Server: 返回执行结果
Server-->>MCP: 返回响应
```
### 工具接口定义
每个工具实现统一的接口结构：
```typescript
interface Tool> {
capability: "core" | "extended";
schema: ToolSchema;
handle: (context: Context, params: z.infer) => Promise;
}
```
资料来源：[src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)
## Context 上下文管理
### 上下文职责
Context 是连接 MCP 协议层和业务逻辑层的桥梁，负责：
1. 提供 Stagehand 实例访问
2. 管理活动会话
3. 工具执行和错误处理
```mermaid
graph TB
subgraph "Context"
sessionManager[SessionManager]
activeSessionId[活动会话ID]
end
Context-->|获取| sessionManager
Context-->|提供| stagehand
```
### 工具执行方法
```typescript
async run(tool: Tool, params: any): Promise {
// 调用工具的 handle 方法
const result = await tool.handle(this, params);
return result;
}
```
资料来源：[src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)
## ServerList 服务器管理
### 设计模式
ServerList 采用工厂模式管理多个服务器实例：
```mermaid
classDiagram
class ServerList {
-_servers: Server[]
-_serverFactory: () => Promise~Server~
+create(): Promise~Server~
+close(server: Server): Promise~void~
+closeAll(): Promise~void~
}
```
### 核心方法
| 方法 | 签名 | 描述 |
|-----|------|-----|
| create | `() => Promise` | 创建新服务器并加入管理 |
| close | `(server: Server) => Promise` | 关闭指定服务器 |
| closeAll | `() => Promise` | 关闭所有服务器 |
资料来源：[src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)
## 数据流架构
### 请求处理流程
```mermaid
graph TD
A[客户端请求] --> B{传输类型}
B -->|STDIO| C[stdio 传输]
B -->|HTTP| D[HTTP 服务器]
C --> E[MCP Server.handle]
D --> E
E --> F[路由到工具处理器]
F --> G[Context.run]
G --> H[Tool.handle]
H --> I[Stagehand 操作]
I --> J[浏览器执行]
J --> K[结果返回]
K --> L[格式化响应]
L --> M[返回给客户端]
```
### 会话创建流程
```mermaid
graph TB
A[start 工具调用] --> B{是否存在默认会话}
B -->|否| C[调用 createNewBrowserSession]
B -->|是| D{会话是否有效}
D -->|有效| E[返回现有会话]
D -->|无效| F[关闭旧会话]
F --> C
C --> G[创建 Stagehand 实例]
G --> H[配置 Browserbase]
H --> I[返回 BrowserSession]
I --> J[存储到 browsers Map]
J --> K[标记为活动会话]
```
## 配置体系
### 环境变量配置
| 变量名 | 必填 | 描述 |
|-------|-----|------|
| BROWSERBASE_API_KEY | 是 | Browserbase API 密钥 |
| BROWSERBASE_PROJECT_ID | 是 | Browserbase 项目 ID |
| GEMINI_API_KEY | 是 | Gemini API 密钥（用于 LLM 操作） |
### 命令行参数
| 参数 | 描述 | 默认值 |
|-----|------|-------|
| `--proxies` | 启用代理支持 | false |
| `--modelName` | 指定使用的模型名称 | google/gemini-2.5-flash-lite |
### MCP 配置示例
**STDIO 模式：**
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": ["/path/to/mcp-server-browserbase/cli.js"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
**HTTP 模式：**
```json
{
"mcpServers": {
"browserbase": {
"type": "http",
"url": "https://mcp.browserbase.com/mcp"
}
}
}
```
## 依赖关系
### 核心依赖
| 依赖包 | 版本 | 用途 |
|-------|-----|-----|
| @modelcontextprotocol/sdk | ^1.13.1 | MCP 协议实现 |
| @browserbasehq/stagehand | ^3.3.0 | 浏览器自动化框架 |
| @browserbasehq/sdk | ^2.6.0 | Browserbase API 客户端 |
| zod | ^3.25.67 | Schema 验证 |
### 开发依赖
| 依赖包 | 版本 | 用途 |
|-------|-----|-----|
| typescript | ^5.6.2 | TypeScript 编译 |
| vitest | ^4.1.2 | 单元测试 |
| eslint | ^9.29.0 | 代码检查 |
| prettier | ^3.6.1 | 代码格式化 |
资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
## 部署模式
### 自托管部署
```mermaid
graph LR
A[本地机器] -->|npm run build| B[构建产物]
B --> C[cli.js]
C --> D[MCP 客户端]
D --> E[Browserbase 云服务]
```
### Docker 部署
```mermaid
graph TB
A[Dockerfile] --> B[docker build]
B --> C[mcp-browserbase 镜像]
C --> D[docker run]
D --> E[MCP 客户端连接]
```
构建命令：
```bash
docker build -t mcp-browserbase .
```
运行配置：
```json
{
"command": "docker",
"args": ["run", "--rm", "-i", "-e", "BROWSERBASE_API_KEY", "-e", "BROWSERBASE_PROJECT_ID", "-e", "GEMINI_API_KEY", "mcp-browserbase"]
}
```
## 安全考虑
### 会话隔离
- 每个会话独立的 BrowserSession 实例
- 会话清理使用互斥锁防止竞态条件
- 过期会话自动检测和清理
### 错误处理
```mermaid
graph TB
A[异常发生] --> B{异常类型}
B -->|Stagehand 错误| C[记录错误日志]
B -->|会话无效| D[清理会话]
B -->|创建失败| E[重试一次]
C --> F[返回错误响应]
D --> F
E --> G{重试成功?}
E -->|否| F
G -->|是| H[返回成功]
```
### 敏感信息管理
- API 密钥通过环境变量传递
- 不在日志中输出敏感配置
- 命令行参数支持但不推荐传递密钥
## 扩展性设计
### 添加新工具
1. 在 `src/tools/` 目录创建新工具文件
2. 实现 Tool 接口的 schema 和 handle 方法
3. 将工具添加到 TOOLS 数组导出
4. 工具将自动注册到 MCP 服务器
### 自定义传输
传输层支持扩展，可通过修改 `src/transport.ts` 添加新的传输协议实现。
## 总结
mcp-server-browserbase 采用分层架构设计，通过清晰的责任分离实现了：
- **可维护性**：各组件职责明确，易于理解和修改
- **可扩展性**：工具系统支持灵活扩展新功能
- **可靠性**：会话管理和错误处理机制完善
- **兼容性**：支持多种 MCP 客户端和部署方式
该架构为 AI 模型提供了标准化的网页自动化接口，同时保持了与 Browserbase 生态系统的深度集成。
---
## 核心组件
### 相关页面
相关主题：[系统架构](#page-architecture), [工具集概述](#page-tools-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)
- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)
- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)
- [src/mcp/resources.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts)
- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)
- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)
- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)
- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
# 核心组件
本文档详细介绍了 `mcp-server-browserbase` 项目的核心组件架构，包括配置管理、会话管理、工具系统、传输层和上下文管理等关键模块。
## 概述
mcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于通过 Browserbase 和 Stagehand 实现 AI 网页自动化。该项目采用 TypeScript 开发，使用 `@modelcontextprotocol/sdk` 作为 MCP 协议的实现基础。
**项目技术栈：**
| 类别 | 技术/库 |
|------|---------|
| 核心框架 | `@modelcontextprotocol/sdk: ^1.13.1` |
| 浏览器自动化 | `@browserbasehq/stagehand: ^3.3.0` |
| 浏览器控制 | `@browserbasehq/sdk: ^2.6.0` |
| 数据验证 | `zod: ^3.25.67` |
| CLI 参数解析 | `commander: ^14.0.0` |
| 环境变量 | `dotenv: ^16.4.6` |
资料来源：[package.json:1-30]()
## 架构概览
```mermaid
graph TD
A[MCP 客户端] -->|STDIO/SHTTP| B[MCP Server]
B --> C[ServerList]
C --> D[SessionManager]
D --> E[Stagehand 实例]
E --> F[浏览器会话]
B --> G[Context]
G --> H[工具系统]
H --> I[extract]
H --> J[act]
H --> K[navigate]
H --> L[observe]
B --> M[Resources]
B --> N[Transport]
```
## 1. 配置管理 (Config)
### 1.1 配置结构
配置管理模块负责集中管理所有运行时配置选项，包括环境变量、CLI 参数和默认配置值。
资料来源：[src/config.ts:1-5]()
**CLI 选项类型定义：**
```typescript
export type CLIOptions = {
proxies?: boolean;
verified?: boolean;
advancedStealth?: boolean;
contextId?: string;
persist?: boolean;
port?: number;
host?: string;
browserWidth?: number;
browserHeight?: number;
modelName?: string;
modelApiKey?: string;
keepAlive?: boolean;
experimental?: boolean;
};
```
资料来源：[src/config.ts:10-25]()
### 1.2 默认配置值
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `browserbaseApiKey` | `BROWSERBASE_API_KEY` 环境变量 | Browserbase API 密钥 |
| `browserbaseProjectId` | `BROWSERBASE_PROJECT_ID` 环境变量 | Browserbase 项目 ID |
| `proxies` | `false` | 是否启用代理 |
| `browserWidth` | `1024` | 浏览器窗口宽度 |
| `browserHeight` | `768` | 浏览器窗口高度 |
| `modelName` | `google/gemini-2.5-flash-lite` | 默认模型名称 |
| `modelApiKey` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | 模型 API 密钥 |
资料来源：[src/config.ts:28-40]()
### 1.3 配置合并策略
配置采用分层合并策略，优先级顺序为：**默认值 < 文件配置 < CLI 参数**
```typescript
export async function resolveConfig(cliOptions: CLIOptions): Promise {
const cliConfig = await configFromCLIOptions(cliOptions);
const mergedConfig = normalizeVerifiedConfig(
mergeConfig(defaultConfig, cliConfig),
);
// 环境变量补充
if (!mergedConfig.modelApiKey) {
mergedConfig.modelApiKey =
process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
}
return mergedConfig;
}
```
资料来源：[src/config.ts:45-58]()
## 2. 会话管理器 (SessionManager)
### 2.1 概述
SessionManager 是整个系统的核心组件，负责管理多个浏览器会话的生命周期。每个会话对应一个独立的 Stagehand 实例和底层浏览器实例。
资料来源：[src/sessionManager.ts:1-10]()
### 2.2 核心数据结构
```typescript
class SessionManager {
private browsers: Map = new Map();
private defaultSessionId: string = "(default)";
private defaultBrowserSession: BrowserSession | null = null;
private defaultSessionCreationPromise: Promise | null = null;
private activeSessionId: string = "(default)";
private cleaningUpSessions: Set = new Set();
}
type BrowserSession = {
stagehand: Stagehand;
config: Config;
};
```
资料来源：[src/sessionManager.ts:1-50]()
### 2.3 会话生命周期
```mermaid
stateDiagram-v2
[*] --> 创建中: createSession()
创建中 --> 活跃: 创建成功
创建中 --> [*]: 创建失败
活跃 --> 清理中: cleanupSession()
活跃 --> 失效: 检测到过期
失效 --> [*]: 自动清理
清理中 --> [*]: 清理完成
```
### 2.4 主要方法
| 方法 | 功能 | 说明 |
|------|------|------|
| `createSession()` | 创建新会话 | 初始化 Stagehand 实例 |
| `getOrCreateDefaultSession()` | 获取或创建默认会话 | 懒加载机制 |
| `cleanupSession(sessionId)` | 清理指定会话 | 优雅关闭浏览器 |
| `closeAllSessions()` | 关闭所有会话 | 批量清理 |
| `setActiveSessionId(id)` | 设置活跃会话 | 管理当前会话 |
资料来源：[src/sessionManager.ts:60-120]()
### 2.5 会话验证机制
SessionManager 实现了一套完整的会话有效性验证机制：
1. **简单验证**：检查 `pages` 是否存在且数量大于 0
2. **错误捕获**：任何操作异常都会触发会话重建
3. **自动重试**：首次创建失败后自动重试一次
```typescript
// 会话有效性检查示例
const pages = this.defaultBrowserSession.stagehand.context.pages();
if (!pages || pages.length === 0) {
throw new Error("No pages available");
}
```
资料来源：[src/sessionManager.ts:150-180]()
### 2.6 并发控制
为防止重复创建会话，SessionManager 使用 Promise 缓存机制：
```typescript
private defaultSessionCreationPromise: Promise | null = null;
```
当一个会话正在创建时，后续请求会等待同一 Promise，而不是触发新的创建操作。
资料来源：[src/sessionManager.ts:100-110]()
## 3. 上下文管理 (Context)
### 3.1 概述
Context 是工具执行时的运行时上下文，负责协调 SessionManager 和工具之间的交互。
资料来源：[src/context.ts:1-10]()
### 3.2 核心职责
```mermaid
graph LR
A[工具请求] --> B[Context.run]
B --> C[SessionManager]
C --> D[获取 Stagehand]
D --> E[执行工具]
E --> F[返回结果]
```
### 3.3 工具执行流程
```typescript
async run(tool: Tool, params: unknown): Promise {
const session = await this.sessionManager.getOrCreateDefaultSession();
if (tool.handle) {
const result = await tool.handle(this, params);
return result;
}
throw new Error(`Tool ${tool.schema.name} does not have a handle method`);
}
```
资料来源：[src/context.ts:30-50]()
### 3.4 资源管理
Context 还负责 MCP 资源的列表和读取操作：
```typescript
listResources() {
return listResources();
}
readResource(uri: string) {
return readResource(uri);
}
```
资料来源：[src/context.ts:55-65]()
## 4. 工具系统 (Tools)
### 4.1 工具架构
工具系统采用插件化架构，每个工具都是一个独立模块，遵循统一的接口定义。
资料来源：[src/tools/tool.ts:1-40]()
### 4.2 工具类型定义
```typescript
export type Tool = {
capability: string; // 工具能力分类
schema: ToolSchema; // 工具元数据
handle: (context: Context, params: z.output) => Promise;
};
export type ToolResult = {
action?: () => Promise;
waitForNetwork: boolean;
};
```
资料来源：[src/tools/tool.ts:20-35]()
### 4.3 工具定义示例：extract
以下以 `extract` 工具为例说明工具的实现方式：
资料来源：[src/tools/extract.ts:1-50]()
```typescript
const ExtractInputSchema = z.object({
instruction: z.string().optional(),
});
const extractSchema: ToolSchema = {
name: "extract",
description: "Extract data from the page",
inputSchema: ExtractInputSchema,
};
async function handleExtract(
context: Context,
params: ExtractInput,
): Promise {
const action = async (): Promise => {
const stagehand = await context.getStagehand();
const extraction = params.instruction
? await stagehand.extract(params.instruction)
: await stagehand.extract({});
return { content: [{ type: "text", text: JSON.stringify({ success: true, data: extraction }) }] };
};
return { action, waitForNetwork: false };
}
```
资料来源：[src/tools/extract.ts:15-45]()
### 4.4 核心工具列表
| 工具名称 | 功能描述 | 输入参数 |
|----------|----------|----------|
| `start` | 创建新的浏览器会话 | `{ proxies?: boolean, verified?: boolean, ... }` |
| `end` | 关闭当前会话 | - |
| `navigate` | 导航到指定 URL | `{ url: string }` |
| `act` | 执行页面操作 | `{ action: string }` |
| `observe` | 观察页面可交互元素 | `{ instruction: string }` |
| `extract` | 从页面提取数据 | `{ instruction?: string }` |
资料来源：[README.md:1-50]()
### 4.5 工具注册流程
工具通过 `tools.ts` 统一注册到 MCP 服务器：
```typescript
const tools: MCPToolsArray = [...TOOLS];
tools.forEach((tool) => {
if (tool.schema.inputSchema instanceof z.ZodObject) {
server.tool(
tool.schema.name,
tool.schema.description,
tool.schema.inputSchema.shape,
async (params) => {
const result = await context.run(tool, params);
return result;
}
);
}
});
```
资料来源：[src/index.ts:50-80]()
## 5. 传输层 (Transport)
### 5.1 传输方式
mcp-server-browserbase 支持两种传输方式：
| 传输方式 | 说明 | 使用场景 |
|----------|------|----------|
| STDIO | 标准输入输出 | 本地 CLI 工具集成 |
| SHTTP | 流式 HTTP | 远程/托管部署 |
资料来源：[README.md:60-80]()
### 5.2 HTTP 传输实现
```mermaid
graph LR
A[MCP 客户端] -->|HTTP 请求| B[HTTP Server]
B --> C[handleStreamable]
C --> D[ServerList]
D --> E[Server 实例]
```
### 5.3 服务器地址解析
传输层支持动态端口和地址解析：
```typescript
let resolvedHost = address.family === "IPv4"
? address.address
: `[${address.address}]`;
if (resolvedHost === "0.0.0.0" || resolvedHost === "[::]") {
resolvedHost = "localhost";
}
```
资料来源：[src/transport.ts:50-70]()
## 6. 服务器管理 (ServerList)
### 6.1 概述
ServerList 负责管理多个 MCP Server 实例的生命周期。
资料来源：[src/server.ts:1-30]()
### 6.2 类结构
```typescript
export class ServerList {
private _servers: Server[] = [];
private _serverFactory: () => Promise;
async create(): Promise { /* ... */ }
async close(server: Server): Promise { /* ... */ }
async closeAll(): Promise { /* ... */ }
}
```
资料来源：[src/server.ts:5-25]()
## 7. 资源系统 (Resources)
### 7.1 概述
MCP 资源系统提供了只读数据的访问接口。当前实现为空结构，保留扩展能力。
资料来源：[src/mcp/resources.ts:1-20]()
### 7.2 资源定义
```typescript
export const RESOURCES = [];
export const RESOURCE_TEMPLATES = [];
export function listResources() {
return { resources: [] };
}
export function listResourceTemplates() {
return { resourceTemplates: [] };
}
export function readResource(uri: string) {
return { contents: [{ uri, text: `Resource not found: ${uri}` }] };
}
```
资料来源：[src/mcp/resources.ts:1-25]()
## 8. 组件交互关系
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Server as MCP Server
participant Context as Context
participant SessionMgr as SessionManager
participant Tool as Tool Handler
participant Stagehand as Stagehand
Client->>Server: 请求工具调用
Server->>Context: run(tool, params)
Context->>SessionMgr: getOrCreateDefaultSession()
SessionMgr-->>Context: BrowserSession
Context->>Tool: handle(context, params)
Tool->>Stagehand: 执行操作
Stagehand-->>Tool: 操作结果
Tool-->>Context: ToolResult
Context-->>Server: 执行结果
Server-->>Client: MCP 响应
```
## 9. 错误处理机制
### 9.1 工具执行错误
```typescript
try {
const result = await context.run(tool, params);
return result;
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
process.stderr.write(
`[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`
);
throw new Error(`Failed to run tool '${tool.schema.name}': ${errorMessage}`);
}
```
资料来源：[src/index.ts:60-75]()
### 9.2 会话清理错误
SessionManager 在清理会话时使用幂等设计，确保重复清理不会导致问题：
```typescript
if (this.cleaningUpSessions.has(sessionIdToLog)) {
process.stderr.write(
`[SessionManager] Session ${sessionIdToLog} is already being cleaned up, skipping.\n`
);
return;
}
```
资料来源：[src/sessionManager.ts:80-90]()
## 10. 总结
mcp-server-browserbase 的核心组件架构体现了清晰的职责分离：
- **Config** 提供了统一的配置管理
- **SessionManager** 实现了浏览器会话的完整生命周期管理
- **Context** 作为运行时上下文连接各组件
- **Tools** 采用插件化设计便于扩展
- **Transport** 支持多种传输协议
- **ServerList** 管理服务器实例
这套架构确保了系统的可维护性、可扩展性和可靠性。
---
## 工具集概述
### 相关页面
相关主题：[会话管理](#page-session-management), [核心组件](#page-core-components)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)
- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)
- [src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)
- [src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)
- [src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)
- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)
# 工具集概述
## 简介
mcp-server-browserbase 的工具集（Tools）是该 MCP 服务器的核心功能模块，为大语言模型（LLM）提供浏览器自动化操作能力。通过这些工具，AI 模型可以控制浏览器执行网页导航、元素交互、页面观察和数据提取等任务。
工具集基于 [Stagehand](https://www.stagehand.dev) 框架构建，封装了 Playwright 的底层能力，提供声明式的网页操作接口。每个工具都遵循统一的类型定义和注册机制，确保与 MCP 协议的无缝集成。
**核心功能定位：**
- 为 AI Agent 提供浏览器控制能力
- 支持会话级别的浏览器状态管理
- 通过自然语言指令驱动网页自动化操作
## 架构设计
### 工具类型系统
工具系统采用泛型设计，通过 TypeScript 的类型约束确保类型安全。核心类型定义位于 `src/tools/tool.ts` 文件中。
```typescript
export type ToolSchema = {
name: string;
description: string;
inputSchema: Input;
};
```
每个工具包含三个核心属性：
| 属性 | 类型 | 说明 |
|------|------|------|
| `capability` | `string` | 工具能力分类，如 "core" |
| `schema` | `ToolSchema` | 工具元数据，包含名称、描述和输入模式 |
| `handle` | `Function` | 工具执行逻辑，处理输入参数并返回结果 |
**工具执行结果类型：**
```typescript
export type ToolResult = {
action?: () => Promise;
waitForNetwork: boolean;
};
```
资料来源：[src/tools/tool.ts:1-30]()
### 工具执行流程
工具的执行通过 `Context` 类的 `run` 方法统一调度。当 MCP 客户端调用工具时，系统按以下流程处理：
```mermaid
graph TD
A[MCP 客户端请求] --> B[Context.run 调度]
B --> C{工具类型检查}
C -->|标准工具| D[调用 tool.handle]
C -->|代理工具| E[代理转发]
D --> F[Stagehand 执行]
E --> F
F --> G[返回 ToolResult]
G --> H[转换为 MCP 响应]
```
资料来源：[src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)
## 核心工具列表
### 工具注册机制
所有工具通过 `src/tools/index.ts` 统一导出和管理。服务器启动时，工具被批量注册到 MCP 服务器实例：
```typescript
const tools: MCPToolsArray = [...TOOLS];
tools.forEach((tool) => {
if (tool.schema.inputSchema instanceof z.ZodObject) {
server.tool(
tool.schema.name,
tool.schema.description,
tool.schema.inputSchema.shape,
async (params) => {
const result = await context.run(tool, params);
return result;
},
);
}
});
```
资料来源：[src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)
### 工具清单
| 工具名称 | 功能描述 | 输入参数 | 核心能力 |
|----------|----------|----------|----------|
| `start` | 创建新浏览器会话 | `sessionId?: string` | 会话管理 |
| `end` | 关闭浏览器会话 | `sessionId?: string` | 会话管理 |
| `navigate` | 导航至指定 URL | `{ url: string }` | 页面访问 |
| `act` | 执行页面动作 | `{ action: string, variables?: object }` | 元素交互 |
| `observe` | 观察可操作元素 | `{ instruction: string }` | 元素识别 |
| `extract` | 提取页面数据 | `{ instruction?: string }` | 数据采集 |
资料来源：[README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
## 工具详解
### navigate 工具
`navigate` 工具负责将浏览器导航至指定的 URL 地址。
**工具模式定义：**
```typescript
const NavigateInputSchema = z.object({
url: z.string().min(1),
});
const navigateSchema: ToolSchema = {
name: "navigate",
description: "Navigate to a URL",
inputSchema: NavigateInputSchema,
};
```
**输入参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `url` | `string` | 是 | 目标网页 URL，必须为非空字符串 |
**执行逻辑：**
1. 通过 `context.getStagehand()` 获取当前 Stagehand 实例
2. 获取浏览器上下文的页面列表
3. 调用 `page.goto()` 导航至目标 URL
4. 等待 DOM 内容加载完成（`domcontentloaded`）
5. 返回导航结果 JSON
**返回值示例：**
```json
{
"success": true,
"data": {
"url": "https://example.com"
}
}
```
**错误处理：**
- 当没有可用页面时抛出 `"No active page available"`
- 导航失败时抛出具体错误信息
资料来源：[src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)
### act 工具
`act` 工具用于执行页面上的用户操作，如点击、输入文本等。
**工具模式定义：**
```typescript
const ActInputSchema = z.object({
action: z.string().min(1),
});
```
**输入参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `action` | `string` | 是 | 自然语言描述的待执行动作 |
**执行逻辑：**
`act` 工具将自然语言动作描述传递给 Stagehand 的 `act` 方法，由 AI 模型解析并执行相应的网页操作。
资料来源：[src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)
### observe 工具
`observe` 工具用于观察和识别页面上可交互的元素。
**工具模式定义：**
```typescript
const ObserveInputSchema = z.object({
instruction: z.string().min(1),
});
```
**输入参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `instruction` | `string` | 是 | 观察指令，描述要查找的元素或区域 |
**执行逻辑：**
`observe` 工具调用 Stagehand 的 `observe` 方法，识别页面中符合指令描述的可交互元素，并返回识别结果。
资料来源：[src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)
### extract 工具
`extract` 工具用于从当前页面提取结构化数据。
**工具模式定义：**
```typescript
const ExtractInputSchema = z.object({
instruction: z.string().optional(),
});
const extractSchema: ToolSchema = {
name: "extract",
description: "Extract data from the page",
inputSchema: ExtractInputSchema,
};
```
**输入参数：**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `instruction` | `string` | 否 | 可选的提取指令，描述要提取的数据 |
**执行逻辑：**
1. 获取当前 Stagehand 实例
2. 根据是否提供指令参数调用对应的提取方法：
- 有指令时：`stagehand.extract(params.instruction)`
- 无指令时：`stagehand.extract({})`
3. 返回提取结果的 JSON 表示
**返回值示例：**
```json
{
"success": true,
"data": {
"extracted_content": "..."
}
}
```
**设计特点：**
- `instruction` 参数为可选项，设计上兼容无参数的默认提取行为
- 返回值统一封装在 `{ success, data }` 结构中
资料来源：[src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)
## 会话管理
### BrowserSession 结构
工具的执行依赖于 `BrowserSession` 对象，该对象封装了 Stagehand 实例和相关的会话状态：
```typescript
interface BrowserSession {
id: string;
stagehand: Stagehand;
config: Config;
// ... 其他会话状态
}
```
资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
### 会话生命周期
```mermaid
graph LR
A[创建会话] --> B[激活会话]
B --> C[执行工具]
C --> D[验证会话]
D -->|正常| C
D -->|失效| E[清理会话]
E --> A
C --> F[结束会话]
```
**会话创建流程：**
1. 调用 `createSession(config)` 创建新会话
2. 初始化 Stagehand 实例
3. 将会话添加到 `browsers` Map 中
4. 设置为活跃会话
**会话验证机制：**
- 定期检查会话有效性
- 验证页面列表是否存在
- 失效时自动重建会话
资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
## 工具扩展
### 定义新工具
项目提供了 `defineTool` 辅助函数用于标准化工具定义：
```typescript
export function defineTool(
tool: Tool,
): Tool {
return tool;
}
```
**创建新工具的步骤：**
1. 定义 Zod 输入模式
2. 创建工具模式对象（schema）
3. 实现 handle 处理函数
4. 组装并导出工具对象
5. 在 `index.ts` 中注册工具
### 工具能力分类
工具通过 `capability` 属性进行分类：
| 能力值 | 说明 |
|--------|------|
| `core` | 核心工具，MCP 服务器的标准能力 |
| `extended` | 扩展工具，需额外配置启用 |
资料来源：[src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)
## 版本变更记录
### v3.0.0 重大变更
根据 CHANGELOG.md，3.0.0 版本对工具集进行了重大调整：
| 旧工具名 | 新工具名 | 变更类型 |
|----------|----------|----------|
| `browserbase_session_create` | `start` | 重命名 |
| `browserbase_session_close` | `end` | 重命名 |
| `browserbase_stagehand_navigate` | `navigate` | 重命名 |
| `browserbase_stagehand_act` | `act` | 重命名 |
| `browserbase_stagehand_observe` | `observe` | 重命名 |
| `browserbase_stagehand_extract` | `extract` | 重命名 |
| `browserbase_screenshot` | - | 移除 |
| `browserbase_stagehand_get_url` | - | 移除 |
| `browserbase_stagehand_agent` | - | 移除 |
**其他变更：**
- `act` 工具不再接受 `variables` 参数
- `start` 工具不再接受 `sessionId` 参数
- `extract` 工具的 `instruction` 参数改为可选
- 默认模型从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`
资料来源：[CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)
## 总结
mcp-server-browserbase 的工具集提供了完整的浏览器自动化能力封装。通过统一的类型系统、清晰的工具定义模式和模块化的架构设计，开发者可以便捷地扩展新的工具功能，同时保持与 MCP 协议的良好兼容性。工具集的核心价值在于将复杂的网页操作抽象为简单的自然语言指令，使 AI Agent 能够以声明式的方式控制浏览器完成各类自动化任务。
---
## 会话管理
### 相关页面
相关主题：[工具集概述](#page-tools-overview), [配置参数](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
- [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)
- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)
- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)
- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)
- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
# 会话管理
## 概述
会话管理是 MCP Server Browserbase 的核心子系统，负责创建、管理和销毁浏览器会话实例。该系统基于 [Stagehand](https://www.stagehand.dev) 构建，通过 Browserbase 云基础设施提供稳定的浏览器自动化能力。
会话管理器在整个 MCP 服务器中扮演中间层角色，连接上层的 MCP 协议处理与下层的 Stagehand 浏览器实例：
- **上层**：接收 MCP 客户端的工具调用请求
- **中层**：通过 SessionManager 管理会话生命周期和状态同步
- **下层**：调用 Stagehand SDK 执行实际的浏览器操作 资料来源：[src/context.ts:49-56]()
## 核心组件
### BrowserSession 数据结构
```typescript
interface BrowserSession {
page: Page; // Playwright Page 实例
sessionId: string; // Browserbase 会话 ID
stagehand: Stagehand; // Stagehand 实例
}
```
| 字段 | 类型 | 说明 |
|------|------|------|
| `page` | `Page` | Playwright 页面对象，用于执行浏览器操作 |
| `sessionId` | `string` | Browserbase 云端会话的唯一标识符 |
| `stagehand` | `Stagehand` | Stagehand SDK 实例，管理浏览器上下文 |
资料来源：[src/sessionManager.ts:89-93]()
### SessionManager 类
SessionManager 是会话管理的中央控制器，负责维护会话状态机和管理会话集合。
```mermaid
graph TD
subgraph SessionManager 内部状态
BM[browsers: Map]
DS[defaultSessionId: string]
AS[activeSessionId: string]
DBS[defaultBrowserSession: BrowserSession | null]
CP[defaultSessionCreationPromise: Promise | null]
CS[cleaningUpSessions: Set]
end
subgraph 公共接口
GI[getOrCreateSession]
GC[getSession]
CL[cleanupSession]
CA[closeAllSessions]
GA[getActiveSessionId]
end
```
#### 关键属性
| 属性 | 类型 | 默认值 | 用途 |
|------|------|--------|------|
| `browsers` | `Map` | 新建空 Map | 存储所有活跃会话 |
| `defaultSessionId` | `string` | `"default"` | 默认会话标识符 |
| `activeSessionId` | `string` | `"default"` | 当前活跃会话标识符 |
| `defaultBrowserSession` | `BrowserSession \| null` | `null` | 默认会话缓存引用 |
| `defaultSessionCreationPromise` | `Promise \| null` | `null` | 创建互斥锁，防止并发创建 |
| `cleaningUpSessions` | `Set` | 新建空 Set | 跟踪正在清理的会话，防止重复关闭 |
资料来源：[src/sessionManager.ts:75-88]()
## 会话生命周期
### 状态转换图
```mermaid
stateDiagram-v2
[*] --> 不存在: 初始化
不存在 --> 活跃: createNewBrowserSession
活跃 --> 正在清理: cleanupSession / closeAllSessions
正在清理 --> 不存在: close 完成
活跃 --> 正在清理: 验证失败 (stale)
正在清理 --> 活跃: 自动重建 (仅限默认会话)
```
### 创建会话流程
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Context
participant SessionManager
participant Stagehand
participant Browserbase
Client->>Context: 调用 start 工具
Context->>SessionManager: ensureDefaultSessionInternal()
alt 默认会话不存在
SessionManager->>SessionManager: 设置创建互斥锁
SessionManager->>Stagehand: createStagehandInstance()
Stagehand->>Browserbase: 创建云端会话
Browserbase-->>Stagehand: 返回 sessionId
Stagehand-->>SessionManager: 返回 Stagehand 实例
SessionManager->>SessionManager: 存储到 browsers Map
SessionManager->>SessionManager: 缓存到 defaultBrowserSession
SessionManager->>SessionManager: 设置 activeSessionId
else 存在但失效
SessionManager->>SessionManager: 关闭旧会话
SessionManager->>SessionManager: 重新创建
end
SessionManager-->>Context: BrowserSession
Context-->>Client: 返回会话信息
```
#### 创建会话的核心逻辑
```typescript
async createNewBrowserSession(
newSessionId: string,
config: Config,
resumeSessionId?: string,
): Promise
```
**前置条件校验**：
1. 验证 `config.browserbaseApiKey` 存在
2. 验证 `config.browserbaseProjectId` 存在
**创建步骤**：
1. 调用 `createStagehandInstance()` 创建 Stagehand 实例
2. 获取 Playwright Page 实例：`stagehand.context.pages()[0]`
3. 提取 Browserbase Session ID：`stagehand.browserbaseSessionId`
4. 构造 BrowserSession 对象并存储到 Map
资料来源：[src/sessionManager.ts:131-175]()
### 验证与重建机制
SessionManager 实现了自动健康检查机制，确保会话可用性：
```mermaid
graph TD
A[获取会话] --> B{会话存在?}
B -->|否| C[创建新会话]
B -->|是| D{会话有效?}
D -->|是| E[返回会话]
D -->|否| F[关闭失效会话]
F --> G{是默认会话?}
G -->|是| H[自动重建]
G -->|否| I[返回 null]
H --> C
```
**有效性检测**：
```typescript
try {
const pages = sessionObj.stagehand.context.pages();
if (!pages || pages.length === 0) {
throw new Error("No pages available");
}
} catch {
// 标记为 stale，执行清理
}
```
资料来源：[src/sessionManager.ts:114-130]()
## 工具接口
### 会话管理工具列表
| 工具名称 | 描述 | 功能级别 |
|----------|------|----------|
| `start` | 启动新会话 | 核心 |
| `end` | 关闭会话 | 核心 |
资料来源：[src/tools/index.ts:14-15]()
### start 工具
启动一个新的 Browserbase 会话。
**参数结构**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `resumeSessionId` | `string` | 否 | 可选的 Browserbase Session ID，用于恢复已有会话 |
**返回值**：
```json
{
"sessionId": "string",
"debuggerUrl": "string"
}
```
### end 工具
优雅关闭指定会话。
**参数结构**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `sessionId` | `string` | 是 | 要关闭的会话 ID |
## 并发控制
### 互斥锁模式
为防止多个并发请求同时创建默认会话，SessionManager 实现了 Promise-based 互斥锁：
```typescript
async ensureDefaultSessionInternal(config: Config): Promise {
// 如果创建已在进行中，等待现有 Promise
if (this.defaultSessionCreationPromise) {
return await this.defaultSessionCreationPromise;
}
// 设置互斥锁并开始创建
this.defaultSessionCreationPromise = (async () => {
try {
this.defaultBrowserSession = await this.createNewBrowserSession(...);
} finally {
this.defaultSessionCreationPromise = null; // 解锁
}
})();
return await this.defaultSessionCreationPromise;
}
```
### 清理状态追踪
使用 Set 跟踪正在清理的会话，防止重复关闭：
```typescript
async closeBrowserGracefully(
session: BrowserSession | undefined | null,
sessionIdToLog: string,
): Promise {
// 检查是否已在清理中
if (this.cleaningUpSessions.has(sessionIdToLog)) {
return; // 跳过
}
this.cleaningUpSessions.add(sessionIdToLog);
try {
if (session?.stagehand) {
await session.stagehand.close();
}
} finally {
this.cleaningUpSessions.delete(sessionIdToLog);
}
}
```
## Context 集成
### SessionManager 在 Context 中的角色
Context 类是 MCP 服务器的主控制器，通过 SessionManager 提供会话访问：
```mermaid
graph LR
subgraph Context
SM[getSessionManager]
CS[currentSessionId getter]
GS[getStagehand]
end
SM --> |获取| SessionManager
CS --> |代理| SessionManager.getActiveSessionId
GS --> |委托| SessionManager.getSession
```
**关键方法**：
| 方法 | 签名 | 说明 |
|------|------|------|
| `getSessionManager()` | `SessionManager` | 返回 SessionManager 实例 |
| `currentSessionId` | `string` (getter) | 获取当前活跃会话 ID |
| `getStagehand(sessionId?)` | `Promise` | 获取指定会话的 Stagehand 实例 |
资料来源：[src/context.ts:61-78]()
## 配置要求
### 环境变量
| 变量名 | 必填 | 说明 |
|--------|------|------|
| `BROWSERBASE_API_KEY` | 是 | Browserbase API 密钥 |
| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目 ID |
| `GEMINI_API_KEY` | 否 | Gemini 模型 API 密钥（使用 Gemini 时必需） |
### 命令行参数
| 参数 | 说明 |
|------|------|
| `--modelName` | 指定使用的模型名称（如使用非 Gemini 模型） |
| `--proxies` | 启用代理支持 |
## 错误处理
### 常见错误场景
| 场景 | 错误信息 | 处理方式 |
|------|----------|----------|
| API Key 缺失 | `Browserbase API Key is missing in the configuration.` | 阻止会话创建 |
| Project ID 缺失 | `Browserbase Project ID is missing in the configuration.` | 阻止会话创建 |
| 会话创建失败 | `Failed to create/connect session ${sessionId}: ${errorMessage}` | 抛出异常，由调用方处理 |
| 页面不可用 | `No pages available in Stagehand context` | 标记会话为 stale，触发重建 |
### 重试机制
默认会话创建失败后会自动重试一次：
```typescript
} catch (creationError) {
// 首次失败，记录错误
process.stderr.write(`[SessionManager] Initial attempt failed: ${errorMessage}\n`);
// 重试一次
try {
this.defaultBrowserSession = await this.createNewBrowserSession(...);
} catch (retryError) {
throw new Error(`Failed after initial error and retry: ${finalErrorMessage}`);
}
}
```
## 与其他模块的交互
```mermaid
graph TD
subgraph MCP Server
Server[MCP Server]
Tools[工具处理器]
end
subgraph Core
Context[Context]
SessionManager[SessionManager]
end
subgraph 工具层
navigateTool[navigate]
actTool[act]
observeTool[observe]
extractTool[extract]
end
subgraph 底层
Stagehand[Stagehand SDK]
Browserbase[Browserbase Cloud]
end
Server --> Context
Tools --> Context.run
Context --> SessionManager
SessionManager --> Stagehand
Stagehand --> Browserbase
navigateTool --> Context.getStagehand
actTool --> Context.getStagehand
observeTool --> Context.getStagehand
extractTool --> Context.getStagehand
```
## 最佳实践
1. **使用默认会话**：大多数场景下无需指定会话 ID，系统会自动管理
2. **避免手动关闭会话**：使用 `end` 工具而非直接操作 SessionManager
3. **监控会话状态**：通过 Browserbase Live Debugger URL 监控会话：`https://www.browserbase.com/sessions/${sessionId}`
4. **处理并发请求**：系统内置互斥锁，但建议限制并发调用频率
5. **会话清理**：长时间空闲后再次使用会自动验证并重建会话
---
## 配置参数
### 相关页面
相关主题：[部署指南](#page-deployment), [安装指南](#page-installation)
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)
- [cli.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/cli.js)
- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
# 配置参数
## 概述
配置参数系统是 mcp-server-browserbase 项目中用于控制 MCP 服务器行为的核心模块。该系统通过整合环境变量、命令行参数和默认配置值，为服务器提供灵活的运行时配置能力。配置参数决定了浏览器会话的创建方式、代理设置、模型选择、视图端口尺寸等关键运行参数。
配置系统的设计遵循分层覆盖原则，优先级顺序为：默认值 < 环境变量 < 命令行参数。这种设计允许用户通过多种途径自定义服务器行为，同时保持合理的默认值以简化初次使用体验。
---
## 配置参数类型
### 环境变量
环境变量是配置服务器的基础方式，特别适用于生产环境部署和 Docker 容器化场景。系统支持以下环境变量：
| 环境变量名 | 说明 | 必填 | 示例 |
|-----------|------|------|------|
| `BROWSERBASE_API_KEY` | Browserbase 平台的 API 密钥，用于身份验证 | 是 | `bb_xxxxxxxxxxxx` |
| `BROWSERBASE_PROJECT_ID` | Browserbase 项目标识符 | 是 | `proj_xxxxxxxxxxxx` |
| `GEMINI_API_KEY` | Google Gemini API 密钥，用于 AI 模型调用 | 是 | `AIza...` |
| `GOOGLE_API_KEY` | Google API 密钥的别名 | 否 | `AIza...` |
资料来源：[src/config.ts:30-32](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
系统会优先使用 `GEMINI_API_KEY`，如果未设置则回退到 `GOOGLE_API_KEY`。这一设计提供了配置的灵活性。
### 命令行参数
命令行参数通过 CLI 界面传递，提供细粒度的运行时控制。`CLIOptions` 类型定义了所有支持的命令行标志：
```typescript
export type CLIOptions = {
proxies?: boolean;
verified?: boolean;
advancedStealth?: boolean;
contextId?: string;
persist?: boolean;
port?: number;
host?: string;
browserWidth?: number;
browserHeight?: number;
modelName?: string;
modelApiKey?: string;
keepAlive?: boolean;
experimental?: boolean;
};
```
资料来源：[src/config.ts:8-22](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
---
## 配置数据结构
完整的配置通过 `Config` 类型定义，包含了所有运行时需要的参数：
| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `browserbaseApiKey` | `string` | `process.env.BROWSERBASE_API_KEY` | Browserbase API 密钥 |
| `browserbaseProjectId` | `string` | `process.env.BROWSERBASE_PROJECT_ID` | Browserbase 项目 ID |
| `proxies` | `boolean` | `false` | 是否启用代理 |
| `verified` | `boolean` | `false` | 是否启用经验证模式 |
| `advancedStealth` | `boolean` | `false` | 高级隐身模式（`verified` 的别名） |
| `contextId` | `string` | `undefined` | 浏览器上下文 ID |
| `persist` | `boolean` | `false` | 是否持久化会话 |
| `server.port` | `number \| undefined` | `undefined` | HTTP 服务器端口 |
| `server.host` | `string \| undefined` | `undefined` | HTTP 服务器主机 |
| `viewPort.browserWidth` | `number` | `1024` | 浏览器窗口宽度 |
| `viewPort.browserHeight` | `number` | `768` | 浏览器窗口高度 |
| `modelName` | `string` | `google/gemini-2.5-flash-lite` | AI 模型名称 |
| `modelApiKey` | `string` | `process.env.GEMINI_API_KEY` | 模型 API 密钥 |
| `keepAlive` | `boolean` | `false` | 是否保持连接活跃 |
资料来源：[config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)
---
## 配置解析流程
配置解析采用链式合并策略，将不同来源的配置参数按照优先级合并成最终的有效配置。
```mermaid
graph TD
A[默认配置 defaultConfig] --> B{mergeConfig}
C[CLI 配置 cliConfig] --> B
B --> D[合并配置 mergedConfig]
D --> E{normalizeVerifiedConfig}
E --> F[规范化配置 normalizedConfig]
F --> G{检查 modelApiKey}
G -->|未设置| H[使用 GEMINI_API_KEY]
G -->|已设置| I[保持不变]
H --> J[最终配置 finalConfig]
I --> J
```
`resolveConfig` 函数是配置解析的核心入口，负责协调整个合并过程：
```typescript
export async function resolveConfig(cliOptions: CLIOptions): Promise {
const cliConfig = await configFromCLIOptions(cliOptions);
// 优先级: 默认值 < 文件配置 < CLI 参数
const mergedConfig = normalizeVerifiedConfig(
mergeConfig(defaultConfig, cliConfig),
);
if (!mergedConfig.modelApiKey) {
mergedConfig.modelApiKey =
process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
}
return mergedConfig;
}
```
资料来源：[src/config.ts:35-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
### 配置优先级
配置参数的优先级从低到高排列如下：
1. **默认值** (`defaultConfig`) - 提供最基础的配置值
2. **环境变量** - 通过 `process.env` 读取
3. **CLI 参数** (`cliOptions`) - 命令行传入的参数具有最高优先级
这种设计确保了灵活性的同时，用户可以通过命令行快速覆盖任何配置。
---
## 默认配置值
系统预设了一套合理的默认配置值，用户无需修改即可启动服务器：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `proxies` | `false` | 默认不启用代理 |
| `viewPort.browserWidth` | `1024` | 默认窗口宽度 1024px |
| `viewPort.browserHeight` | `768` | 默认窗口高度 768px |
| `modelName` | `google/gemini-2.5-flash-lite` | 默认使用 Gemini 2.5 Flash Lite |
```typescript
const defaultConfig: Config = {
browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? "",
browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? "",
proxies: false,
server: {
port: undefined,
host: undefined,
},
viewPort: {
browserWidth: 1024,
browserHeight: 768,
},
modelName: "google/gemini-2.5-flash-lite",
};
```
资料来源：[src/config.ts:24-36](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
---
## 命令行标志详解
### 代理与安全
| 标志 | 类型 | 说明 |
|------|------|------|
| `--proxies` | `boolean` | 启用代理支持 |
| `--verified` | `boolean` | 启用经验证的浏览器模式 |
| `--advancedStealth` | `boolean` | 高级隐身模式（`--verified` 的别名） |
资料来源：[src/config.ts:8-10](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
### 会话管理
| 标志 | 类型 | 说明 |
|------|------|------|
| `--contextId` | `string` | 指定浏览器上下文 ID |
| `--persist` | `boolean` | 启用会话持久化 |
| `--keepAlive` | `boolean` | 保持连接活跃 |
### 服务器配置
| 标志 | 类型 | 说明 |
|------|------|------|
| `--port` | `number` | HTTP 服务器监听端口 |
| `--host` | `string` | HTTP 服务器监听主机 |
### 浏览器视图
| 标志 | 类型 | 说明 |
|------|------|------|
| `--browserWidth` | `number` | 浏览器窗口宽度（像素） |
| `--browserHeight` | `number` | 浏览器窗口高度（像素） |
### 模型配置
| 标志 | 类型 | 说明 |
|------|------|------|
| `--modelName` | `string` | AI 模型名称（如需使用不同模型必须指定） |
| `--modelApiKey` | `string` | AI 模型 API 密钥 |
> **注意**：如果需要使用不同的模型，必须通过 `--modelName` 参数指定，并在环境变量或参数中提供对应的 API 密钥。
---
## 配置示例
### 环境变量配置
```bash
export BROWSERBASE_API_KEY="bb_your_api_key_here"
export BROWSERBASE_PROJECT_ID="proj_your_project_id_here"
export GEMINI_API_KEY="your_gemini_key_here"
```
### Docker 部署配置
```json
{
"mcpServers": {
"browserbase": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"BROWSERBASE_API_KEY",
"-e",
"BROWSERBASE_PROJECT_ID",
"-e",
"GEMINI_API_KEY",
"mcp-browserbase"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
### NPM 部署配置
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
### 自定义视图端口配置
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": [
"/path/to/mcp-server-browserbase/cli.js",
"--browserWidth",
"1920",
"--browserHeight",
"1080"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
---
## verified 与 advancedStealth 兼容性
系统维护了向后兼容性，`advancedStealth` 参数作为 `verified` 的别名存在。配置规范化函数会处理这种映射关系：
```typescript
export function normalizeVerifiedConfig(config: Config): Config {
// 如果设置了 advancedStealth 但未设置 verified，则将 verified 设置为 true
if (config.advancedStealth && !config.verified) {
return { ...config, verified: true };
}
return config;
}
```
资料来源：[src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
当同时设置 `verified` 和 `advancedStealth` 时，`verified` 的值优先：
| verified | advancedStealth | 最终 verified 值 |
|----------|-----------------|------------------|
| `true` | `true` | `true` |
| `false` | `true` | `false` |
| `undefined` | `true` | `true` |
---
## 相关命令脚本
项目在 `package.json` 中定义了与配置相关的构建和测试脚本：
| 脚本命令 | 说明 |
|---------|------|
| `pnpm build` | 编译 TypeScript 代码并设置执行权限 |
| `pnpm prepare` | 准备阶段：运行 husky 和构建 |
| `pnpm inspect` | 使用 MCP inspector 检查服务器 |
| `pnpm test` | 运行单元测试 |
```json
{
"scripts": {
"build": "tsc && shx chmod +x dist/*.js",
"prepare": "husky && pnpm build",
"inspector": "npx @modelcontextprotocol/inspector build/index.js",
"test": "vitest run"
}
}
```
资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
---
## 部署指南
### 相关页面
相关主题：[安装指南](#page-installation), [配置参数](#page-configuration), [MCP 客户端集成](#page-mcp-integration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)
- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)
- [cli.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/cli.js)
# 部署指南
本页面详细说明如何部署和配置 Browserbase MCP 服务器。该服务器基于 Model Context Protocol (MCP) 构建，通过 Browserbase 和 Stagehand 实现 AI 网页自动化功能。
## 部署架构概览
Browserbase MCP 服务器支持两种主要的运行时部署模式：
```mermaid
graph TD
A[用户 MCP 客户端] --> B{传输协议选择}
B -->|SHTTP| C[Browserbase 托管服务
https://mcp.browserbase.com/mcp]
B -->|STDIO| D[本地 MCP 服务器]
C --> E[Gemini 模型]
D --> F[Browserbase Cloud]
D --> G[本地浏览器]
F --> H[Stagehand 引擎]
G --> H
```
## 前提条件
| 要求 | 说明 |
|------|------|
| Node.js | 版本 18.x 或更高 |
| Docker | 仅在使用 Docker 部署时需要 |
| Browserbase 账户 | 用于获取 API Key 和 Project ID |
| Gemini API Key | 用于 AI 模型调用 |
## 安装方式
### 方式一：直接安装
通过 Git 克隆源码后自行编译：
```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build
```
编译完成后，CLI 入口文件位于 `cli.js`，可通过以下命令验证：
```bash
node cli.js --version
```
资料来源：[README.md:1-12]()
### 方式二：使用 NPM 包
通过 npx 直接运行官方发布的 NPM 包：
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
资料来源：[README.md:65-77]()
### 方式三：Docker 部署
使用 Docker 构建自定义镜像：
```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .
```
Docker 部署特别适合隔离环境依赖，或在不支持 Node.js 的系统上运行。
资料来源：[README.md:8-11]()
## 环境变量配置
MCP 服务器运行时需要以下环境变量：
| 环境变量 | 必填 | 说明 |
|---------|------|------|
| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |
| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目标识符 |
| `GEMINI_API_KEY` | 条件必填 | Gemini 模型 API 密钥（当 `modelApiKey` 未设置时使用） |
| `GOOGLE_API_KEY` | 条件必填 | 备用 Gemini API 密钥 |
服务器启动时会优先使用 `modelApiKey` 配置参数，其次回退到 `GEMINI_API_KEY`，最后使用 `GOOGLE_API_KEY`。
资料来源：[src/config.ts:30-35]()
## 命令行配置选项
服务器支持丰富的命令行参数配置：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `--browserbaseApiKey` | string | 环境变量 | Browserbase API 密钥 |
| `--browserbaseProjectId` | string | 环境变量 | Browserbase 项目 ID |
| `--proxies` | boolean | false | 启用 Browserbase 代理 |
| `--verified` | boolean | false | 启用 Browserbase 验证身份（仅限 Scale 计划用户） |
| `--advancedStealth` | boolean | false | 已弃用，与 `--verified` 等效 |
| `--contextId` | string | - | Browserbase 上下文 ID |
| `--persist` | boolean | false | 持久化会话 |
| `--port` | number | - | HTTP 传输监听端口 |
| `--host` | string | - | HTTP 传输监听主机 |
| `--browserWidth` | number | 1024 | 浏览器视口宽度 |
| `--browserHeight` | number | 768 | 浏览器视口高度 |
| `--modelName` | string | google/gemini-2.5-flash-lite | 使用的 AI 模型名称 |
| `--modelApiKey` | string | - | 模型 API 密钥 |
| `--keepAlive` | boolean | - | 保持连接活跃 |
| `--experimental` | boolean | false | 启用实验性功能 |
资料来源：[src/config.ts:7-24]()
## 传输协议配置
### STDIO 传输模式
STDIO 是本地进程间通信的标准方式，适合桌面 MCP 客户端（如 Claude Desktop、Cursor）。
#### 直接安装配置
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": ["/path/to/mcp-server-browserbase/cli.js"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
#### Docker 配置
```json
{
"mcpServers": {
"browserbase": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"BROWSERBASE_API_KEY",
"-e",
"BROWSERBASE_PROJECT_ID",
"-e",
"GEMINI_API_KEY",
"mcp-browserbase"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
资料来源：[README.md:18-60]()
### SHTTP 传输模式
SHTTP (Streamable HTTP) 是现代化的传输协议，支持服务端推送和流式响应。
#### 托管服务（推荐）
Browserbase 提供托管 MCP 服务器，无需本地运行：
```json
{
"mcpServers": {
"browserbase": {
"type": "http",
"url": "https://mcp.browserbase.com/mcp"
}
}
}
```
如果客户端不支持原生 SHTTP，可使用 `mcp-remote` 代理：
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
}
}
}
```
资料来源：[README.md:82-102]()
#### 自托管 HTTP 服务
使用 `--port` 和 `--host` 参数启动自托管 HTTP 服务器：
```bash
node cli.js --port 8080 --host 0.0.0.0
```
服务器启动后会输出配置信息：
```
Listening on http://localhost:8080
Put this in your client config:
{
"mcpServers": {
"browserbase": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}
}
If your client supports streamable HTTP, you can use the /mcp endpoint instead.
```
资料来源：[src/transport.ts:1-45]()
## 部署拓扑图
```mermaid
graph LR
subgraph "客户端层"
A[MCP 客户端]
end
subgraph "传输层"
B[STDIO]
C[HTTP/SHTTP]
end
subgraph "服务层"
D[本地部署]
E[托管服务
mcp.browserbase.com]
end
subgraph "后端服务"
F[Browserbase Cloud]
G[Gemini API]
end
A --> B
A --> C
B --> D
C --> D
C --> E
D --> F
D --> G
E --> F
E --> G
```
## 完整配置示例
### 完整 STDIO 配置（本地部署）
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": [
"/usr/local/bin/mcp-server-browserbase/cli.js",
"--modelName",
"google/gemini-2.5-flash-lite",
"--browserWidth",
"1920",
"--browserHeight",
"1080"
],
"env": {
"BROWSERBASE_API_KEY": "your-api-key-here",
"BROWSERBASE_PROJECT_ID": "your-project-id-here",
"GEMINI_API_KEY": "your-gemini-key-here"
}
}
}
}
```
### 使用代理的配置
```bash
node cli.js --proxies --verified
```
### 自定义模型配置
如需使用不同的 AI 模型，添加 `--modelName` 参数并提供相应的 API 密钥：
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": [
"@browserbasehq/mcp",
"--modelName",
"anthropic/claude-3-5-sonnet"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"MODEL_API_KEY": ""
}
}
}
}
```
资料来源：[src/config.ts:22]()
## 部署验证
部署完成后，可通过以下方式验证：
1. **CLI 版本检查**：运行 `node cli.js --version`
2. **MCP Inspector**：使用官方检查器测试工具连接
```bash
npm run inspector
```
3. **功能测试**：使用 MCP 客户端发送测试请求到服务器
资料来源：[package.json:34]()
## 常见部署问题
| 问题 | 解决方案 |
|------|----------|
| 连接超时 | 检查防火墙设置，确保端口可访问 |
| API Key 无效 | 验证 Browserbase 和 Gemini 密钥是否正确 |
| 浏览器启动失败 | 检查系统是否安装 Chromium，Docker 模式下确保沙箱配置正确 |
| 会话不稳定 | 添加 `--keepAlive` 参数保持连接 |
## 版本信息
当前稳定版本为 **3.0.0**，主要变化包括：
- 工具名称与托管服务对齐
- 默认模型更新为 `google/gemini-2.5-flash-lite`
- 移除 Smithery 相关依赖
资料来源：[package.json:3-4]()
---
## MCP 客户端集成
### 相关页面
相关主题：[部署指南](#page-deployment), [工具集概述](#page-tools-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)
- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)
- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)
- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)
- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)
- [src/mcp/resources.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts)
- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
# MCP 客户端集成
## 概述
MCP 客户端集成是指将 Browserbase MCP 服务器与支持 Model Context Protocol 的客户端应用（如 Claude Desktop、Cursor、Cody 等）进行连接的配置过程。该服务器基于 `@modelcontextprotocol/sdk` 构建，提供浏览器自动化能力，允许 AI 助手通过自然语言控制浏览器执行网页导航、元素交互和数据提取等操作。
资料来源：[src/index.ts:1-25]()
## 架构设计
### 服务器层级结构
```mermaid
graph TD
A[MCP 客户端
Claude Desktop / Cursor] --> B[MCP Server
McpServer 实例]
B --> C[Context 上下文
会话管理器]
C --> D[SessionManager
浏览器会话管理]
D --> E[Stagehand 实例
浏览器自动化]
F[Tools 工具集
start/navigate/act/observe/extract] --> B
```
Browserbase MCP 服务器采用分层架构设计：
| 层级 | 组件 | 职责 |
|------|------|------|
| 协议层 | `McpServer` | 处理 MCP 协议通信，注册工具和资源 |
| 业务层 | `Context` | 执行工具逻辑，管理工具生命周期 |
| 会话层 | `SessionManager` | 管理多个浏览器会话，验证会话状态 |
| 自动化层 | `Stagehand` | 基于 Playwright 的浏览器自动化执行 |
资料来源：[src/server.ts:3-27]()[src/context.ts:1-50]()
### 工具注册机制
服务器启动时，所有工具通过统一接口注册到 MCP 协议层：
```typescript
// 伪代码展示工具注册流程
tools.forEach((tool) => {
server.tool(
tool.schema.name, // 工具名称
tool.schema.description, // 工具描述
tool.schema.inputSchema.shape, // 输入参数 schema
async (params) => {
const result = await context.run(tool, params);
return result;
}
);
});
```
资料来源：[src/index.ts:45-70]()
## 支持的传输方式
### 传输方式对比
| 传输方式 | 说明 | 推荐场景 | 配置复杂度 |
|----------|------|----------|------------|
| **STDI O** | 标准输入输出流 | 本地运行、自托管 | 低 |
| **SHTTP** | Server-Sent HTTP | 托管服务、远程访问 | 中 |
| **Docker** | 容器化部署 | 生产环境隔离 | 中 |
资料来源：[README.md:1-80]()
### STDIO 传输配置
STDIO 传输适用于本地部署场景，服务器通过标准输入输出与客户端通信。
**NPM 方式（推荐）**
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
**本地构建方式**
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": ["/path/to/mcp-server-browserbase/cli.js"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
资料来源：[README.md:30-60]()
### SHTTP 传输配置
SHTTP（Server-Sent HTTP）传输允许客户端通过 HTTP 协议连接到托管的 MCP 服务器：
**支持 SHTTP 的客户端**
```json
{
"mcpServers": {
"browserbase": {
"type": "http",
"url": "https://mcp.browserbase.com/mcp"
}
}
}
```
**不支持 SHTTP 的客户端**
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
}
}
}
```
资料来源：[README.md:62-85]()
### Docker 部署配置
```json
{
"mcpServers": {
"browserbase": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"BROWSERBASE_API_KEY",
"-e",
"BROWSERBASE_PROJECT_ID",
"-e",
"GEMINI_API_KEY",
"mcp-browserbase"
],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
资料来源：[README.md:18-28]()
## 配置参数详解
### 环境变量
| 环境变量 | 必需 | 说明 |
|----------|------|------|
| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |
| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目标识符 |
| `GEMINI_API_KEY` | 是 | Google Gemini 模型 API 密钥（用于 AI 驱动的浏览器自动化） |
| `GOOGLE_API_KEY` | 否 | Google API 密钥备选（当 GEMINI_API_KEY 未设置时使用） |
资料来源：[src/config.ts:40-55]()
### 命令行参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `--browserbaseApiKey` | string | Browserbase API 密钥 |
| `--browserbaseProjectId` | string | Browserbase 项目 ID |
| `--proxies` | boolean | 启用 Browserbase 代理 |
| `--verified` | boolean | 使用 Browserbase 验证身份（仅 Scale 计划可用） |
| `--advancedStealth` | boolean | 已废弃，等同于 `--verified` |
| `--contextId` | string | 指定 Browserbase 上下文 ID |
| `--keepAlive` | boolean | 保持浏览器会话活跃 |
| `--modelName` | string | 使用的 AI 模型名称（默认：`google/gemini-2.5-flash-lite`） |
| `--modelApiKey` | string | 模型 API 密钥 |
资料来源：[src/program.ts:28-50]()
### 默认配置
```typescript
const defaultConfig: Config = {
browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? "",
browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? "",
proxies: false,
server: {
port: undefined,
host: undefined,
},
viewPort: {
browserWidth: 1024,
browserHeight: 768,
},
modelName: "google/gemini-2.5-flash-lite",
};
```
资料来源：[src/config.ts:28-40]()
## 资源与模板
### 资源注册
MCP 协议支持资源管理功能，Browserbase MCP 服务器当前提供了空的资源集合：
```typescript
export const RESOURCES = [];
export const RESOURCE_TEMPLATES = [];
export function listResources() {
return { resources: [] };
}
export function listResourceTemplates() {
return { resourceTemplates: [] };
}
export function readResource(uri: string) {
return { contents: [{ uri, text: `Resource not found: ${uri}` }] };
}
```
资料来源：[src/mcp/resources.ts:1-20]()
服务器通过 MCP 协议注册了资源处理器：
```typescript
server.server.setRequestHandler(ListResourcesRequestSchema, async () => {
return listResources();
});
server.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {
return { resourceTemplates: RESOURCE_TEMPLATES };
});
server.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
return readResource(request.params.uri);
});
```
资料来源：[src/index.ts:30-45]()
## 工具能力
### 核心工具集
| 工具名称 | 功能 | 输入参数 |
|----------|------|----------|
| `start` | 创建新的浏览器会话 | _(无)_ |
| `end` | 关闭当前浏览器会话 | _(无)_ |
| `navigate` | 导航到指定 URL | `{ url: string }` |
| `act` | 执行页面操作 | `{ action: string }` |
| `observe` | 观察页面可交互元素 | `{ instruction: string }` |
| `extract` | 从页面提取数据 | `{ instruction?: string }` |
资料来源：[README.md:1-15]()[src/tools/extract.ts:1-55]()
### 工具定义结构
```typescript
export type Tool = {
capability: string; // 能力分类：core
schema: ToolSchema;
handle: (context: Context, params: z.output) => Promise;
};
export type ToolResult = {
action?: () => Promise;
waitForNetwork: boolean;
};
```
资料来源：[src/tools/tool.ts:18-30]()
## 服务器生命周期
### 服务端点
```mermaid
sequenceDiagram
participant Client as MCP 客户端
participant Server as McpServer
participant Context as Context
participant SessionManager as SessionManager
participant Stagehand as Stagehand
Client->>Server: 初始化连接
Server->>Context: 创建上下文
Context->>SessionManager: 初始化会话管理器
Server->>Server: 注册工具处理器
Server->>Server: 注册资源处理器
Client->>Server: 工具调用 (tool/Call)
Server->>Context: 执行工具 (context.run)
Context->>SessionManager: 获取/创建会话
SessionManager->>Stagehand: 操作浏览器
Stagehand-->>SessionManager: 执行结果
SessionManager-->>Context: 工具结果
Context-->>Server: MCP 响应
Server-->>Client: 返回结果
Client->>Server: 关闭连接
Server->>SessionManager: 关闭所有会话
Server->>Server: 清理资源
```
### 服务器管理
```typescript
export class ServerList {
private _servers: Server[] = [];
private _serverFactory: () => Promise;
async create() {
const server = await this._serverFactory();
this._servers.push(server);
return server;
}
async close(server: Server) {
await server.close();
const index = this._servers.indexOf(server);
if (index !== -1) this._servers.splice(index, 1);
}
async closeAll() {
await Promise.all(this._servers.map((server) => server.close()));
}
}
```
资料来源：[src/server.ts:3-27]()
## 错误处理
### 工具执行错误
当工具执行失败时，错误信息通过 MCP 协议返回：
```typescript
try {
const result = await context.run(tool, params);
return result;
} catch (error) {
const errorMessage = error instanceof Error ? error.message : String(error);
process.stderr.write(
`[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\n`,
);
throw new Error(`Failed to run tool '${tool.schema.name}': ${errorMessage}`);
}
```
资料来源：[src/index.ts:62-73]()
### 会话验证错误
会话管理器会自动检测失效会话并触发重建：
```typescript
try {
const pages = this.defaultBrowserSession.stagehand.context.pages();
if (!pages || pages.length === 0) {
throw new Error("No pages available");
}
} catch {
needsReCreation = true;
// 关闭并重建会话
await this.closeBrowserGracefully(this.defaultBrowserSession, sessionId);
this.defaultBrowserSession = null;
}
```
资料来源：[src/sessionManager.ts:80-105]()
## 快速开始
### 1. 安装依赖
```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build
```
### 2. 配置环境变量
创建 `.env` 文件：
```bash
BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id
GEMINI_API_KEY=your_gemini_key
```
### 3. 配置客户端
根据使用的客户端，将以下配置添加到 MCP 配置文件中：
```json
{
"mcpServers": {
"browserbase": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-browserbase/cli.js"],
"env": {
"BROWSERBASE_API_KEY": "your_api_key",
"BROWSERBASE_PROJECT_ID": "your_project_id",
"GEMINI_API_KEY": "your_gemini_key"
}
}
}
}
```
### 4. 重启客户端
重新加载 MCP 客户端以应用配置变更。
## 版本兼容性
### 3.0.0 重大变更
版本 3.0.0 带来了以下破坏性变更，以与托管服务对齐：
| 旧名称 | 新名称 |
|--------|--------|
| `browserbase_session_create` | `start` |
| `browserbase_session_close` | `end` |
| `browserbase_stagehand_navigate` | `navigate` |
| `browserbase_stagehand_act` | `act` |
| `browserbase_stagehand_observe` | `observe` |
| `browserbase_stagehand_extract` | `extract` |
默认模型已从 `gemini-2.0-flash` 更改为 `google/gemini-2.5-flash-lite`。
资料来源：[CHANGELOG.md:1-30]()
## 相关文档
- [Browserbase MCP 官方文档](https://docs.browserbase.com/integrations/mcp/introduction)
- [Model Context Protocol 规范](https://modelcontextprotocol.io/docs/concepts/resources)
- [Stagehand 浏览器自动化](https://www.stagehand.dev)
---
## 模型配置
### 相关页面
相关主题：[配置参数](#page-configuration), [工具集概述](#page-tools-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)
- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)
- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)
- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)
- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)
# 模型配置
## 概述
模型配置是 Browserbase MCP Server 的核心功能之一，用于控制浏览器自动化操作所使用的 AI 模型。该配置通过 [Stagehand](https://www.stagehand.dev) 框架实现网页自动化操作，包括页面导航（navigate）、元素操作（act）、页面观察（observe）和数据提取（extract）。
默认情况下，服务器使用 Google 的 Gemini 2.5 Flash Lite 模型，该模型在 Stagehand 的自动化评估中表现优异。用户也可以配置其他支持的模型（如 GPT-4o、Claude 等）来满足特定需求。
资料来源：[README.md:1-50]()
## 配置架构
MCP Server 的模型配置遵循以下层次结构：
```mermaid
graph TD
A[默认配置] --> B[环境变量]
B --> C[CLI 参数]
C --> D[最终配置]
A1["defaultConfig
modelName: google/gemini-2.5-flash-lite"] --> A
B1["GEMINI_API_KEY
GOOGLE_API_KEY"] --> B
C1["--modelName
--modelApiKey"] --> C
```
配置优先级顺序为：**默认值 < 环境变量 < CLI 参数**
资料来源：[src/config.ts:1-30]()
## 配置参数详解
### 主要配置项
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `modelName` | string | `google/gemini-2.5-flash-lite` | 使用的 AI 模型标识符 |
| `modelApiKey` | string | 环境变量 | 自定义模型的 API 密钥 |
| `experimental` | boolean | `false` | 是否启用实验性功能 |
资料来源：[src/index.ts:1-50]()
### CLI 选项定义
```typescript
modelName: z
.string()
.optional()
.describe(
"The model to use for Stagehand (default: google/gemini-2.5-flash-lite)",
),
modelApiKey: z
.string()
.optional()
.describe(
"API key for the custom model provider. Required when using a model other than the default google/gemini-2.5-flash-lite",
),
```
资料来源：[src/index.ts:50-65]()
## 配置验证机制
服务器实现了严格的配置验证逻辑，确保在使用非默认模型时必须提供相应的 API 密钥。
```mermaid
graph TD
A[配置输入] --> B{modelName 是否为默认值?}
B -->|是| C[无需 API Key]
B -->|否| D{modelApiKey 是否存在且有效?}
D -->|是| E[验证通过]
D -->|否| F[抛出验证错误]
F --> F1["modelApiKey is required
when specifying a custom model"]
```
### 验证规则
服务器使用 Zod schema 进行配置验证，核心验证逻辑如下：
```typescript
.refine(
(data) => {
// 如果指定了非默认模型，API 密钥是必需的
if (data.modelName && data.modelName !== "google/gemini-2.5-flash-lite") {
return (
data.modelApiKey !== undefined &&
typeof data.modelApiKey === "string" &&
data.modelApiKey.length > 0
);
}
return true;
},
{
message: "modelApiKey is required when specifying a custom model",
path: ["modelApiKey"],
},
);
```
资料来源：[src/index.ts:65-85]()
## 环境变量配置
### 优先级顺序
系统按以下顺序查找 API 密钥：
| 优先级 | 环境变量名 | 说明 |
|--------|------------|------|
| 1 | `modelApiKey` (CLI) | 通过命令行直接指定 |
| 2 | `GEMINI_API_KEY` | Gemini 专用环境变量 |
| 3 | `GOOGLE_API_KEY` | Google 通用 API 密钥 |
```typescript
// --- Add Browserbase Env Vars ---
if (!mergedConfig.modelApiKey) {
mergedConfig.modelApiKey =
process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
}
```
资料来源：[src/config.ts:45-50]()
## 配置示例
### 使用默认模型
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "your-api-key",
"BROWSERBASE_PROJECT_ID": "your-project-id",
"GEMINI_API_KEY": "your-gemini-key"
}
}
}
}
```
### 使用自定义模型（Claude）
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": [
"@browserbasehq/mcp",
"--modelName",
"anthropic/claude-sonnet-4-5",
"--modelApiKey",
"your-anthropic-api-key"
],
"env": {
"BROWSERBASE_API_KEY": "your-api-key",
"BROWSERBASE_PROJECT_ID": "your-project-id"
}
}
}
}
```
资料来源：[README.md:80-100]()
## 支持的模型
根据 Stagehand 的支持列表，用户可以使用以下类型的模型：
| 模型类别 | 示例模型 | 提供商 |
|----------|----------|--------|
| Gemini 系列 | `google/gemini-2.5-flash-lite` | Google |
| Claude 系列 | `anthropic/claude-sonnet-4-5` | Anthropic |
| GPT 系列 | `openai/gpt-4o` | OpenAI |
> **注意**：自定义模型必须在 Stagehand 支持的模型列表中，具体支持情况请参阅 [Stagehand 文档](https://docs.stagehand.dev/examples/custom_llms#supported-llms)。
资料来源：[README.md:95-100]()
## 完整配置流程
```mermaid
sequenceDiagram
participant U as 用户
participant M as MCP Server
participant C as Config 模块
participant S as SessionManager
participant SB as Stagehand
U->>M: 启动服务器 (带模型配置)
M->>C: resolveConfig(cliOptions)
C->>C: 合并默认配置
C->>C: 加载环境变量
C->>C: 应用 CLI 参数
C-->>M: 返回最终 Config
M->>S: 创建会话 (config)
S->>SB: 初始化 Stagehand
SB->>SB: 使用配置的 modelName
alt 非默认模型
C->>C: 验证 modelApiKey 存在
C-->>M: 验证通过或抛出错误
end
```
## 配置代码参考
### 默认配置对象
```typescript
const defaultConfig: Config = {
browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? "",
browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? "",
proxies: false,
server: {
port: undefined,
host: undefined,
},
viewPort: {
browserWidth: 1024,
browserHeight: 768,
},
modelName: "google/gemini-2.5-flash-lite", // 默认模型
};
```
资料来源：[src/config.ts:20-35]()
### CLI 选项类型定义
```typescript
export type CLIOptions = {
proxies?: boolean;
verified?: boolean;
advancedStealth?: boolean;
contextId?: string;
persist?: boolean;
port?: number;
host?: string;
browserWidth?: number;
browserHeight?: number;
modelName?: string; // 模型名称
modelApiKey?: string; // 模型 API 密钥
keepAlive?: boolean;
experimental?: boolean;
};
```
资料来源：[src/config.ts:1-25]()
## 依赖关系
模型配置功能的实现依赖于以下核心包：
| 包名 | 版本 | 用途 |
|------|------|------|
| `@browserbasehq/stagehand` | ^3.3.0 | 浏览器自动化核心框架 |
| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP 协议实现 |
| `zod` | ^3.25.67 | 配置验证 |
| `commander` | ^14.0.0 | CLI 参数解析 |
资料来源：[package.json:1-30]()
## 常见问题
### 1. 模型配置验证失败
**问题**：使用自定义模型时收到 "modelApiKey is required" 错误。
**解决方案**：确保在使用非默认模型时，通过 `--modelApiKey` 参数或 `GEMINI_API_KEY` 环境变量提供了有效的 API 密钥。
### 2. 模型不支持
**问题**：配置的模型在 Stagehand 中不被支持。
**解决方案**：请查阅 [Stagehand 支持的模型列表](https://docs.stagehand.dev/examples/custom_llms#supported-llms)，选择支持的模型。
### 3. API 密钥优先级
**问题**：不确定哪个环境变量会被使用。
**优先级**：`--modelApiKey` > `GEMINI_API_KEY` > `GOOGLE_API_KEY`
## 版本变更记录
| 版本 | 变更内容 |
|------|----------|
| 3.0.0 | 默认模型从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`，工具名称与托管服务对齐 |
| 2.4.0 | 新增 stagehand agent 工具支持 |
| 2.3.0 | 初始阶段hand集成 |
资料来源：[CHANGELOG.md:1-30]()
---
---
## Doramagic 踩坑日志
项目：browserbase/mcp-server-browserbase
摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives。
## 1. 安全/权限坑 · 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。
## 2. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令: `npx @browserbasehq/mcp`
- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp
## 3. 安装坑 · 来源证据：Your MCP server is now indexed on Joy Trust Network
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.
## 5. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing
## 6. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium
## 7. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium
## 8. 安全/权限坑 · 来源证据：Add MCPpedia security badge to README
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 安全/权限坑 · 来源证据：Add policy enforcement for cloud browser sessions
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作: issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown
## 11. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown