1 项目概述

@browserbasehq/mcp 是一个基于 Model Context Protocol (MCP) 的服务器实现，专门用于通过 Browserbase 和 Stagehand 实现 AI 驱动的 Web 浏览器自动化操作。该项目为 AI 助手提供了与浏览器交互的能力，支持导航网页、执行操作、观察页面元素以及提取数据等核心功能。

项目基本信息如下：

资料来源：package.json:1-15

2 核心功能

该项目作为 MCP 协议的服务器实现，提供了一套完整的浏览器自动化工具集。根据 README.md 的说明，服务器暴露以下核心工具：

资料来源：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 架构概览

项目采用模块化架构设计，主要包含以下核心模块：

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() 方法注册各个工具，每个工具都关联到对应的处理函数。

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<typeof tool.schema.inputSchema>) => {
        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) 负责管理浏览器会话的生命周期，包括：

• 创建新的浏览器会话
• 验证会话状态
• 清理过期会话
• 批量关闭所有会话
• 默认会话的自动维护

会话管理器包含以下关键功能：

资料来源：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 主要生产依赖

资料来源：package.json:27-35

4.2 关键外部服务

• Browserbase - 提供云端浏览器基础设施
• Stagehand - AI 驱动的浏览器自动化框架
• Gemini - 默认使用的 AI 模型（由 GEMINI_API_KEY 或 GOOGLE_API_KEY 配置）

5 部署方式

项目支持两种部署方式：

5.1 直接安装

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build

5.2 Docker 部署

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .

6 配置说明

6.1 环境变量

6.2 命令行参数

资料来源：src/config.ts:10-28

6.3 MCP 客户端配置示例

#### STDIO 模式（自托管）

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

#### NPM 模式

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

#### SHTTP 模式（托管服务）

{
  "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 传输协议：

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 文档
• MCP 协议文档
• MCP 协议规范
• Stagehand 文档

系统要求

运行环境

环境变量配置

在开始安装前，需要准备以下环境变量：

[!TIP]

如需使用其他模型，可通过 --modelName 参数指定，并提供对应的 API 密钥。

资料来源：README.md:1-50

安装方式

mcp-server-browserbase 支持三种安装方式，适用于不同的使用场景：

资料来源：README.md:40-80

方式一：NPM 安装（推荐）

NPM 安装是最简洁的方式，适合大多数用户快速上手。

{
  "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 包管理器

#### 安装命令

# 克隆仓库
git clone https://github.com/browserbase/mcp-server-browserbase.git

# 进入项目目录
cd mcp-server-browserbase

# 安装依赖并构建
npm install && npm run build

#### MCP 配置

{
  "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

方式三：Docker 安装

Docker 安装提供完整的隔离环境，适合生产部署。

#### 构建镜像

# 克隆仓库
git clone https://github.com/browserbase/mcp-server-browserbase.git

# 进入项目目录
cd mcp-server-browserbase

# 构建 Docker 镜像
docker build -t mcp-browserbase .

#### MCP 配置

{
  "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

传输方式配置

MCP 服务器支持两种传输协议，根据 MCP 客户端能力选择合适的传输方式：

资料来源：src/transport.ts:1-50

SHTTP（托管服务）

使用 Browserbase 托管的 MCP 服务器地址 https://mcp.browserbase.com/mcp，这是最简便的启动方式。

#### 支持 SHTTP 的客户端配置

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

#### 不支持 SHTTP 的客户端配置

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}

资料来源：README.md:60-90

STDIO（自托管）

STDIO 方式允许完全本地运行服务器。

#### NPM 方式运行

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

#### 本地完全自托管

{
  "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

命令行参数配置

服务器支持丰富的命令行参数，用于自定义部署行为：

资料来源：src/config.ts:1-40

配置合并优先级

系统配置采用分层合并策略，优先级从低到高如下：

1. 默认配置 - 代码中的硬编码默认值
2. 文件配置 - 配置文件中的设置
3. CLI 参数 - 命令行传入的参数（最高优先级）

graph TD
    A[默认配置] --> B[合并文件配置]
    B --> C[合并CLI参数]
    C --> D[最终配置]

资料来源：src/config.ts:45-60

项目结构与构建

项目依赖

主要生产依赖包括：

资料来源：package.json:30-45

构建命令

#### 构建流程

# 开发构建
npm install && npm run build

# 监听模式（开发时使用）
npm run watch

# 运行测试
npm test

资料来源：package.json:20-35

完整配置示例

开发环境配置

{
  "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）

{
  "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 模型：

{
  "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 文档。

资料来源：README.md:130-160

验证安装

安装完成后，可以通过 MCP 检查器验证服务器是否正常工作：

# 使用 npm 脚本启动检查器
npm run inspector

检查器将启动可视化界面，可以测试 MCP 服务器的各项功能和工具。

资料来源：package.json:24

故障排除

常见问题

环境变量验证

在启动服务器前，可以创建 .env 文件管理环境变量：

# 创建 .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

相关资源

• Browserbase MCP 官方文档
• MCP 协议文档
• MCP 协议规范
• Stagehand 文档
• GitHub 仓库

概述

mcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 模型提供网页自动化能力。该服务器通过集成 Browserbase 基础设施和 Stagehand 浏览器自动化框架，使 LLM 能够通过标准化接口执行网页操作。

资料来源：package.json

核心架构组件

组件层次结构

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

组件职责表

资料来源：src/index.ts:1-100

传输层架构

支持的传输方式

该服务器支持两种传输协议，通过命令行参数指定：

HTTP 传输实现

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 请求：

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

会话管理架构

SessionManager 设计

SessionManager 是核心的会话管理组件，负责浏览器实例的生命周期管理。

graph TB
    subgraph "SessionManager"
        browsers[Map<sessionId, BrowserSession>]
        activeSessionId[当前活动会话ID]
        defaultSessionId[默认会话ID: __default__]
        cleaningUpSessions[正在清理的会话集合]
        defaultSessionCreationPromise[创建互斥锁]
    end
    
    subgraph "BrowserSession"
        stagehand[Stagehand 实例]
        config[会话配置]
    end

会话状态管理

关键方法

会话验证通过执行简单操作检测可用性：

const pages = this.defaultBrowserSession.stagehand.context.pages();
if (!pages || pages.length === 0) {
  throw new Error("No pages available");
}

资料来源：src/sessionManager.ts

工具系统架构

工具注册流程

graph TD
    A[TOOLS 数组] --> B[遍历工具]
    B --> C{schema 类型检查}
    C -->|ZodObject| D[server.tool 注册]
    C -->|非 ZodObject| E[警告日志输出]
    D --> F[MCP 服务器就绪]

内置工具列表

工具执行流程

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: 返回响应

工具接口定义

每个工具实现统一的接口结构：

interface Tool<T extends z.ZodObject<any>> {
  capability: "core" | "extended";
  schema: ToolSchema<T>;
  handle: (context: Context, params: z.infer<T>) => Promise<ToolResult>;
}

资料来源：src/tools/extract.ts

Context 上下文管理

上下文职责

Context 是连接 MCP 协议层和业务逻辑层的桥梁，负责：

1. 提供 Stagehand 实例访问
2. 管理活动会话
3. 工具执行和错误处理

graph TB
    subgraph "Context"
        sessionManager[SessionManager]
        activeSessionId[活动会话ID]
    end
    
    Context-->|获取| sessionManager
    Context-->|提供| stagehand

工具执行方法

async run(tool: Tool<any>, params: any): Promise<ToolResult> {
  // 调用工具的 handle 方法
  const result = await tool.handle(this, params);
  return result;
}

资料来源：src/context.ts

ServerList 服务器管理

设计模式

ServerList 采用工厂模式管理多个服务器实例：

classDiagram
    class ServerList {
        -_servers: Server[]
        -_serverFactory: () => Promise~Server~
        +create(): Promise~Server~
        +close(server: Server): Promise~void~
        +closeAll(): Promise~void~
    }

核心方法

资料来源：src/server.ts

数据流架构

请求处理流程

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[返回给客户端]

会话创建流程

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[标记为活动会话]

配置体系

环境变量配置

命令行参数

MCP 配置示例

STDIO 模式：

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

HTTP 模式：

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

依赖关系

核心依赖

开发依赖

资料来源：package.json

部署模式

自托管部署

graph LR
    A[本地机器] -->|npm run build| B[构建产物]
    B --> C[cli.js]
    C --> D[MCP 客户端]
    D --> E[Browserbase 云服务]

Docker 部署

graph TB
    A[Dockerfile] --> B[docker build]
    B --> C[mcp-browserbase 镜像]
    C --> D[docker run]
    D --> E[MCP 客户端连接]

构建命令：

docker build -t mcp-browserbase .

运行配置：

{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-e", "BROWSERBASE_API_KEY", "-e", "BROWSERBASE_PROJECT_ID", "-e", "GEMINI_API_KEY", "mcp-browserbase"]
}

安全考虑

会话隔离

• 每个会话独立的 BrowserSession 实例
• 会话清理使用互斥锁防止竞态条件
• 过期会话自动检测和清理

错误处理

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 生态系统的深度集成。

概述

mcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于通过 Browserbase 和 Stagehand 实现 AI 网页自动化。该项目采用 TypeScript 开发，使用 @modelcontextprotocol/sdk 作为 MCP 协议的实现基础。

项目技术栈：

资料来源：package.json:1-30

架构概览

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 选项类型定义：

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 默认配置值

资料来源：src/config.ts:28-40

1.3 配置合并策略

配置采用分层合并策略，优先级顺序为：默认值 < 文件配置 < CLI 参数

export async function resolveConfig(cliOptions: CLIOptions): Promise<Config> {
  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 核心数据结构

class SessionManager {
  private browsers: Map<string, BrowserSession> = new Map();
  private defaultSessionId: string = "(default)";
  private defaultBrowserSession: BrowserSession | null = null;
  private defaultSessionCreationPromise: Promise<BrowserSession | null> | null = null;
  private activeSessionId: string = "(default)";
  private cleaningUpSessions: Set<string> = new Set();
}

type BrowserSession = {
  stagehand: Stagehand;
  config: Config;
};

资料来源：src/sessionManager.ts:1-50

2.3 会话生命周期

stateDiagram-v2
    [*] --> 创建中: createSession()
    创建中 --> 活跃: 创建成功
    创建中 --> [*]: 创建失败
    活跃 --> 清理中: cleanupSession()
    活跃 --> 失效: 检测到过期
    失效 --> [*]: 自动清理
    清理中 --> [*]: 清理完成

2.4 主要方法

资料来源：src/sessionManager.ts:60-120

2.5 会话验证机制

SessionManager 实现了一套完整的会话有效性验证机制：

1. 简单验证：检查 pages 是否存在且数量大于 0
2. 错误捕获：任何操作异常都会触发会话重建
3. 自动重试：首次创建失败后自动重试一次

// 会话有效性检查示例
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 缓存机制：

private defaultSessionCreationPromise: Promise<BrowserSession | null> | null = null;

当一个会话正在创建时，后续请求会等待同一 Promise，而不是触发新的创建操作。

资料来源：src/sessionManager.ts:100-110

3. 上下文管理 (Context)

3.1 概述

Context 是工具执行时的运行时上下文，负责协调 SessionManager 和工具之间的交互。

资料来源：src/context.ts:1-10

3.2 核心职责

graph LR
    A[工具请求] --> B[Context.run]
    B --> C[SessionManager]
    C --> D[获取 Stagehand]
    D --> E[执行工具]
    E --> F[返回结果]

3.3 工具执行流程

async run(tool: Tool, params: unknown): Promise<ToolResult> {
  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 资源的列表和读取操作：

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 工具类型定义

export type Tool<Input extends InputType = InputType> = {
  capability: string;       // 工具能力分类
  schema: ToolSchema<Input>; // 工具元数据
  handle: (context: Context, params: z.output<Input>) => Promise<ToolResult>;
};

export type ToolResult = {
  action?: () => Promise<ToolActionResult>;
  waitForNetwork: boolean;
};

资料来源：src/tools/tool.ts:20-35

4.3 工具定义示例：extract

以下以 extract 工具为例说明工具的实现方式：

资料来源：src/tools/extract.ts:1-50

const ExtractInputSchema = z.object({
  instruction: z.string().optional(),
});

const extractSchema: ToolSchema<typeof ExtractInputSchema> = {
  name: "extract",
  description: "Extract data from the page",
  inputSchema: ExtractInputSchema,
};

async function handleExtract(
  context: Context,
  params: ExtractInput,
): Promise<ToolResult> {
  const action = async (): Promise<ToolActionResult> => {
    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 核心工具列表

资料来源：README.md:1-50

4.5 工具注册流程

工具通过 tools.ts 统一注册到 MCP 服务器：

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 支持两种传输方式：

资料来源：README.md:60-80

5.2 HTTP 传输实现

graph LR
    A[MCP 客户端] -->|HTTP 请求| B[HTTP Server]
    B --> C[handleStreamable]
    C --> D[ServerList]
    D --> E[Server 实例]

5.3 服务器地址解析

传输层支持动态端口和地址解析：

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 类结构

export class ServerList {
  private _servers: Server[] = [];
  private _serverFactory: () => Promise<Server>;

  async create(): Promise<Server> { /* ... */ }
  async close(server: Server): Promise<void> { /* ... */ }
  async closeAll(): Promise<void> { /* ... */ }
}

资料来源：src/server.ts:5-25

7. 资源系统 (Resources)

7.1 概述

MCP 资源系统提供了只读数据的访问接口。当前实现为空结构，保留扩展能力。

资料来源：src/mcp/resources.ts:1-20

7.2 资源定义

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. 组件交互关系

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 工具执行错误

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 在清理会话时使用幂等设计，确保重复清理不会导致问题：

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 管理服务器实例

这套架构确保了系统的可维护性、可扩展性和可靠性。

简介

mcp-server-browserbase 的工具集（Tools）是该 MCP 服务器的核心功能模块，为大语言模型（LLM）提供浏览器自动化操作能力。通过这些工具，AI 模型可以控制浏览器执行网页导航、元素交互、页面观察和数据提取等任务。

工具集基于 Stagehand 框架构建，封装了 Playwright 的底层能力，提供声明式的网页操作接口。每个工具都遵循统一的类型定义和注册机制，确保与 MCP 协议的无缝集成。

核心功能定位：

• 为 AI Agent 提供浏览器控制能力
• 支持会话级别的浏览器状态管理
• 通过自然语言指令驱动网页自动化操作

架构设计

工具类型系统

工具系统采用泛型设计，通过 TypeScript 的类型约束确保类型安全。核心类型定义位于 src/tools/tool.ts 文件中。

export type ToolSchema<Input extends InputType> = {
  name: string;
  description: string;
  inputSchema: Input;
};

每个工具包含三个核心属性：

工具执行结果类型：

export type ToolResult = {
  action?: () => Promise<ToolActionResult>;
  waitForNetwork: boolean;
};

资料来源：src/tools/tool.ts:1-30

工具执行流程

工具的执行通过 Context 类的 run 方法统一调度。当 MCP 客户端调用工具时，系统按以下流程处理：

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

核心工具列表

工具注册机制

所有工具通过 src/tools/index.ts 统一导出和管理。服务器启动时，工具被批量注册到 MCP 服务器实例：

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

工具清单

资料来源：README.md

工具详解

navigate 工具

navigate 工具负责将浏览器导航至指定的 URL 地址。

工具模式定义：

const NavigateInputSchema = z.object({
  url: z.string().min(1),
});

const navigateSchema: ToolSchema<typeof NavigateInputSchema> = {
  name: "navigate",
  description: "Navigate to a URL",
  inputSchema: NavigateInputSchema,
};

输入参数：

执行逻辑：

1. 通过 context.getStagehand() 获取当前 Stagehand 实例
2. 获取浏览器上下文的页面列表
3. 调用 page.goto() 导航至目标 URL
4. 等待 DOM 内容加载完成（domcontentloaded）
5. 返回导航结果 JSON

返回值示例：

{
  "success": true,
  "data": {
    "url": "https://example.com"
  }
}

错误处理：

• 当没有可用页面时抛出 "No active page available"
• 导航失败时抛出具体错误信息

资料来源：src/tools/navigate.ts

act 工具

act 工具用于执行页面上的用户操作，如点击、输入文本等。

工具模式定义：

const ActInputSchema = z.object({
  action: z.string().min(1),
});

输入参数：

执行逻辑：

act 工具将自然语言动作描述传递给 Stagehand 的 act 方法，由 AI 模型解析并执行相应的网页操作。

资料来源：src/tools/act.ts

observe 工具

observe 工具用于观察和识别页面上可交互的元素。

工具模式定义：

const ObserveInputSchema = z.object({
  instruction: z.string().min(1),
});

输入参数：

执行逻辑：

observe 工具调用 Stagehand 的 observe 方法，识别页面中符合指令描述的可交互元素，并返回识别结果。

资料来源：src/tools/observe.ts

extract 工具

extract 工具用于从当前页面提取结构化数据。

工具模式定义：

const ExtractInputSchema = z.object({
  instruction: z.string().optional(),
});

const extractSchema: ToolSchema<typeof ExtractInputSchema> = {
  name: "extract",
  description: "Extract data from the page",
  inputSchema: ExtractInputSchema,
};

输入参数：

执行逻辑：

1. 获取当前 Stagehand 实例
2. 根据是否提供指令参数调用对应的提取方法：

• 有指令时：stagehand.extract(params.instruction)
• 无指令时：stagehand.extract({})

1. 返回提取结果的 JSON 表示

返回值示例：

{
  "success": true,
  "data": {
    "extracted_content": "..."
  }
}

设计特点：

• instruction 参数为可选项，设计上兼容无参数的默认提取行为
• 返回值统一封装在 { success, data } 结构中

资料来源：src/tools/extract.ts

会话管理

BrowserSession 结构

工具的执行依赖于 BrowserSession 对象，该对象封装了 Stagehand 实例和相关的会话状态：

interface BrowserSession {
  id: string;
  stagehand: Stagehand;
  config: Config;
  // ... 其他会话状态
}

资料来源：src/sessionManager.ts

会话生命周期

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

工具扩展

定义新工具

项目提供了 defineTool 辅助函数用于标准化工具定义：

export function defineTool<Input extends InputType>(
  tool: Tool<Input>,
): Tool<Input> {
  return tool;
}

创建新工具的步骤：

1. 定义 Zod 输入模式
2. 创建工具模式对象（schema）
3. 实现 handle 处理函数
4. 组装并导出工具对象
5. 在 index.ts 中注册工具

工具能力分类

工具通过 capability 属性进行分类：

资料来源：src/tools/tool.ts

版本变更记录

v3.0.0 重大变更

根据 CHANGELOG.md，3.0.0 版本对工具集进行了重大调整：

其他变更：

• act 工具不再接受 variables 参数
• start 工具不再接受 sessionId 参数
• extract 工具的 instruction 参数改为可选
• 默认模型从 gemini-2.0-flash 改为 google/gemini-2.5-flash-lite

资料来源：CHANGELOG.md

总结

mcp-server-browserbase 的工具集提供了完整的浏览器自动化能力封装。通过统一的类型系统、清晰的工具定义模式和模块化的架构设计，开发者可以便捷地扩展新的工具功能，同时保持与 MCP 协议的良好兼容性。工具集的核心价值在于将复杂的网页操作抽象为简单的自然语言指令，使 AI Agent 能够以声明式的方式控制浏览器完成各类自动化任务。

概述

会话管理是 MCP Server Browserbase 的核心子系统，负责创建、管理和销毁浏览器会话实例。该系统基于 Stagehand 构建，通过 Browserbase 云基础设施提供稳定的浏览器自动化能力。

会话管理器在整个 MCP 服务器中扮演中间层角色，连接上层的 MCP 协议处理与下层的 Stagehand 浏览器实例：

• 上层：接收 MCP 客户端的工具调用请求
• 中层：通过 SessionManager 管理会话生命周期和状态同步
• 下层：调用 Stagehand SDK 执行实际的浏览器操作 资料来源：src/context.ts:49-56

核心组件

BrowserSession 数据结构

interface BrowserSession {
  page: Page;                    // Playwright Page 实例
  sessionId: string;             // Browserbase 会话 ID
  stagehand: Stagehand;          // Stagehand 实例
}

资料来源：src/sessionManager.ts:89-93

SessionManager 类

SessionManager 是会话管理的中央控制器，负责维护会话状态机和管理会话集合。

graph TD
    subgraph SessionManager 内部状态
        BM[browsers: Map<string, BrowserSession>]
        DS[defaultSessionId: string]
        AS[activeSessionId: string]
        DBS[defaultBrowserSession: BrowserSession | null]
        CP[defaultSessionCreationPromise: Promise | null]
        CS[cleaningUpSessions: Set<string>]
    end
    
    subgraph 公共接口
        GI[getOrCreateSession]
        GC[getSession]
        CL[cleanupSession]
        CA[closeAllSessions]
        GA[getActiveSessionId]
    end

#### 关键属性

资料来源：src/sessionManager.ts:75-88

会话生命周期

状态转换图

stateDiagram-v2
    [*] --> 不存在: 初始化
    不存在 --> 活跃: createNewBrowserSession
    活跃 --> 正在清理: cleanupSession / closeAllSessions
    正在清理 --> 不存在: close 完成
    活跃 --> 正在清理: 验证失败 (stale)
    正在清理 --> 活跃: 自动重建 (仅限默认会话)

创建会话流程

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: 返回会话信息

#### 创建会话的核心逻辑

async createNewBrowserSession(
  newSessionId: string,
  config: Config,
  resumeSessionId?: string,
): Promise<BrowserSession>

前置条件校验：

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 实现了自动健康检查机制，确保会话可用性：

graph TD
    A[获取会话] --> B{会话存在?}
    B -->|否| C[创建新会话]
    B -->|是| D{会话有效?}
    D -->|是| E[返回会话]
    D -->|否| F[关闭失效会话]
    F --> G{是默认会话?}
    G -->|是| H[自动重建]
    G -->|否| I[返回 null]
    H --> C

有效性检测：

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

工具接口

会话管理工具列表

资料来源：src/tools/index.ts:14-15

start 工具

启动一个新的 Browserbase 会话。

参数结构：

返回值：

{
  "sessionId": "string",
  "debuggerUrl": "string"
}

end 工具

优雅关闭指定会话。

参数结构：

并发控制

互斥锁模式

为防止多个并发请求同时创建默认会话，SessionManager 实现了 Promise-based 互斥锁：

async ensureDefaultSessionInternal(config: Config): Promise<BrowserSession> {
  // 如果创建已在进行中，等待现有 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 跟踪正在清理的会话，防止重复关闭：

async closeBrowserGracefully(
  session: BrowserSession | undefined | null,
  sessionIdToLog: string,
): Promise<void> {
  // 检查是否已在清理中
  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 提供会话访问：

graph LR
    subgraph Context
        SM[getSessionManager]
        CS[currentSessionId getter]
        GS[getStagehand]
    end
    
    SM --> |获取| SessionManager
    CS --> |代理| SessionManager.getActiveSessionId
    GS --> |委托| SessionManager.getSession

关键方法：

资料来源：src/context.ts:61-78

配置要求

环境变量

命令行参数

错误处理

常见错误场景

重试机制

默认会话创建失败后会自动重试一次：

} 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}`);
  }
}

与其他模块的交互

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. 会话清理：长时间空闲后再次使用会自动验证并重建会话

概述

配置参数系统是 mcp-server-browserbase 项目中用于控制 MCP 服务器行为的核心模块。该系统通过整合环境变量、命令行参数和默认配置值，为服务器提供灵活的运行时配置能力。配置参数决定了浏览器会话的创建方式、代理设置、模型选择、视图端口尺寸等关键运行参数。

配置系统的设计遵循分层覆盖原则，优先级顺序为：默认值 < 环境变量 < 命令行参数。这种设计允许用户通过多种途径自定义服务器行为，同时保持合理的默认值以简化初次使用体验。

部署架构概览

Browserbase MCP 服务器支持两种主要的运行时部署模式：

graph TD
    A[用户 MCP 客户端] --> B{传输协议选择}
    B -->|SHTTP| C[Browserbase 托管服务<br/>https://mcp.browserbase.com/mcp]
    B -->|STDIO| D[本地 MCP 服务器]
    C --> E[Gemini 模型]
    D --> F[Browserbase Cloud]
    D --> G[本地浏览器]
    F --> H[Stagehand 引擎]
    G --> H

前提条件

安装方式

方式一：直接安装

通过 Git 克隆源码后自行编译：

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build

编译完成后，CLI 入口文件位于 cli.js，可通过以下命令验证：

node cli.js --version

资料来源：README.md:1-12

方式二：使用 NPM 包

通过 npx 直接运行官方发布的 NPM 包：

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

资料来源：README.md:65-77

方式三：Docker 部署

使用 Docker 构建自定义镜像：

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 服务器运行时需要以下环境变量：

服务器启动时会优先使用 modelApiKey 配置参数，其次回退到 GEMINI_API_KEY，最后使用 GOOGLE_API_KEY。

资料来源：src/config.ts:30-35

命令行配置选项

服务器支持丰富的命令行参数配置：

资料来源：src/config.ts:7-24

传输协议配置

STDIO 传输模式

STDIO 是本地进程间通信的标准方式，适合桌面 MCP 客户端（如 Claude Desktop、Cursor）。

#### 直接安装配置

{
  "mcpServers": {
    "browserbase": {
      "command": "node",
      "args": ["/path/to/mcp-server-browserbase/cli.js"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

#### Docker 配置

{
  "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 服务器，无需本地运行：

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

如果客户端不支持原生 SHTTP，可使用 mcp-remote 代理：

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}

资料来源：README.md:82-102

#### 自托管 HTTP 服务

使用 --port 和 --host 参数启动自托管 HTTP 服务器：

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

部署拓扑图

graph LR
    subgraph "客户端层"
        A[MCP 客户端]
    end
    
    subgraph "传输层"
        B[STDIO]
        C[HTTP/SHTTP]
    end
    
    subgraph "服务层"
        D[本地部署]
        E[托管服务<br/>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 配置（本地部署）

{
  "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"
      }
    }
  }
}

使用代理的配置

node cli.js --proxies --verified

自定义模型配置

如需使用不同的 AI 模型，添加 --modelName 参数并提供相应的 API 密钥：

{
  "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

部署验证

部署完成后，可通过以下方式验证：

``bash npm run inspector ``

1. CLI 版本检查：运行 node cli.js --version
2. MCP Inspector：使用官方检查器测试工具连接
3. 功能测试：使用 MCP 客户端发送测试请求到服务器

资料来源：package.json:34

常见部署问题

版本信息

当前稳定版本为 3.0.0，主要变化包括：

• 工具名称与托管服务对齐
• 默认模型更新为 google/gemini-2.5-flash-lite
• 移除 Smithery 相关依赖

资料来源：package.json:3-4

概述

MCP 客户端集成是指将 Browserbase MCP 服务器与支持 Model Context Protocol 的客户端应用（如 Claude Desktop、Cursor、Cody 等）进行连接的配置过程。该服务器基于 @modelcontextprotocol/sdk 构建，提供浏览器自动化能力，允许 AI 助手通过自然语言控制浏览器执行网页导航、元素交互和数据提取等操作。

资料来源：src/index.ts:1-25

架构设计

服务器层级结构

graph TD
    A[MCP 客户端<br/>Claude Desktop / Cursor] --> B[MCP Server<br/>McpServer 实例]
    B --> C[Context 上下文<br/>会话管理器]
    C --> D[SessionManager<br/>浏览器会话管理]
    D --> E[Stagehand 实例<br/>浏览器自动化]
    F[Tools 工具集<br/>start/navigate/act/observe/extract] --> B

Browserbase MCP 服务器采用分层架构设计：

资料来源：src/server.ts:3-27src/context.ts:1-50

工具注册机制

服务器启动时，所有工具通过统一接口注册到 MCP 协议层：

// 伪代码展示工具注册流程
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

支持的传输方式

传输方式对比

资料来源：README.md:1-80

STDIO 传输配置

STDIO 传输适用于本地部署场景，服务器通过标准输入输出与客户端通信。

NPM 方式（推荐）

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["@browserbasehq/mcp"],
      "env": {
        "BROWSERBASE_API_KEY": "",
        "BROWSERBASE_PROJECT_ID": "",
        "GEMINI_API_KEY": ""
      }
    }
  }
}

本地构建方式

{
  "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 的客户端

{
  "mcpServers": {
    "browserbase": {
      "type": "http",
      "url": "https://mcp.browserbase.com/mcp"
    }
  }
}

不支持 SHTTP 的客户端

{
  "mcpServers": {
    "browserbase": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
    }
  }
}

资料来源：README.md:62-85

Docker 部署配置

{
  "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

配置参数详解

环境变量

资料来源：src/config.ts:40-55

命令行参数

资料来源：src/program.ts:28-50

默认配置

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 服务器当前提供了空的资源集合：

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 协议注册了资源处理器：

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

工具能力

核心工具集

资料来源：README.md:1-15src/tools/extract.ts:1-55

工具定义结构

export type Tool<Input extends InputType = InputType> = {
  capability: string;  // 能力分类：core
  schema: ToolSchema<Input>;
  handle: (context: Context, params: z.output<Input>) => Promise<ToolResult>;
};

export type ToolResult = {
  action?: () => Promise<ToolActionResult>;
  waitForNetwork: boolean;
};

资料来源：src/tools/tool.ts:18-30

服务器生命周期

服务端点

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: 清理资源

服务器管理

export class ServerList {
  private _servers: Server[] = [];
  private _serverFactory: () => Promise<Server>;

  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 协议返回：

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

会话验证错误

会话管理器会自动检测失效会话并触发重建：

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. 安装依赖

git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build

2. 配置环境变量

创建 .env 文件：

BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id
GEMINI_API_KEY=your_gemini_key

3. 配置客户端

根据使用的客户端，将以下配置添加到 MCP 配置文件中：

{
  "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 带来了以下破坏性变更，以与托管服务对齐：

默认模型已从 gemini-2.0-flash 更改为 google/gemini-2.5-flash-lite。

资料来源：CHANGELOG.md:1-30

相关文档

• Browserbase MCP 官方文档
• Model Context Protocol 规范
• Stagehand 浏览器自动化

概述

模型配置是 Browserbase MCP Server 的核心功能之一，用于控制浏览器自动化操作所使用的 AI 模型。该配置通过 Stagehand 框架实现网页自动化操作，包括页面导航（navigate）、元素操作（act）、页面观察（observe）和数据提取（extract）。

默认情况下，服务器使用 Google 的 Gemini 2.5 Flash Lite 模型，该模型在 Stagehand 的自动化评估中表现优异。用户也可以配置其他支持的模型（如 GPT-4o、Claude 等）来满足特定需求。

资料来源：README.md:1-50

配置架构

MCP Server 的模型配置遵循以下层次结构：

graph TD
    A[默认配置] --> B[环境变量]
    B --> C[CLI 参数]
    C --> D[最终配置]
    
    A1["defaultConfig<br/>modelName: google/gemini-2.5-flash-lite"] --> A
    B1["GEMINI_API_KEY<br/>GOOGLE_API_KEY"] --> B
    C1["--modelName<br/>--modelApiKey"] --> C

配置优先级顺序为：默认值 < 环境变量 < CLI 参数

资料来源：src/config.ts:1-30

配置参数详解

主要配置项

资料来源：src/index.ts:1-50

CLI 选项定义

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 密钥。

graph TD
    A[配置输入] --> B{modelName 是否为默认值?}
    B -->|是| C[无需 API Key]
    B -->|否| D{modelApiKey 是否存在且有效?}
    D -->|是| E[验证通过]
    D -->|否| F[抛出验证错误]
    
    F --> F1["modelApiKey is required<br/>when specifying a custom model"]

验证规则

服务器使用 Zod schema 进行配置验证，核心验证逻辑如下：

.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 密钥：

// --- Add Browserbase Env Vars ---
if (!mergedConfig.modelApiKey) {
  mergedConfig.modelApiKey =
    process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;
}

资料来源：src/config.ts:45-50

配置示例

使用默认模型

{
  "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）

{
  "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 的支持列表，用户可以使用以下类型的模型：

注意：自定义模型必须在 Stagehand 支持的模型列表中，具体支持情况请参阅 Stagehand 文档。

资料来源：README.md:95-100

完整配置流程

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

配置代码参考

默认配置对象

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 选项类型定义

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

依赖关系

模型配置功能的实现依赖于以下核心包：

资料来源：package.json:1-30

常见问题

1. 模型配置验证失败

问题：使用自定义模型时收到 "modelApiKey is required" 错误。

解决方案：确保在使用非默认模型时，通过 --modelApiKey 参数或 GEMINI_API_KEY 环境变量提供了有效的 API 密钥。

2. 模型不支持

问题：配置的模型在 Stagehand 中不被支持。

解决方案：请查阅 Stagehand 支持的模型列表，选择支持的模型。

3. API 密钥优先级

问题：不确定哪个环境变量会被使用。

优先级：--modelApiKey > GEMINI_API_KEY > GOOGLE_API_KEY

版本变更记录

资料来源：CHANGELOG.md:1-30

Pitfall Log / 踩坑日志

项目：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