{
"canonical_name": "browserbase/mcp-server-browserbase",
"compilation_id": "pack_4f1385826ad94685be208609b18e5610",
"created_at": "2026-05-21T16:35:31.962473+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx @browserbasehq/mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx @browserbasehq/mcp",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_fc81feab2afc465b8303c6dd5895b62d"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_52dd13b0d2d9fc25009c68f4f6fbccaf",
"canonical_name": "browserbase/mcp-server-browserbase",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/browserbase/mcp-server-browserbase",
"slug": "mcp-server-browserbase",
"source_packet_id": "phit_91d1008fa4d04fab89c5b128a82bd7a8",
"source_validation_id": "dval_c54342a96f3141908b3d3ae8102ada57"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 358,
"github_stars": 3343,
"one_liner_en": "Allow LLMs to control a browser with Browserbase and Stagehand",
"one_liner_zh": "Allow LLMs to control a browser with Browserbase and Stagehand",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "mcp-server-browserbase",
"title_zh": "mcp-server-browserbase 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Page Observation and Action Planning",
"label_zh": "页面观察与动作规划",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-page-observation-and-action-planning",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_91d1008fa4d04fab89c5b128a82bd7a8",
"page_model": {
"artifacts": {
"artifact_slug": "mcp-server-browserbase",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx @browserbasehq/mcp",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/browserbase/mcp-server-browserbase#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Allow LLMs to control a browser with Browserbase and Stagehand"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Your MCP server is now indexed on Joy Trust Network",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add MCPpedia security badge to README",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Add policy enforcement for cloud browser sessions",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 16,
"forks": 358,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3343
},
"source_url": "https://github.com/browserbase/mcp-server-browserbase",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Allow LLMs to control a browser with Browserbase and Stagehand",
"title": "mcp-server-browserbase 能力包",
"trial_prompt": "# mcp-server-browserbase - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-server-browserbase 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Allow LLMs to control a browser with Browserbase and Stagehand 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-components：核心组件。围绕“核心组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-overview：工具集概述。围绕“工具集概述”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-components\n输入：用户提供的“核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-overview\n输入：用户提供的“工具集概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-components：Step 4 必须围绕“核心组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-overview：Step 5 必须围绕“工具集概述”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/browserbase/mcp-server-browserbase\n- https://github.com/browserbase/mcp-server-browserbase#readme\n- README.md\n- package.json\n- index.js\n- Dockerfile\n- tsconfig.json\n- src/index.ts\n- src/server.ts\n- src/program.ts\n- src/transport.ts\n- src/config.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-server-browserbase 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: Add policy enforcement for cloud browser sessions（https://github.com/browserbase/mcp-server-browserbase/issues/176）；github/github_issue: Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alte（https://github.com/browserbase/mcp-server-browserbase/issues/127）；github/github_issue: Add MCPpedia security badge to README（https://github.com/browserbase/mcp-server-browserbase/issues/175）；github/github_issue: Your MCP server is now indexed on Joy Trust Network（https://github.com/browserbase/mcp-server-browserbase/issues/174）；github/github_release: v3.0.0（https://github.com/browserbase/mcp-server-browserbase/releases/tag/v3.0.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Add policy enforcement for cloud browser sessions",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/176"
},
{
"kind": "github_issue",
"source": "github",
"title": "Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alte",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/127"
},
{
"kind": "github_issue",
"source": "github",
"title": "Add MCPpedia security badge to README",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/175"
},
{
"kind": "github_issue",
"source": "github",
"title": "Your MCP server is now indexed on Joy Trust Network",
"url": "https://github.com/browserbase/mcp-server-browserbase/issues/174"
},
{
"kind": "github_release",
"source": "github",
"title": "v3.0.0",
"url": "https://github.com/browserbase/mcp-server-browserbase/releases/tag/v3.0.0"
}
],
"status": "已收录 5 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Allow LLMs to control a browser with Browserbase and Stagehand",
"effort": "安装已验证",
"forks": 358,
"icon": "link",
"name": "mcp-server-browserbase 能力包",
"risk": "可发布",
"slug": "mcp-server-browserbase",
"stars": 3343,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"页面观察与动作规划",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/browserbase/mcp-server-browserbase 项目说明书\n\n生成时间: 2026-05-21 16:34:02 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [安装指南](#page-installation)\n- [系统架构](#page-architecture)\n- [核心组件](#page-core-components)\n- [工具集概述](#page-tools-overview)\n- [会话管理](#page-session-management)\n- [配置参数](#page-configuration)\n- [部署指南](#page-deployment)\n- [MCP 客户端集成](#page-mcp-integration)\n- [模型配置](#page-model-configuration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [安装指南](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json)\n \n\n# 项目介绍\n\n## 1 项目概述\n\n`@browserbasehq/mcp` 是一个基于 Model Context Protocol (MCP) 的服务器实现，专门用于通过 Browserbase 和 Stagehand 实现 AI 驱动的 Web 浏览器自动化操作。该项目为 AI 助手提供了与浏览器交互的能力，支持导航网页、执行操作、观察页面元素以及提取数据等核心功能。\n\n项目基本信息如下：\n\n| 属性 | 值 |\n|------|-----|\n| 项目名称 | @browserbasehq/mcp |\n| 当前版本 | 3.0.0 |\n| 许可证 | Apache-2.0 |\n| MCP 协议名称 | io.github.browserbase/mcp-server-browserbase |\n| 开发者 | Browserbase, Inc. |\n| 仓库地址 | https://github.com/browserbase/mcp-server-browserbase |\n\n资料来源：[package.json:1-15]()\n\n## 2 核心功能\n\n该项目作为 MCP 协议的服务器实现，提供了一套完整的浏览器自动化工具集。根据 README.md 的说明，服务器暴露以下核心工具：\n\n| 工具名称 | 功能描述 | 参数 |\n|---------|---------|------|\n| `start` | 创建新的浏览器会话 | _(none)_ |\n| `end` | 关闭浏览器会话 | _(none)_ |\n| `navigate` | 导航到指定 URL | `{ url: string }` |\n| `act` | 在页面上执行操作 | `{ action: string }` |\n| `observe` | 观察页面上的可操作元素 | `{ instruction: string }` |\n| `extract` | 从页面提取数据 | `{ instruction?: string }` |\n\n资料来源：[README.md:48-54]()\n\n### 2.1 工具功能详解\n\n#### start 工具\n用于启动一个新的浏览器会话。在 3.0.0 版本中，该工具不再接受 `sessionId` 参数，这与之前版本的 `browserbase_session_create` 工具存在差异。\n\n#### end 工具\n用于关闭当前活动的浏览器会话，对应旧版本的 `browserbase_session_close`。\n\n#### navigate 工具\n通过接收 URL 参数，将浏览器导航到指定网页地址。\n\n#### act 工具\n在当前页面执行指定的操作。该操作由 AI 模型理解并转换为实际的浏览器操作。注意：在 3.0.0 版本中，`act` 工具不再接受 `variables` 参数。\n\n#### observe 工具\n根据给定的指令观察页面上的可操作元素，帮助 AI 理解页面结构。\n\n#### extract 工具\n从当前页面提取数据。`instruction` 参数现在变为可选，与 Browserbase 托管服务保持一致。\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 3 技术架构\n\n### 3.1 架构概览\n\n项目采用模块化架构设计，主要包含以下核心模块：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[MCP 服务器]\n B --> C[工具注册层]\n C --> D[上下文管理]\n D --> E[会话管理器]\n E --> F[Stagehand 实例]\n F --> G[Browserbase 云服务]\n G --> H[远程浏览器]\n```\n\n### 3.2 核心模块职责\n\n#### 入口模块 (src/index.ts)\n作为应用程序的主入口，负责初始化 MCP 服务器、注册工具、处理请求路由等核心功能。服务器通过 `server.tool()` 方法注册各个工具，每个工具都关联到对应的处理函数。\n\n```typescript\ntools.forEach((tool) => {\n if (tool.schema.inputSchema instanceof z.ZodObject) {\n server.tool(\n tool.schema.name,\n tool.schema.description,\n tool.schema.inputSchema.shape,\n async (params: z.infer) => {\n const result = await context.run(tool, params);\n return result;\n }\n );\n }\n});\n```\n\n资料来源：[src/index.ts:1-30]()\n\n#### 配置模块 (src/config.ts)\n负责管理和解析应用配置，支持多种配置来源的合并：\n\n- 默认配置\n- 环境变量\n- 命令行参数\n- 配置文件\n\n默认模型为 `google/gemini-2.5-flash-lite`，这与托管 MCP 服务器保持一致。\n\n#### 会话管理器 (src/sessionManager.ts)\n负责管理浏览器会话的生命周期，包括：\n\n- 创建新的浏览器会话\n- 验证会话状态\n- 清理过期会话\n- 批量关闭所有会话\n- 默认会话的自动维护\n\n会话管理器包含以下关键功能：\n\n| 方法 | 功能 |\n|------|------|\n| `getOrCreateSession` | 获取或创建会话 |\n| `createNewBrowserSession` | 创建新的浏览器会话 |\n| `cleanupSession` | 清理指定会话 |\n| `closeAllSessions` | 关闭所有会话 |\n| `ensureDefaultSession` | 确保默认会话存在 |\n\n资料来源：[src/sessionManager.ts:1-80]()\n\n#### 资源模块 (src/mcp/resources.ts)\n实现了 MCP 协议的资源相关接口：\n\n- `listResources()` - 列出可用资源\n- `listResourceTemplates()` - 列出资源模板\n- `readResource(uri)` - 读取指定资源\n\n当前实现中，资源功能返回空列表。\n\n#### 传输层 (src/transport.ts)\n支持两种传输方式：\n\n1. **STDIO** - 标准输入输出传输\n2. **SHTTP** - Streamable HTTP 传输\n\n服务器可以监听指定端口，提供 HTTP 服务供支持 SHTTP 的 MCP 客户端连接。\n\n## 4 依赖关系\n\n### 4.1 主要生产依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| @browserbasehq/sdk | ^2.6.0 | Browserbase SDK |\n| @browserbasehq/stagehand | ^3.3.0 | 浏览器自动化框架 |\n| @modelcontextprotocol/sdk | ^1.13.1 | MCP 协议实现 |\n| commander | ^14.0.0 | 命令行参数解析 |\n| dotenv | ^16.4.6 | 环境变量加载 |\n| zod | ^3.25.67 | 数据验证 |\n\n资料来源：[package.json:27-35]()\n\n### 4.2 关键外部服务\n\n- **Browserbase** - 提供云端浏览器基础设施\n- **Stagehand** - AI 驱动的浏览器自动化框架\n- **Gemini** - 默认使用的 AI 模型（由 GEMINI_API_KEY 或 GOOGLE_API_KEY 配置）\n\n## 5 部署方式\n\n项目支持两种部署方式：\n\n### 5.1 直接安装\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\n### 5.2 Docker 部署\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\n## 6 配置说明\n\n### 6.1 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| BROWSERBASE_API_KEY | 是 | Browserbase API 密钥 |\n| BROWSERBASE_PROJECT_ID | 是 | Browserbase 项目 ID |\n| GEMINI_API_KEY | 是 | Gemini API 密钥（默认模型使用） |\n| GOOGLE_API_KEY | 否 | Google API 密钥（备用） |\n\n### 6.2 命令行参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--proxies` | boolean | 启用代理 |\n| `--verified` | boolean | 启用验证模式 |\n| `--advancedStealth` | boolean | 启用高级隐身模式 |\n| `--contextId` | string | 指定上下文 ID |\n| `--persist` | boolean | 持久化会话 |\n| `--port` | number | HTTP 服务器端口 |\n| `--host` | string | HTTP 服务器主机 |\n| `--browserWidth` | number | 浏览器宽度 |\n| `--browserHeight` | number | 浏览器高度 |\n| `--modelName` | string | 使用的模型名称 |\n| `--modelApiKey` | string | 模型 API 密钥 |\n| `--keepAlive` | boolean | 保持连接活跃 |\n| `--experimental` | boolean | 启用实验性功能 |\n\n资料来源：[src/config.ts:10-28]()\n\n### 6.3 MCP 客户端配置示例\n\n#### STDIO 模式（自托管）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### NPM 模式\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### SHTTP 模式（托管服务）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:20-70]()\n\n## 7 版本演进\n\n### 7.1 3.0.0 版本重大变更\n\nv3.0.0 版本带来了多项重大变更：\n\n- **工具重命名**：所有工具名称与托管服务保持一致\n - `browserbase_session_create` → `start`\n - `browserbase_session_close` → `end`\n - `browserbase_stagehand_navigate` → `navigate`\n - `browserbase_stagehand_act` → `act`\n - `browserbase_stagehand_observe` → `observe`\n - `browserbase_stagehand_extract` → `extract`\n\n- **移除的工具**：\n - `browserbase_screenshot`\n - `browserbase_stagehand_get_url`\n - `browserbase_stagehand_agent`\n\n- **参数变更**：\n - `act` 工具不再接受 `variables` 参数\n - `start` 工具不再接受 `sessionId` 参数\n - `extract` 工具的 `instruction` 参数变为可选\n\n- **默认模型变更**：从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`\n\n- **依赖更新**：Stagehand 版本升级至 3.3.0\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 8 传输协议支持\n\n项目同时支持两种 MCP 传输协议：\n\n```mermaid\ngraph LR\n A[MCP 客户端] --> B{传输协议选择}\n B --> C[STDIO]\n B --> D[SHTTP]\n C --> E[本地服务器]\n D --> F[远程托管服务]\n E --> G[自托管 MCP 服务器]\n F --> H[mcp.browserbase.com]\n```\n\n### 8.1 STDIO 传输\n\n适用于本地运行场景，服务器通过标准输入输出与客户端通信。推荐使用 NPM 包 `@browserbasehq/mcp` 或直接运行构建后的代码。\n\n### 8.2 SHTTP 传输\n\n适用于使用托管服务场景。Browserbase 提供托管的 MCP 服务器，地址为 `https://mcp.browserbase.com/mcp`。这种方式可以免除本地运行和 LLM 成本。\n\n## 9 项目结构\n\n```\nmcp-server-browserbase/\n├── src/\n│ ├── index.ts # 主入口\n│ ├── context.ts # 上下文管理\n│ ├── config.ts # 配置管理\n│ ├── sessionManager.ts # 会话管理\n│ ├── transport.ts # 传输层\n│ ├── mcp/\n│ │ └── resources.ts # 资源接口\n│ └── tools/\n│ └── extract.ts # 提取工具\n├── cli.js # 命令行入口\n├── package.json # 包配置\n├── server.json # 服务器元数据\n└── README.md # 项目文档\n```\n\n## 10 相关资源\n\n- [Browserbase MCP 文档](https://docs.browserbase.com/integrations/mcp/introduction)\n- [MCP 协议文档](https://modelcontextprotocol.io/docs)\n- [MCP 协议规范](https://spec.modelcontextprotocol.io/)\n- [Stagehand 文档](https://docs.stagehand.dev/)\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [部署指南](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [Dockerfile](https://github.com/browserbase/mcp-server-browserbase/blob/main/Dockerfile)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n \n\n# 安装指南\n\n本页面详细介绍如何安装和配置 mcp-server-browserbase。MCP 服务器（Model Context Protocol Server）是 Browserbase 提供的 AI 网页自动化解决方案，通过集成 Stagehand 实现智能浏览器操作功能。\n\n## 系统要求\n\n### 运行环境\n\n| 要求项 | 最低版本 | 推荐版本 |\n|--------|----------|----------|\n| Node.js | 18.x | 20.x LTS |\n| npm/pnpm | 8.x | 最新稳定版 |\n| Docker | 24.x | 最新稳定版 |\n| Git | 2.x | 最新稳定版 |\n\n### 环境变量配置\n\n在开始安装前，需要准备以下环境变量：\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目 ID |\n| `GEMINI_API_KEY` | 是 | Gemini 模型 API 密钥（用于默认模型） |\n\n> [!TIP]\n> 如需使用其他模型，可通过 `--modelName` 参数指定，并提供对应的 API 密钥。\n\n资料来源：[README.md:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 安装方式\n\nmcp-server-browserbase 支持三种安装方式，适用于不同的使用场景：\n\n| 安装方式 | 适用场景 | 复杂度 | 更新维护 |\n|----------|----------|--------|----------|\n| NPM（推荐） | 快速集成、主流用户 | 低 | 自动 |\n| 直接安装 | 本地开发、自定义修改 | 中 | 手动 |\n| Docker | 生产环境、隔离部署 | 中 | 手动 |\n\n资料来源：[README.md:40-80](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### 方式一：NPM 安装（推荐）\n\nNPM 安装是最简洁的方式，适合大多数用户快速上手。\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### 安装步骤\n\n1. 确保已安装 Node.js 18+ 和 npm\n2. 在 MCP 配置文件中添加上述配置\n3. 填写对应的环境变量值\n4. 重启 MCP 客户端即可使用\n\n### 方式二：直接安装\n\n直接安装适合需要自定义修改或本地开发的用户。\n\n#### 前置条件\n\n- Git 已安装\n- Node.js 18+ 已安装\n- npm 或 pnpm 包管理器\n\n#### 安装命令\n\n```bash\n# 克隆仓库\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\n\n# 进入项目目录\ncd mcp-server-browserbase\n\n# 安装依赖并构建\nnpm install && npm run build\n```\n\n#### MCP 配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:10-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### 方式三：Docker 安装\n\nDocker 安装提供完整的隔离环境，适合生产部署。\n\n#### 构建镜像\n\n```bash\n# 克隆仓库\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\n\n# 进入项目目录\ncd mcp-server-browserbase\n\n# 构建 Docker 镜像\ndocker build -t mcp-browserbase .\n```\n\n#### MCP 配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:20-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 传输方式配置\n\nMCP 服务器支持两种传输协议，根据 MCP 客户端能力选择合适的传输方式：\n\n| 传输方式 | 说明 | 端口 | 推荐场景 |\n|----------|------|------|----------|\n| SHTTP（Streamable HTTP） | 推荐方式，性能最优 | 动态 | 支持 HTTP 的客户端 |\n| STDIO | 标准输入输出 | 无 | 命令行工具、本地开发 |\n\n资料来源：[src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n### SHTTP（托管服务）\n\n使用 Browserbase 托管的 MCP 服务器地址 `https://mcp.browserbase.com/mcp`，这是最简便的启动方式。\n\n#### 支持 SHTTP 的客户端配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n#### 不支持 SHTTP 的客户端配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:60-90](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### STDIO（自托管）\n\nSTDIO 方式允许完全本地运行服务器。\n\n#### NPM 方式运行\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### 本地完全自托管\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@anthropic/mcp-remote\",\n \"node\",\n \"/path/to/mcp-server-browserbase/dist/index.js\",\n \"--apiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\"\n }\n }\n }\n}\n```\n\n> [!NOTE]\n> 如需使用不同的模型，需要添加 `--modelName` 参数并提供对应的密钥。\n\n资料来源：[README.md:95-130](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 命令行参数配置\n\n服务器支持丰富的命令行参数，用于自定义部署行为：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--proxies` | boolean | false | 启用代理功能 |\n| `--verified` | boolean | false | 启用验证模式 |\n| `--advancedStealth` | boolean | false | 启用高级隐身模式 |\n| `--contextId` | string | - | 指定上下文 ID |\n| `--persist` | boolean | false | 持久化会话 |\n| `--port` | number | - | HTTP 服务端口 |\n| `--host` | string | - | HTTP 服务主机 |\n| `--browserWidth` | number | 1024 | 浏览器窗口宽度 |\n| `--browserHeight` | number | 768 | 浏览器窗口高度 |\n| `--modelName` | string | google/gemini-2.5-flash-lite | 使用的模型名称 |\n| `--modelApiKey` | string | - | 模型 API 密钥 |\n| `--keepAlive` | boolean | false | 保持连接活跃 |\n| `--experimental` | boolean | false | 启用实验性功能 |\n\n资料来源：[src/config.ts:1-40](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 配置合并优先级\n\n系统配置采用分层合并策略，优先级从低到高如下：\n\n1. **默认配置** - 代码中的硬编码默认值\n2. **文件配置** - 配置文件中的设置\n3. **CLI 参数** - 命令行传入的参数（最高优先级）\n\n```mermaid\ngraph TD\n A[默认配置] --> B[合并文件配置]\n B --> C[合并CLI参数]\n C --> D[最终配置]\n```\n\n资料来源：[src/config.ts:45-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## 项目结构与构建\n\n### 项目依赖\n\n主要生产依赖包括：\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| `@browserbasehq/sdk` | ^2.6.0 | Browserbase SDK |\n| `@browserbasehq/stagehand` | ^3.3.0 | 浏览器自动化框架 |\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP 协议实现 |\n| `commander` | ^14.0.0 | 命令行工具 |\n| `dotenv` | ^16.4.6 | 环境变量加载 |\n| `zod` | ^3.25.67 | 数据验证 |\n\n资料来源：[package.json:30-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n### 构建命令\n\n| 命令 | 说明 |\n|------|------|\n| `npm run build` | 编译 TypeScript 并设置权限 |\n| `npm run watch` | 监听模式编译 |\n| `npm test` | 运行测试 |\n| `npm run inspector` | 启动 MCP 检查器 |\n\n#### 构建流程\n\n```bash\n# 开发构建\nnpm install && npm run build\n\n# 监听模式（开发时使用）\nnpm run watch\n\n# 运行测试\nnpm test\n```\n\n资料来源：[package.json:20-35](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 完整配置示例\n\n### 开发环境配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"bb-api-key-dev\",\n \"BROWSERBASE_PROJECT_ID\": \"project-dev-123\",\n \"GEMINI_API_KEY\": \"gemini-dev-key\"\n }\n }\n }\n}\n```\n\n### 生产环境配置（Docker）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"bb-api-key-prod\",\n \"BROWSERBASE_PROJECT_ID\": \"project-prod-456\",\n \"GEMINI_API_KEY\": \"gemini-prod-key\"\n }\n }\n }\n}\n```\n\n### 自定义模型配置\n\n如需使用不同的 AI 模型：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"ANTHROPIC_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n> [!WARNING]\n> 使用的模型必须在 Stagehand 支持的模型列表中。详情请参阅 [Stagehand 文档](https://docs.stagehand.dev/examples/custom_llms#supported-llms)。\n\n资料来源：[README.md:130-160](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 验证安装\n\n安装完成后，可以通过 MCP 检查器验证服务器是否正常工作：\n\n```bash\n# 使用 npm 脚本启动检查器\nnpm run inspector\n```\n\n检查器将启动可视化界面，可以测试 MCP 服务器的各项功能和工具。\n\n资料来源：[package.json:24](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接失败 | 环境变量未设置 | 检查 `BROWSERBASE_API_KEY` 等变量 |\n| 模型调用失败 | API 密钥无效 | 验证 `GEMINI_API_KEY` |\n| 浏览器启动失败 | 权限问题 | 确保 Docker 有足够权限 |\n| 构建失败 | Node 版本过低 | 升级到 Node.js 18+ |\n\n### 环境变量验证\n\n在启动服务器前，可以创建 `.env` 文件管理环境变量：\n\n```bash\n# 创建 .env 文件\ncat > .env << EOF\nBROWSERBASE_API_KEY=your_api_key_here\nBROWSERBASE_PROJECT_ID=your_project_id_here\nGEMINI_API_KEY=your_gemini_key_here\nEOF\n```\n\n资料来源：[src/config.ts:1-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## 相关资源\n\n- [Browserbase MCP 官方文档](https://docs.browserbase.com/integrations/mcp/introduction)\n- [MCP 协议文档](https://modelcontextprotocol.io/docs)\n- [MCP 协议规范](https://spec.modelcontextprotocol.io/)\n- [Stagehand 文档](https://docs.stagehand.dev/)\n- [GitHub 仓库](https://github.com/browserbase/mcp-server-browserbase)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [核心组件](#page-core-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n \n\n# 系统架构\n\n## 概述\n\nmcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 模型提供网页自动化能力。该服务器通过集成 Browserbase 基础设施和 Stagehand 浏览器自动化框架，使 LLM 能够通过标准化接口执行网页操作。\n\n资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 核心架构组件\n\n### 组件层次结构\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n MCP_CLIENT[MCP 客户端]\n end\n \n subgraph \"传输层\"\n STDIO[STDIO 传输]\n HTTP[HTTP/SHTTP 传输]\n end\n \n subgraph \"核心服务层\"\n MCP_SERVER[MCP 服务器]\n SERVER_LIST[ServerList 管理器]\n end\n \n subgraph \"业务逻辑层\"\n CONTEXT[Context 上下文]\n SESSION_MANAGER[SessionManager 会话管理器]\n end\n \n subgraph \"工具层\"\n START[start 工具]\n END[end 工具]\n NAVIGATE[navigate 工具]\n ACT[act 工具]\n OBSERVE[observe 工具]\n EXTRACT[extract 工具]\n end\n \n subgraph \"外部集成\"\n STAGEHAND[Stagehand 框架]\n BROWSERBASE[Browserbase SDK]\n end\n \n MCP_CLIENT --> STDIO\n MCP_CLIENT --> HTTP\n STDIO --> MCP_SERVER\n HTTP --> MCP_SERVER\n MCP_SERVER --> CONTEXT\n CONTEXT --> SESSION_MANAGER\n SESSION_MANAGER --> STAGEHAND\n STAGEHAND --> BROWSERBASE\n \n START --> SESSION_MANAGER\n END --> SESSION_MANAGER\n NAVIGATE --> CONTEXT\n ACT --> CONTEXT\n OBSERVE --> CONTEXT\n EXTRACT --> CONTEXT\n```\n\n### 组件职责表\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| MCP_SERVER | src/index.ts | 注册 MCP 协议处理器，注册工具，处理请求路由 |\n| ServerList | src/server.ts | 管理多个服务器实例的生命周期 |\n| SessionManager | src/sessionManager.ts | 管理浏览器会话创建、验证、清理和复用 |\n| Context | src/context.ts | 提供工具执行上下文，集成 Stagehand 实例 |\n| Transport | src/transport.ts | 处理 HTTP 服务器启动和请求分发 |\n\n资料来源：[src/index.ts:1-100](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n## 传输层架构\n\n### 支持的传输方式\n\n该服务器支持两种传输协议，通过命令行参数指定：\n\n| 传输类型 | 配置方式 | 使用场景 |\n|---------|---------|---------|\n| STDIO | 命令行直接运行 | 本地部署，推荐用于 Claude Desktop |\n| HTTP/SHTTP | 启动 HTTP 服务器 | 远程部署，支持流式 HTTP |\n\n### HTTP 传输实现\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|HTTP POST /mcp| B[HTTP Server]\n B --> C[handleStreamable 函数]\n C --> D[ServerList]\n D --> E[MCP Server]\n E --> F[工具执行]\n```\n\nHTTP 服务器在指定端口启动，监听 `/mcp` 端点处理 MCP 请求：\n\n```typescript\nhttpServer.listen(port, hostname, () => {\n const message = [\n `Listening on ${url}`,\n \"Put this in your client config:\",\n JSON.stringify({\n mcpServers: {\n browserbase: {\n type: \"http\",\n url: `${url}/mcp`,\n },\n },\n }, undefined, 2),\n ].join(\"\\n\");\n console.log(message);\n});\n```\n\n资料来源：[src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## 会话管理架构\n\n### SessionManager 设计\n\nSessionManager 是核心的会话管理组件，负责浏览器实例的生命周期管理。\n\n```mermaid\ngraph TB\n subgraph \"SessionManager\"\n browsers[Map]\n activeSessionId[当前活动会话ID]\n defaultSessionId[默认会话ID: __default__]\n cleaningUpSessions[正在清理的会话集合]\n defaultSessionCreationPromise[创建互斥锁]\n end\n \n subgraph \"BrowserSession\"\n stagehand[Stagehand 实例]\n config[会话配置]\n end\n```\n\n### 会话状态管理\n\n| 状态 | 描述 | 处理逻辑 |\n|-----|------|---------|\n| VALID | 会话有效且可用 | 直接返回使用 |\n| STALE | 会话过期或无响应 | 关闭并重建 |\n| MISSING | 会话不存在 | 创建新会话 |\n| CREATING | 正在创建中 | 等待创建完成 |\n\n### 关键方法\n\n| 方法 | 功能 | 线程安全 |\n|-----|------|---------|\n| `ensureDefaultSession()` | 确保默认会话存在 | 使用互斥锁 |\n| `getSession()` | 获取或创建指定会话 | 支持并发 |\n| `cleanupSession()` | 清理指定会话 | 幂等操作 |\n| `closeAllSessions()` | 关闭所有会话 | 批量处理 |\n\n会话验证通过执行简单操作检测可用性：\n\n```typescript\nconst pages = this.defaultBrowserSession.stagehand.context.pages();\nif (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n}\n```\n\n资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## 工具系统架构\n\n### 工具注册流程\n\n```mermaid\ngraph TD\n A[TOOLS 数组] --> B[遍历工具]\n B --> C{schema 类型检查}\n C -->|ZodObject| D[server.tool 注册]\n C -->|非 ZodObject| E[警告日志输出]\n D --> F[MCP 服务器就绪]\n```\n\n### 内置工具列表\n\n| 工具名称 | 功能 | 必填参数 | 可选参数 |\n|---------|------|---------|---------|\n| start | 创建新浏览器会话 | 无 | proxies, modelName |\n| end | 关闭指定会话 | sessionId | 无 |\n| navigate | 导航到指定 URL | url | 无 |\n| act | 执行页面操作 | action | 无 |\n| observe | 观察可交互元素 | instruction | 无 |\n| extract | 提取页面数据 | 无 | instruction |\n\n### 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP 客户端\n participant Server as MCP Server\n participant Context as Context\n participant Tool as Tool Handler\n participant Stagehand as Stagehand\n\n MCP->>Server: 工具调用请求\n Server->>Context: context.run(tool, params)\n Context->>Tool: 调用 handle 方法\n Tool->>Stagehand: 执行实际操作\n Stagehand-->>Tool: 返回结果\n Tool-->>Context: 返回 ToolResult\n Context-->>Server: 返回执行结果\n Server-->>MCP: 返回响应\n```\n\n### 工具接口定义\n\n每个工具实现统一的接口结构：\n\n```typescript\ninterface Tool> {\n capability: \"core\" | \"extended\";\n schema: ToolSchema;\n handle: (context: Context, params: z.infer) => Promise;\n}\n```\n\n资料来源：[src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n\n## Context 上下文管理\n\n### 上下文职责\n\nContext 是连接 MCP 协议层和业务逻辑层的桥梁，负责：\n\n1. 提供 Stagehand 实例访问\n2. 管理活动会话\n3. 工具执行和错误处理\n\n```mermaid\ngraph TB\n subgraph \"Context\"\n sessionManager[SessionManager]\n activeSessionId[活动会话ID]\n end\n \n Context-->|获取| sessionManager\n Context-->|提供| stagehand\n```\n\n### 工具执行方法\n\n```typescript\nasync run(tool: Tool, params: any): Promise {\n // 调用工具的 handle 方法\n const result = await tool.handle(this, params);\n return result;\n}\n```\n\n资料来源：[src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## ServerList 服务器管理\n\n### 设计模式\n\nServerList 采用工厂模式管理多个服务器实例：\n\n```mermaid\nclassDiagram\n class ServerList {\n -_servers: Server[]\n -_serverFactory: () => Promise~Server~\n +create(): Promise~Server~\n +close(server: Server): Promise~void~\n +closeAll(): Promise~void~\n }\n```\n\n### 核心方法\n\n| 方法 | 签名 | 描述 |\n|-----|------|-----|\n| create | `() => Promise` | 创建新服务器并加入管理 |\n| close | `(server: Server) => Promise` | 关闭指定服务器 |\n| closeAll | `() => Promise` | 关闭所有服务器 |\n\n资料来源：[src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n\n## 数据流架构\n\n### 请求处理流程\n\n```mermaid\ngraph TD\n A[客户端请求] --> B{传输类型}\n B -->|STDIO| C[stdio 传输]\n B -->|HTTP| D[HTTP 服务器]\n \n C --> E[MCP Server.handle]\n D --> E\n \n E --> F[路由到工具处理器]\n F --> G[Context.run]\n G --> H[Tool.handle]\n H --> I[Stagehand 操作]\n I --> J[浏览器执行]\n J --> K[结果返回]\n K --> L[格式化响应]\n L --> M[返回给客户端]\n```\n\n### 会话创建流程\n\n```mermaid\ngraph TB\n A[start 工具调用] --> B{是否存在默认会话}\n B -->|否| C[调用 createNewBrowserSession]\n B -->|是| D{会话是否有效}\n D -->|有效| E[返回现有会话]\n D -->|无效| F[关闭旧会话]\n F --> C\n C --> G[创建 Stagehand 实例]\n G --> H[配置 Browserbase]\n H --> I[返回 BrowserSession]\n I --> J[存储到 browsers Map]\n J --> K[标记为活动会话]\n```\n\n## 配置体系\n\n### 环境变量配置\n\n| 变量名 | 必填 | 描述 |\n|-------|-----|------|\n| BROWSERBASE_API_KEY | 是 | Browserbase API 密钥 |\n| BROWSERBASE_PROJECT_ID | 是 | Browserbase 项目 ID |\n| GEMINI_API_KEY | 是 | Gemini API 密钥（用于 LLM 操作） |\n\n### 命令行参数\n\n| 参数 | 描述 | 默认值 |\n|-----|------|-------|\n| `--proxies` | 启用代理支持 | false |\n| `--modelName` | 指定使用的模型名称 | google/gemini-2.5-flash-lite |\n\n### MCP 配置示例\n\n**STDIO 模式：**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**HTTP 模式：**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n## 依赖关系\n\n### 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|-----|-----|\n| @modelcontextprotocol/sdk | ^1.13.1 | MCP 协议实现 |\n| @browserbasehq/stagehand | ^3.3.0 | 浏览器自动化框架 |\n| @browserbasehq/sdk | ^2.6.0 | Browserbase API 客户端 |\n| zod | ^3.25.67 | Schema 验证 |\n\n### 开发依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|-----|-----|\n| typescript | ^5.6.2 | TypeScript 编译 |\n| vitest | ^4.1.2 | 单元测试 |\n| eslint | ^9.29.0 | 代码检查 |\n| prettier | ^3.6.1 | 代码格式化 |\n\n资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 部署模式\n\n### 自托管部署\n\n```mermaid\ngraph LR\n A[本地机器] -->|npm run build| B[构建产物]\n B --> C[cli.js]\n C --> D[MCP 客户端]\n D --> E[Browserbase 云服务]\n```\n\n### Docker 部署\n\n```mermaid\ngraph TB\n A[Dockerfile] --> B[docker build]\n B --> C[mcp-browserbase 镜像]\n C --> D[docker run]\n D --> E[MCP 客户端连接]\n```\n\n构建命令：\n```bash\ndocker build -t mcp-browserbase .\n```\n\n运行配置：\n```json\n{\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"BROWSERBASE_API_KEY\", \"-e\", \"BROWSERBASE_PROJECT_ID\", \"-e\", \"GEMINI_API_KEY\", \"mcp-browserbase\"]\n}\n```\n\n## 安全考虑\n\n### 会话隔离\n\n- 每个会话独立的 BrowserSession 实例\n- 会话清理使用互斥锁防止竞态条件\n- 过期会话自动检测和清理\n\n### 错误处理\n\n```mermaid\ngraph TB\n A[异常发生] --> B{异常类型}\n B -->|Stagehand 错误| C[记录错误日志]\n B -->|会话无效| D[清理会话]\n B -->|创建失败| E[重试一次]\n C --> F[返回错误响应]\n D --> F\n E --> G{重试成功?}\n E -->|否| F\n G -->|是| H[返回成功]\n```\n\n### 敏感信息管理\n\n- API 密钥通过环境变量传递\n- 不在日志中输出敏感配置\n- 命令行参数支持但不推荐传递密钥\n\n## 扩展性设计\n\n### 添加新工具\n\n1. 在 `src/tools/` 目录创建新工具文件\n2. 实现 Tool 接口的 schema 和 handle 方法\n3. 将工具添加到 TOOLS 数组导出\n4. 工具将自动注册到 MCP 服务器\n\n### 自定义传输\n\n传输层支持扩展，可通过修改 `src/transport.ts` 添加新的传输协议实现。\n\n## 总结\n\nmcp-server-browserbase 采用分层架构设计，通过清晰的责任分离实现了：\n\n- **可维护性**：各组件职责明确，易于理解和修改\n- **可扩展性**：工具系统支持灵活扩展新功能\n- **可靠性**：会话管理和错误处理机制完善\n- **兼容性**：支持多种 MCP 客户端和部署方式\n\n该架构为 AI 模型提供了标准化的网页自动化接口，同时保持了与 Browserbase 生态系统的深度集成。\n\n---\n\n\n\n## 核心组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [工具集概述](#page-tools-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [src/mcp/resources.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# 核心组件\n\n本文档详细介绍了 `mcp-server-browserbase` 项目的核心组件架构，包括配置管理、会话管理、工具系统、传输层和上下文管理等关键模块。\n\n## 概述\n\nmcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于通过 Browserbase 和 Stagehand 实现 AI 网页自动化。该项目采用 TypeScript 开发，使用 `@modelcontextprotocol/sdk` 作为 MCP 协议的实现基础。\n\n**项目技术栈：**\n\n| 类别 | 技术/库 |\n|------|---------|\n| 核心框架 | `@modelcontextprotocol/sdk: ^1.13.1` |\n| 浏览器自动化 | `@browserbasehq/stagehand: ^3.3.0` |\n| 浏览器控制 | `@browserbasehq/sdk: ^2.6.0` |\n| 数据验证 | `zod: ^3.25.67` |\n| CLI 参数解析 | `commander: ^14.0.0` |\n| 环境变量 | `dotenv: ^16.4.6` |\n\n资料来源：[package.json:1-30]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[MCP 客户端] -->|STDIO/SHTTP| B[MCP Server]\n B --> C[ServerList]\n C --> D[SessionManager]\n D --> E[Stagehand 实例]\n E --> F[浏览器会话]\n \n B --> G[Context]\n G --> H[工具系统]\n H --> I[extract]\n H --> J[act]\n H --> K[navigate]\n H --> L[observe]\n \n B --> M[Resources]\n B --> N[Transport]\n```\n\n## 1. 配置管理 (Config)\n\n### 1.1 配置结构\n\n配置管理模块负责集中管理所有运行时配置选项，包括环境变量、CLI 参数和默认配置值。\n\n资料来源：[src/config.ts:1-5]()\n\n**CLI 选项类型定义：**\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\n资料来源：[src/config.ts:10-25]()\n\n### 1.2 默认配置值\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `browserbaseApiKey` | `BROWSERBASE_API_KEY` 环境变量 | Browserbase API 密钥 |\n| `browserbaseProjectId` | `BROWSERBASE_PROJECT_ID` 环境变量 | Browserbase 项目 ID |\n| `proxies` | `false` | 是否启用代理 |\n| `browserWidth` | `1024` | 浏览器窗口宽度 |\n| `browserHeight` | `768` | 浏览器窗口高度 |\n| `modelName` | `google/gemini-2.5-flash-lite` | 默认模型名称 |\n| `modelApiKey` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | 模型 API 密钥 |\n\n资料来源：[src/config.ts:28-40]()\n\n### 1.3 配置合并策略\n\n配置采用分层合并策略，优先级顺序为：**默认值 < 文件配置 < CLI 参数**\n\n```typescript\nexport async function resolveConfig(cliOptions: CLIOptions): Promise {\n const cliConfig = await configFromCLIOptions(cliOptions);\n const mergedConfig = normalizeVerifiedConfig(\n mergeConfig(defaultConfig, cliConfig),\n );\n // 环境变量补充\n if (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n }\n return mergedConfig;\n}\n```\n\n资料来源：[src/config.ts:45-58]()\n\n## 2. 会话管理器 (SessionManager)\n\n### 2.1 概述\n\nSessionManager 是整个系统的核心组件，负责管理多个浏览器会话的生命周期。每个会话对应一个独立的 Stagehand 实例和底层浏览器实例。\n\n资料来源：[src/sessionManager.ts:1-10]()\n\n### 2.2 核心数据结构\n\n```typescript\nclass SessionManager {\n private browsers: Map = new Map();\n private defaultSessionId: string = \"(default)\";\n private defaultBrowserSession: BrowserSession | null = null;\n private defaultSessionCreationPromise: Promise | null = null;\n private activeSessionId: string = \"(default)\";\n private cleaningUpSessions: Set = new Set();\n}\n\ntype BrowserSession = {\n stagehand: Stagehand;\n config: Config;\n};\n```\n\n资料来源：[src/sessionManager.ts:1-50]()\n\n### 2.3 会话生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建中: createSession()\n 创建中 --> 活跃: 创建成功\n 创建中 --> [*]: 创建失败\n 活跃 --> 清理中: cleanupSession()\n 活跃 --> 失效: 检测到过期\n 失效 --> [*]: 自动清理\n 清理中 --> [*]: 清理完成\n```\n\n### 2.4 主要方法\n\n| 方法 | 功能 | 说明 |\n|------|------|------|\n| `createSession()` | 创建新会话 | 初始化 Stagehand 实例 |\n| `getOrCreateDefaultSession()` | 获取或创建默认会话 | 懒加载机制 |\n| `cleanupSession(sessionId)` | 清理指定会话 | 优雅关闭浏览器 |\n| `closeAllSessions()` | 关闭所有会话 | 批量清理 |\n| `setActiveSessionId(id)` | 设置活跃会话 | 管理当前会话 |\n\n资料来源：[src/sessionManager.ts:60-120]()\n\n### 2.5 会话验证机制\n\nSessionManager 实现了一套完整的会话有效性验证机制：\n\n1. **简单验证**：检查 `pages` 是否存在且数量大于 0\n2. **错误捕获**：任何操作异常都会触发会话重建\n3. **自动重试**：首次创建失败后自动重试一次\n\n```typescript\n// 会话有效性检查示例\nconst pages = this.defaultBrowserSession.stagehand.context.pages();\nif (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n}\n```\n\n资料来源：[src/sessionManager.ts:150-180]()\n\n### 2.6 并发控制\n\n为防止重复创建会话，SessionManager 使用 Promise 缓存机制：\n\n```typescript\nprivate defaultSessionCreationPromise: Promise | null = null;\n```\n\n当一个会话正在创建时，后续请求会等待同一 Promise，而不是触发新的创建操作。\n\n资料来源：[src/sessionManager.ts:100-110]()\n\n## 3. 上下文管理 (Context)\n\n### 3.1 概述\n\nContext 是工具执行时的运行时上下文，负责协调 SessionManager 和工具之间的交互。\n\n资料来源：[src/context.ts:1-10]()\n\n### 3.2 核心职责\n\n```mermaid\ngraph LR\n A[工具请求] --> B[Context.run]\n B --> C[SessionManager]\n C --> D[获取 Stagehand]\n D --> E[执行工具]\n E --> F[返回结果]\n```\n\n### 3.3 工具执行流程\n\n```typescript\nasync run(tool: Tool, params: unknown): Promise {\n const session = await this.sessionManager.getOrCreateDefaultSession();\n \n if (tool.handle) {\n const result = await tool.handle(this, params);\n return result;\n }\n \n throw new Error(`Tool ${tool.schema.name} does not have a handle method`);\n}\n```\n\n资料来源：[src/context.ts:30-50]()\n\n### 3.4 资源管理\n\nContext 还负责 MCP 资源的列表和读取操作：\n\n```typescript\nlistResources() {\n return listResources();\n}\n\nreadResource(uri: string) {\n return readResource(uri);\n}\n```\n\n资料来源：[src/context.ts:55-65]()\n\n## 4. 工具系统 (Tools)\n\n### 4.1 工具架构\n\n工具系统采用插件化架构，每个工具都是一个独立模块，遵循统一的接口定义。\n\n资料来源：[src/tools/tool.ts:1-40]()\n\n### 4.2 工具类型定义\n\n```typescript\nexport type Tool = {\n capability: string; // 工具能力分类\n schema: ToolSchema; // 工具元数据\n handle: (context: Context, params: z.output) => Promise;\n};\n\nexport type ToolResult = {\n action?: () => Promise;\n waitForNetwork: boolean;\n};\n```\n\n资料来源：[src/tools/tool.ts:20-35]()\n\n### 4.3 工具定义示例：extract\n\n以下以 `extract` 工具为例说明工具的实现方式：\n\n资料来源：[src/tools/extract.ts:1-50]()\n\n```typescript\nconst ExtractInputSchema = z.object({\n instruction: z.string().optional(),\n});\n\nconst extractSchema: ToolSchema = {\n name: \"extract\",\n description: \"Extract data from the page\",\n inputSchema: ExtractInputSchema,\n};\n\nasync function handleExtract(\n context: Context,\n params: ExtractInput,\n): Promise {\n const action = async (): Promise => {\n const stagehand = await context.getStagehand();\n const extraction = params.instruction\n ? await stagehand.extract(params.instruction)\n : await stagehand.extract({});\n return { content: [{ type: \"text\", text: JSON.stringify({ success: true, data: extraction }) }] };\n };\n return { action, waitForNetwork: false };\n}\n```\n\n资料来源：[src/tools/extract.ts:15-45]()\n\n### 4.4 核心工具列表\n\n| 工具名称 | 功能描述 | 输入参数 |\n|----------|----------|----------|\n| `start` | 创建新的浏览器会话 | `{ proxies?: boolean, verified?: boolean, ... }` |\n| `end` | 关闭当前会话 | - |\n| `navigate` | 导航到指定 URL | `{ url: string }` |\n| `act` | 执行页面操作 | `{ action: string }` |\n| `observe` | 观察页面可交互元素 | `{ instruction: string }` |\n| `extract` | 从页面提取数据 | `{ instruction?: string }` |\n\n资料来源：[README.md:1-50]()\n\n### 4.5 工具注册流程\n\n工具通过 `tools.ts` 统一注册到 MCP 服务器：\n\n```typescript\nconst tools: MCPToolsArray = [...TOOLS];\n\ntools.forEach((tool) => {\n if (tool.schema.inputSchema instanceof z.ZodObject) {\n server.tool(\n tool.schema.name,\n tool.schema.description,\n tool.schema.inputSchema.shape,\n async (params) => {\n const result = await context.run(tool, params);\n return result;\n }\n );\n }\n});\n```\n\n资料来源：[src/index.ts:50-80]()\n\n## 5. 传输层 (Transport)\n\n### 5.1 传输方式\n\nmcp-server-browserbase 支持两种传输方式：\n\n| 传输方式 | 说明 | 使用场景 |\n|----------|------|----------|\n| STDIO | 标准输入输出 | 本地 CLI 工具集成 |\n| SHTTP | 流式 HTTP | 远程/托管部署 |\n\n资料来源：[README.md:60-80]()\n\n### 5.2 HTTP 传输实现\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|HTTP 请求| B[HTTP Server]\n B --> C[handleStreamable]\n C --> D[ServerList]\n D --> E[Server 实例]\n```\n\n### 5.3 服务器地址解析\n\n传输层支持动态端口和地址解析：\n\n```typescript\nlet resolvedHost = address.family === \"IPv4\" \n ? address.address \n : `[${address.address}]`;\nif (resolvedHost === \"0.0.0.0\" || resolvedHost === \"[::]\") {\n resolvedHost = \"localhost\";\n}\n```\n\n资料来源：[src/transport.ts:50-70]()\n\n## 6. 服务器管理 (ServerList)\n\n### 6.1 概述\n\nServerList 负责管理多个 MCP Server 实例的生命周期。\n\n资料来源：[src/server.ts:1-30]()\n\n### 6.2 类结构\n\n```typescript\nexport class ServerList {\n private _servers: Server[] = [];\n private _serverFactory: () => Promise;\n\n async create(): Promise { /* ... */ }\n async close(server: Server): Promise { /* ... */ }\n async closeAll(): Promise { /* ... */ }\n}\n```\n\n资料来源：[src/server.ts:5-25]()\n\n## 7. 资源系统 (Resources)\n\n### 7.1 概述\n\nMCP 资源系统提供了只读数据的访问接口。当前实现为空结构，保留扩展能力。\n\n资料来源：[src/mcp/resources.ts:1-20]()\n\n### 7.2 资源定义\n\n```typescript\nexport const RESOURCES = [];\nexport const RESOURCE_TEMPLATES = [];\n\nexport function listResources() {\n return { resources: [] };\n}\n\nexport function listResourceTemplates() {\n return { resourceTemplates: [] };\n}\n\nexport function readResource(uri: string) {\n return { contents: [{ uri, text: `Resource not found: ${uri}` }] };\n}\n```\n\n资料来源：[src/mcp/resources.ts:1-25]()\n\n## 8. 组件交互关系\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP Server\n participant Context as Context\n participant SessionMgr as SessionManager\n participant Tool as Tool Handler\n participant Stagehand as Stagehand\n\n Client->>Server: 请求工具调用\n Server->>Context: run(tool, params)\n Context->>SessionMgr: getOrCreateDefaultSession()\n SessionMgr-->>Context: BrowserSession\n Context->>Tool: handle(context, params)\n Tool->>Stagehand: 执行操作\n Stagehand-->>Tool: 操作结果\n Tool-->>Context: ToolResult\n Context-->>Server: 执行结果\n Server-->>Client: MCP 响应\n```\n\n## 9. 错误处理机制\n\n### 9.1 工具执行错误\n\n```typescript\ntry {\n const result = await context.run(tool, params);\n return result;\n} catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n process.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`\n );\n throw new Error(`Failed to run tool '${tool.schema.name}': ${errorMessage}`);\n}\n```\n\n资料来源：[src/index.ts:60-75]()\n\n### 9.2 会话清理错误\n\nSessionManager 在清理会话时使用幂等设计，确保重复清理不会导致问题：\n\n```typescript\nif (this.cleaningUpSessions.has(sessionIdToLog)) {\n process.stderr.write(\n `[SessionManager] Session ${sessionIdToLog} is already being cleaned up, skipping.\\n`\n );\n return;\n}\n```\n\n资料来源：[src/sessionManager.ts:80-90]()\n\n## 10. 总结\n\nmcp-server-browserbase 的核心组件架构体现了清晰的职责分离：\n\n- **Config** 提供了统一的配置管理\n- **SessionManager** 实现了浏览器会话的完整生命周期管理\n- **Context** 作为运行时上下文连接各组件\n- **Tools** 采用插件化设计便于扩展\n- **Transport** 支持多种传输协议\n- **ServerList** 管理服务器实例\n\n这套架构确保了系统的可维护性、可扩展性和可靠性。\n\n---\n\n\n\n## 工具集概述\n\n### 相关页面\n\n相关主题：[会话管理](#page-session-management), [核心组件](#page-core-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n- [src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n- [src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n- [src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n \n\n# 工具集概述\n\n## 简介\n\nmcp-server-browserbase 的工具集（Tools）是该 MCP 服务器的核心功能模块，为大语言模型（LLM）提供浏览器自动化操作能力。通过这些工具，AI 模型可以控制浏览器执行网页导航、元素交互、页面观察和数据提取等任务。\n\n工具集基于 [Stagehand](https://www.stagehand.dev) 框架构建，封装了 Playwright 的底层能力，提供声明式的网页操作接口。每个工具都遵循统一的类型定义和注册机制，确保与 MCP 协议的无缝集成。\n\n**核心功能定位：**\n\n- 为 AI Agent 提供浏览器控制能力\n- 支持会话级别的浏览器状态管理\n- 通过自然语言指令驱动网页自动化操作\n\n## 架构设计\n\n### 工具类型系统\n\n工具系统采用泛型设计，通过 TypeScript 的类型约束确保类型安全。核心类型定义位于 `src/tools/tool.ts` 文件中。\n\n```typescript\nexport type ToolSchema = {\n name: string;\n description: string;\n inputSchema: Input;\n};\n```\n\n每个工具包含三个核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `capability` | `string` | 工具能力分类，如 \"core\" |\n| `schema` | `ToolSchema` | 工具元数据，包含名称、描述和输入模式 |\n| `handle` | `Function` | 工具执行逻辑，处理输入参数并返回结果 |\n\n**工具执行结果类型：**\n\n```typescript\nexport type ToolResult = {\n action?: () => Promise;\n waitForNetwork: boolean;\n};\n```\n\n资料来源：[src/tools/tool.ts:1-30]()\n\n### 工具执行流程\n\n工具的执行通过 `Context` 类的 `run` 方法统一调度。当 MCP 客户端调用工具时，系统按以下流程处理：\n\n```mermaid\ngraph TD\n A[MCP 客户端请求] --> B[Context.run 调度]\n B --> C{工具类型检查}\n C -->|标准工具| D[调用 tool.handle]\n C -->|代理工具| E[代理转发]\n D --> F[Stagehand 执行]\n E --> F\n F --> G[返回 ToolResult]\n G --> H[转换为 MCP 响应]\n```\n\n资料来源：[src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## 核心工具列表\n\n### 工具注册机制\n\n所有工具通过 `src/tools/index.ts` 统一导出和管理。服务器启动时，工具被批量注册到 MCP 服务器实例：\n\n```typescript\nconst tools: MCPToolsArray = [...TOOLS];\n\ntools.forEach((tool) => {\n if (tool.schema.inputSchema instanceof z.ZodObject) {\n server.tool(\n tool.schema.name,\n tool.schema.description,\n tool.schema.inputSchema.shape,\n async (params) => {\n const result = await context.run(tool, params);\n return result;\n },\n );\n }\n});\n```\n\n资料来源：[src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n### 工具清单\n\n| 工具名称 | 功能描述 | 输入参数 | 核心能力 |\n|----------|----------|----------|----------|\n| `start` | 创建新浏览器会话 | `sessionId?: string` | 会话管理 |\n| `end` | 关闭浏览器会话 | `sessionId?: string` | 会话管理 |\n| `navigate` | 导航至指定 URL | `{ url: string }` | 页面访问 |\n| `act` | 执行页面动作 | `{ action: string, variables?: object }` | 元素交互 |\n| `observe` | 观察可操作元素 | `{ instruction: string }` | 元素识别 |\n| `extract` | 提取页面数据 | `{ instruction?: string }` | 数据采集 |\n\n资料来源：[README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 工具详解\n\n### navigate 工具\n\n`navigate` 工具负责将浏览器导航至指定的 URL 地址。\n\n**工具模式定义：**\n\n```typescript\nconst NavigateInputSchema = z.object({\n url: z.string().min(1),\n});\n\nconst navigateSchema: ToolSchema = {\n name: \"navigate\",\n description: \"Navigate to a URL\",\n inputSchema: NavigateInputSchema,\n};\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `url` | `string` | 是 | 目标网页 URL，必须为非空字符串 |\n\n**执行逻辑：**\n\n1. 通过 `context.getStagehand()` 获取当前 Stagehand 实例\n2. 获取浏览器上下文的页面列表\n3. 调用 `page.goto()` 导航至目标 URL\n4. 等待 DOM 内容加载完成（`domcontentloaded`）\n5. 返回导航结果 JSON\n\n**返回值示例：**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"url\": \"https://example.com\"\n }\n}\n```\n\n**错误处理：**\n\n- 当没有可用页面时抛出 `\"No active page available\"`\n- 导航失败时抛出具体错误信息\n\n资料来源：[src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n\n### act 工具\n\n`act` 工具用于执行页面上的用户操作，如点击、输入文本等。\n\n**工具模式定义：**\n\n```typescript\nconst ActInputSchema = z.object({\n action: z.string().min(1),\n});\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `action` | `string` | 是 | 自然语言描述的待执行动作 |\n\n**执行逻辑：**\n\n`act` 工具将自然语言动作描述传递给 Stagehand 的 `act` 方法，由 AI 模型解析并执行相应的网页操作。\n\n资料来源：[src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n\n### observe 工具\n\n`observe` 工具用于观察和识别页面上可交互的元素。\n\n**工具模式定义：**\n\n```typescript\nconst ObserveInputSchema = z.object({\n instruction: z.string().min(1),\n});\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `instruction` | `string` | 是 | 观察指令，描述要查找的元素或区域 |\n\n**执行逻辑：**\n\n`observe` 工具调用 Stagehand 的 `observe` 方法，识别页面中符合指令描述的可交互元素，并返回识别结果。\n\n资料来源：[src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n\n### extract 工具\n\n`extract` 工具用于从当前页面提取结构化数据。\n\n**工具模式定义：**\n\n```typescript\nconst ExtractInputSchema = z.object({\n instruction: z.string().optional(),\n});\n\nconst extractSchema: ToolSchema = {\n name: \"extract\",\n description: \"Extract data from the page\",\n inputSchema: ExtractInputSchema,\n};\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `instruction` | `string` | 否 | 可选的提取指令，描述要提取的数据 |\n\n**执行逻辑：**\n\n1. 获取当前 Stagehand 实例\n2. 根据是否提供指令参数调用对应的提取方法：\n - 有指令时：`stagehand.extract(params.instruction)`\n - 无指令时：`stagehand.extract({})`\n3. 返回提取结果的 JSON 表示\n\n**返回值示例：**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"extracted_content\": \"...\"\n }\n}\n```\n\n**设计特点：**\n\n- `instruction` 参数为可选项，设计上兼容无参数的默认提取行为\n- 返回值统一封装在 `{ success, data }` 结构中\n\n资料来源：[src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n\n## 会话管理\n\n### BrowserSession 结构\n\n工具的执行依赖于 `BrowserSession` 对象，该对象封装了 Stagehand 实例和相关的会话状态：\n\n```typescript\ninterface BrowserSession {\n id: string;\n stagehand: Stagehand;\n config: Config;\n // ... 其他会话状态\n}\n```\n\n资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### 会话生命周期\n\n```mermaid\ngraph LR\n A[创建会话] --> B[激活会话]\n B --> C[执行工具]\n C --> D[验证会话]\n D -->|正常| C\n D -->|失效| E[清理会话]\n E --> A\n C --> F[结束会话]\n```\n\n**会话创建流程：**\n\n1. 调用 `createSession(config)` 创建新会话\n2. 初始化 Stagehand 实例\n3. 将会话添加到 `browsers` Map 中\n4. 设置为活跃会话\n\n**会话验证机制：**\n\n- 定期检查会话有效性\n- 验证页面列表是否存在\n- 失效时自动重建会话\n\n资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## 工具扩展\n\n### 定义新工具\n\n项目提供了 `defineTool` 辅助函数用于标准化工具定义：\n\n```typescript\nexport function defineTool(\n tool: Tool,\n): Tool {\n return tool;\n}\n```\n\n**创建新工具的步骤：**\n\n1. 定义 Zod 输入模式\n2. 创建工具模式对象（schema）\n3. 实现 handle 处理函数\n4. 组装并导出工具对象\n5. 在 `index.ts` 中注册工具\n\n### 工具能力分类\n\n工具通过 `capability` 属性进行分类：\n\n| 能力值 | 说明 |\n|--------|------|\n| `core` | 核心工具，MCP 服务器的标准能力 |\n| `extended` | 扩展工具，需额外配置启用 |\n\n资料来源：[src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n\n## 版本变更记录\n\n### v3.0.0 重大变更\n\n根据 CHANGELOG.md，3.0.0 版本对工具集进行了重大调整：\n\n| 旧工具名 | 新工具名 | 变更类型 |\n|----------|----------|----------|\n| `browserbase_session_create` | `start` | 重命名 |\n| `browserbase_session_close` | `end` | 重命名 |\n| `browserbase_stagehand_navigate` | `navigate` | 重命名 |\n| `browserbase_stagehand_act` | `act` | 重命名 |\n| `browserbase_stagehand_observe` | `observe` | 重命名 |\n| `browserbase_stagehand_extract` | `extract` | 重命名 |\n| `browserbase_screenshot` | - | 移除 |\n| `browserbase_stagehand_get_url` | - | 移除 |\n| `browserbase_stagehand_agent` | - | 移除 |\n\n**其他变更：**\n\n- `act` 工具不再接受 `variables` 参数\n- `start` 工具不再接受 `sessionId` 参数\n- `extract` 工具的 `instruction` 参数改为可选\n- 默认模型从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`\n\n资料来源：[CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n\n## 总结\n\nmcp-server-browserbase 的工具集提供了完整的浏览器自动化能力封装。通过统一的类型系统、清晰的工具定义模式和模块化的架构设计，开发者可以便捷地扩展新的工具功能，同时保持与 MCP 协议的良好兼容性。工具集的核心价值在于将复杂的网页操作抽象为简单的自然语言指令，使 AI Agent 能够以声明式的方式控制浏览器完成各类自动化任务。\n\n---\n\n\n\n## 会话管理\n\n### 相关页面\n\n相关主题：[工具集概述](#page-tools-overview), [配置参数](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n \n\n# 会话管理\n\n## 概述\n\n会话管理是 MCP Server Browserbase 的核心子系统，负责创建、管理和销毁浏览器会话实例。该系统基于 [Stagehand](https://www.stagehand.dev) 构建，通过 Browserbase 云基础设施提供稳定的浏览器自动化能力。\n\n会话管理器在整个 MCP 服务器中扮演中间层角色，连接上层的 MCP 协议处理与下层的 Stagehand 浏览器实例：\n\n- **上层**：接收 MCP 客户端的工具调用请求\n- **中层**：通过 SessionManager 管理会话生命周期和状态同步\n- **下层**：调用 Stagehand SDK 执行实际的浏览器操作 资料来源：[src/context.ts:49-56]()\n\n## 核心组件\n\n### BrowserSession 数据结构\n\n```typescript\ninterface BrowserSession {\n page: Page; // Playwright Page 实例\n sessionId: string; // Browserbase 会话 ID\n stagehand: Stagehand; // Stagehand 实例\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `page` | `Page` | Playwright 页面对象，用于执行浏览器操作 |\n| `sessionId` | `string` | Browserbase 云端会话的唯一标识符 |\n| `stagehand` | `Stagehand` | Stagehand SDK 实例，管理浏览器上下文 |\n\n资料来源：[src/sessionManager.ts:89-93]()\n\n### SessionManager 类\n\nSessionManager 是会话管理的中央控制器，负责维护会话状态机和管理会话集合。\n\n```mermaid\ngraph TD\n subgraph SessionManager 内部状态\n BM[browsers: Map]\n DS[defaultSessionId: string]\n AS[activeSessionId: string]\n DBS[defaultBrowserSession: BrowserSession | null]\n CP[defaultSessionCreationPromise: Promise | null]\n CS[cleaningUpSessions: Set]\n end\n \n subgraph 公共接口\n GI[getOrCreateSession]\n GC[getSession]\n CL[cleanupSession]\n CA[closeAllSessions]\n GA[getActiveSessionId]\n end\n```\n\n#### 关键属性\n\n| 属性 | 类型 | 默认值 | 用途 |\n|------|------|--------|------|\n| `browsers` | `Map` | 新建空 Map | 存储所有活跃会话 |\n| `defaultSessionId` | `string` | `\"default\"` | 默认会话标识符 |\n| `activeSessionId` | `string` | `\"default\"` | 当前活跃会话标识符 |\n| `defaultBrowserSession` | `BrowserSession \\| null` | `null` | 默认会话缓存引用 |\n| `defaultSessionCreationPromise` | `Promise \\| null` | `null` | 创建互斥锁，防止并发创建 |\n| `cleaningUpSessions` | `Set` | 新建空 Set | 跟踪正在清理的会话，防止重复关闭 |\n\n资料来源：[src/sessionManager.ts:75-88]()\n\n## 会话生命周期\n\n### 状态转换图\n\n```mermaid\nstateDiagram-v2\n [*] --> 不存在: 初始化\n 不存在 --> 活跃: createNewBrowserSession\n 活跃 --> 正在清理: cleanupSession / closeAllSessions\n 正在清理 --> 不存在: close 完成\n 活跃 --> 正在清理: 验证失败 (stale)\n 正在清理 --> 活跃: 自动重建 (仅限默认会话)\n```\n\n### 创建会话流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Context\n participant SessionManager\n participant Stagehand\n participant Browserbase\n\n Client->>Context: 调用 start 工具\n Context->>SessionManager: ensureDefaultSessionInternal()\n alt 默认会话不存在\n SessionManager->>SessionManager: 设置创建互斥锁\n SessionManager->>Stagehand: createStagehandInstance()\n Stagehand->>Browserbase: 创建云端会话\n Browserbase-->>Stagehand: 返回 sessionId\n Stagehand-->>SessionManager: 返回 Stagehand 实例\n SessionManager->>SessionManager: 存储到 browsers Map\n SessionManager->>SessionManager: 缓存到 defaultBrowserSession\n SessionManager->>SessionManager: 设置 activeSessionId\n else 存在但失效\n SessionManager->>SessionManager: 关闭旧会话\n SessionManager->>SessionManager: 重新创建\n end\n SessionManager-->>Context: BrowserSession\n Context-->>Client: 返回会话信息\n```\n\n#### 创建会话的核心逻辑\n\n```typescript\nasync createNewBrowserSession(\n newSessionId: string,\n config: Config,\n resumeSessionId?: string,\n): Promise\n```\n\n**前置条件校验**：\n\n1. 验证 `config.browserbaseApiKey` 存在\n2. 验证 `config.browserbaseProjectId` 存在\n\n**创建步骤**：\n\n1. 调用 `createStagehandInstance()` 创建 Stagehand 实例\n2. 获取 Playwright Page 实例：`stagehand.context.pages()[0]`\n3. 提取 Browserbase Session ID：`stagehand.browserbaseSessionId`\n4. 构造 BrowserSession 对象并存储到 Map\n\n资料来源：[src/sessionManager.ts:131-175]()\n\n### 验证与重建机制\n\nSessionManager 实现了自动健康检查机制，确保会话可用性：\n\n```mermaid\ngraph TD\n A[获取会话] --> B{会话存在?}\n B -->|否| C[创建新会话]\n B -->|是| D{会话有效?}\n D -->|是| E[返回会话]\n D -->|否| F[关闭失效会话]\n F --> G{是默认会话?}\n G -->|是| H[自动重建]\n G -->|否| I[返回 null]\n H --> C\n```\n\n**有效性检测**：\n\n```typescript\ntry {\n const pages = sessionObj.stagehand.context.pages();\n if (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n }\n} catch {\n // 标记为 stale，执行清理\n}\n```\n\n资料来源：[src/sessionManager.ts:114-130]()\n\n## 工具接口\n\n### 会话管理工具列表\n\n| 工具名称 | 描述 | 功能级别 |\n|----------|------|----------|\n| `start` | 启动新会话 | 核心 |\n| `end` | 关闭会话 | 核心 |\n\n资料来源：[src/tools/index.ts:14-15]()\n\n### start 工具\n\n启动一个新的 Browserbase 会话。\n\n**参数结构**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `resumeSessionId` | `string` | 否 | 可选的 Browserbase Session ID，用于恢复已有会话 |\n\n**返回值**：\n\n```json\n{\n \"sessionId\": \"string\",\n \"debuggerUrl\": \"string\"\n}\n```\n\n### end 工具\n\n优雅关闭指定会话。\n\n**参数结构**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `sessionId` | `string` | 是 | 要关闭的会话 ID |\n\n## 并发控制\n\n### 互斥锁模式\n\n为防止多个并发请求同时创建默认会话，SessionManager 实现了 Promise-based 互斥锁：\n\n```typescript\nasync ensureDefaultSessionInternal(config: Config): Promise {\n // 如果创建已在进行中，等待现有 Promise\n if (this.defaultSessionCreationPromise) {\n return await this.defaultSessionCreationPromise;\n }\n\n // 设置互斥锁并开始创建\n this.defaultSessionCreationPromise = (async () => {\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n } finally {\n this.defaultSessionCreationPromise = null; // 解锁\n }\n })();\n\n return await this.defaultSessionCreationPromise;\n}\n```\n\n### 清理状态追踪\n\n使用 Set 跟踪正在清理的会话，防止重复关闭：\n\n```typescript\nasync closeBrowserGracefully(\n session: BrowserSession | undefined | null,\n sessionIdToLog: string,\n): Promise {\n // 检查是否已在清理中\n if (this.cleaningUpSessions.has(sessionIdToLog)) {\n return; // 跳过\n }\n\n this.cleaningUpSessions.add(sessionIdToLog);\n try {\n if (session?.stagehand) {\n await session.stagehand.close();\n }\n } finally {\n this.cleaningUpSessions.delete(sessionIdToLog);\n }\n}\n```\n\n## Context 集成\n\n### SessionManager 在 Context 中的角色\n\nContext 类是 MCP 服务器的主控制器，通过 SessionManager 提供会话访问：\n\n```mermaid\ngraph LR\n subgraph Context\n SM[getSessionManager]\n CS[currentSessionId getter]\n GS[getStagehand]\n end\n \n SM --> |获取| SessionManager\n CS --> |代理| SessionManager.getActiveSessionId\n GS --> |委托| SessionManager.getSession\n```\n\n**关键方法**：\n\n| 方法 | 签名 | 说明 |\n|------|------|------|\n| `getSessionManager()` | `SessionManager` | 返回 SessionManager 实例 |\n| `currentSessionId` | `string` (getter) | 获取当前活跃会话 ID |\n| `getStagehand(sessionId?)` | `Promise` | 获取指定会话的 Stagehand 实例 |\n\n资料来源：[src/context.ts:61-78]()\n\n## 配置要求\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目 ID |\n| `GEMINI_API_KEY` | 否 | Gemini 模型 API 密钥（使用 Gemini 时必需） |\n\n### 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--modelName` | 指定使用的模型名称（如使用非 Gemini 模型） |\n| `--proxies` | 启用代理支持 |\n\n## 错误处理\n\n### 常见错误场景\n\n| 场景 | 错误信息 | 处理方式 |\n|------|----------|----------|\n| API Key 缺失 | `Browserbase API Key is missing in the configuration.` | 阻止会话创建 |\n| Project ID 缺失 | `Browserbase Project ID is missing in the configuration.` | 阻止会话创建 |\n| 会话创建失败 | `Failed to create/connect session ${sessionId}: ${errorMessage}` | 抛出异常，由调用方处理 |\n| 页面不可用 | `No pages available in Stagehand context` | 标记会话为 stale，触发重建 |\n\n### 重试机制\n\n默认会话创建失败后会自动重试一次：\n\n```typescript\n} catch (creationError) {\n // 首次失败，记录错误\n process.stderr.write(`[SessionManager] Initial attempt failed: ${errorMessage}\\n`);\n \n // 重试一次\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n } catch (retryError) {\n throw new Error(`Failed after initial error and retry: ${finalErrorMessage}`);\n }\n}\n```\n\n## 与其他模块的交互\n\n```mermaid\ngraph TD\n subgraph MCP Server\n Server[MCP Server]\n Tools[工具处理器]\n end\n \n subgraph Core\n Context[Context]\n SessionManager[SessionManager]\n end\n \n subgraph 工具层\n navigateTool[navigate]\n actTool[act]\n observeTool[observe]\n extractTool[extract]\n end\n \n subgraph 底层\n Stagehand[Stagehand SDK]\n Browserbase[Browserbase Cloud]\n end\n \n Server --> Context\n Tools --> Context.run\n Context --> SessionManager\n SessionManager --> Stagehand\n Stagehand --> Browserbase\n \n navigateTool --> Context.getStagehand\n actTool --> Context.getStagehand\n observeTool --> Context.getStagehand\n extractTool --> Context.getStagehand\n```\n\n## 最佳实践\n\n1. **使用默认会话**：大多数场景下无需指定会话 ID，系统会自动管理\n2. **避免手动关闭会话**：使用 `end` 工具而非直接操作 SessionManager\n3. **监控会话状态**：通过 Browserbase Live Debugger URL 监控会话：`https://www.browserbase.com/sessions/${sessionId}`\n4. **处理并发请求**：系统内置互斥锁，但建议限制并发调用频率\n5. **会话清理**：长时间空闲后再次使用会自动验证并重建会话\n\n---\n\n\n\n## 配置参数\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment), [安装指南](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [cli.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/cli.js)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# 配置参数\n\n## 概述\n\n配置参数系统是 mcp-server-browserbase 项目中用于控制 MCP 服务器行为的核心模块。该系统通过整合环境变量、命令行参数和默认配置值，为服务器提供灵活的运行时配置能力。配置参数决定了浏览器会话的创建方式、代理设置、模型选择、视图端口尺寸等关键运行参数。\n\n配置系统的设计遵循分层覆盖原则，优先级顺序为：默认值 < 环境变量 < 命令行参数。这种设计允许用户通过多种途径自定义服务器行为，同时保持合理的默认值以简化初次使用体验。\n\n---\n\n## 配置参数类型\n\n### 环境变量\n\n环境变量是配置服务器的基础方式，特别适用于生产环境部署和 Docker 容器化场景。系统支持以下环境变量：\n\n| 环境变量名 | 说明 | 必填 | 示例 |\n|-----------|------|------|------|\n| `BROWSERBASE_API_KEY` | Browserbase 平台的 API 密钥，用于身份验证 | 是 | `bb_xxxxxxxxxxxx` |\n| `BROWSERBASE_PROJECT_ID` | Browserbase 项目标识符 | 是 | `proj_xxxxxxxxxxxx` |\n| `GEMINI_API_KEY` | Google Gemini API 密钥，用于 AI 模型调用 | 是 | `AIza...` |\n| `GOOGLE_API_KEY` | Google API 密钥的别名 | 否 | `AIza...` |\n\n资料来源：[src/config.ts:30-32](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n系统会优先使用 `GEMINI_API_KEY`，如果未设置则回退到 `GOOGLE_API_KEY`。这一设计提供了配置的灵活性。\n\n### 命令行参数\n\n命令行参数通过 CLI 界面传递，提供细粒度的运行时控制。`CLIOptions` 类型定义了所有支持的命令行标志：\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\n资料来源：[src/config.ts:8-22](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n---\n\n## 配置数据结构\n\n完整的配置通过 `Config` 类型定义，包含了所有运行时需要的参数：\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `browserbaseApiKey` | `string` | `process.env.BROWSERBASE_API_KEY` | Browserbase API 密钥 |\n| `browserbaseProjectId` | `string` | `process.env.BROWSERBASE_PROJECT_ID` | Browserbase 项目 ID |\n| `proxies` | `boolean` | `false` | 是否启用代理 |\n| `verified` | `boolean` | `false` | 是否启用经验证模式 |\n| `advancedStealth` | `boolean` | `false` | 高级隐身模式（`verified` 的别名） |\n| `contextId` | `string` | `undefined` | 浏览器上下文 ID |\n| `persist` | `boolean` | `false` | 是否持久化会话 |\n| `server.port` | `number \\| undefined` | `undefined` | HTTP 服务器端口 |\n| `server.host` | `string \\| undefined` | `undefined` | HTTP 服务器主机 |\n| `viewPort.browserWidth` | `number` | `1024` | 浏览器窗口宽度 |\n| `viewPort.browserHeight` | `number` | `768` | 浏览器窗口高度 |\n| `modelName` | `string` | `google/gemini-2.5-flash-lite` | AI 模型名称 |\n| `modelApiKey` | `string` | `process.env.GEMINI_API_KEY` | 模型 API 密钥 |\n| `keepAlive` | `boolean` | `false` | 是否保持连接活跃 |\n\n资料来源：[config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n---\n\n## 配置解析流程\n\n配置解析采用链式合并策略，将不同来源的配置参数按照优先级合并成最终的有效配置。\n\n```mermaid\ngraph TD\n A[默认配置 defaultConfig] --> B{mergeConfig}\n C[CLI 配置 cliConfig] --> B\n B --> D[合并配置 mergedConfig]\n D --> E{normalizeVerifiedConfig}\n E --> F[规范化配置 normalizedConfig]\n F --> G{检查 modelApiKey}\n G -->|未设置| H[使用 GEMINI_API_KEY]\n G -->|已设置| I[保持不变]\n H --> J[最终配置 finalConfig]\n I --> J\n```\n\n`resolveConfig` 函数是配置解析的核心入口，负责协调整个合并过程：\n\n```typescript\nexport async function resolveConfig(cliOptions: CLIOptions): Promise {\n const cliConfig = await configFromCLIOptions(cliOptions);\n // 优先级: 默认值 < 文件配置 < CLI 参数\n const mergedConfig = normalizeVerifiedConfig(\n mergeConfig(defaultConfig, cliConfig),\n );\n\n if (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n }\n\n return mergedConfig;\n}\n```\n\n资料来源：[src/config.ts:35-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 配置优先级\n\n配置参数的优先级从低到高排列如下：\n\n1. **默认值** (`defaultConfig`) - 提供最基础的配置值\n2. **环境变量** - 通过 `process.env` 读取\n3. **CLI 参数** (`cliOptions`) - 命令行传入的参数具有最高优先级\n\n这种设计确保了灵活性的同时，用户可以通过命令行快速覆盖任何配置。\n\n---\n\n## 默认配置值\n\n系统预设了一套合理的默认配置值，用户无需修改即可启动服务器：\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `proxies` | `false` | 默认不启用代理 |\n| `viewPort.browserWidth` | `1024` | 默认窗口宽度 1024px |\n| `viewPort.browserHeight` | `768` | 默认窗口高度 768px |\n| `modelName` | `google/gemini-2.5-flash-lite` | 默认使用 Gemini 2.5 Flash Lite |\n\n```typescript\nconst defaultConfig: Config = {\n browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? \"\",\n browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? \"\",\n proxies: false,\n server: {\n port: undefined,\n host: undefined,\n },\n viewPort: {\n browserWidth: 1024,\n browserHeight: 768,\n },\n modelName: \"google/gemini-2.5-flash-lite\",\n};\n```\n\n资料来源：[src/config.ts:24-36](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n---\n\n## 命令行标志详解\n\n### 代理与安全\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--proxies` | `boolean` | 启用代理支持 |\n| `--verified` | `boolean` | 启用经验证的浏览器模式 |\n| `--advancedStealth` | `boolean` | 高级隐身模式（`--verified` 的别名） |\n\n资料来源：[src/config.ts:8-10](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 会话管理\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--contextId` | `string` | 指定浏览器上下文 ID |\n| `--persist` | `boolean` | 启用会话持久化 |\n| `--keepAlive` | `boolean` | 保持连接活跃 |\n\n### 服务器配置\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--port` | `number` | HTTP 服务器监听端口 |\n| `--host` | `string` | HTTP 服务器监听主机 |\n\n### 浏览器视图\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--browserWidth` | `number` | 浏览器窗口宽度（像素） |\n| `--browserHeight` | `number` | 浏览器窗口高度（像素） |\n\n### 模型配置\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--modelName` | `string` | AI 模型名称（如需使用不同模型必须指定） |\n| `--modelApiKey` | `string` | AI 模型 API 密钥 |\n\n> **注意**：如果需要使用不同的模型，必须通过 `--modelName` 参数指定，并在环境变量或参数中提供对应的 API 密钥。\n\n---\n\n## 配置示例\n\n### 环境变量配置\n\n```bash\nexport BROWSERBASE_API_KEY=\"bb_your_api_key_here\"\nexport BROWSERBASE_PROJECT_ID=\"proj_your_project_id_here\"\nexport GEMINI_API_KEY=\"your_gemini_key_here\"\n```\n\n### Docker 部署配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### NPM 部署配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### 自定义视图端口配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-server-browserbase/cli.js\",\n \"--browserWidth\",\n \"1920\",\n \"--browserHeight\",\n \"1080\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n---\n\n## verified 与 advancedStealth 兼容性\n\n系统维护了向后兼容性，`advancedStealth` 参数作为 `verified` 的别名存在。配置规范化函数会处理这种映射关系：\n\n```typescript\nexport function normalizeVerifiedConfig(config: Config): Config {\n // 如果设置了 advancedStealth 但未设置 verified，则将 verified 设置为 true\n if (config.advancedStealth && !config.verified) {\n return { ...config, verified: true };\n }\n return config;\n}\n```\n\n资料来源：[src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n当同时设置 `verified` 和 `advancedStealth` 时，`verified` 的值优先：\n\n| verified | advancedStealth | 最终 verified 值 |\n|----------|-----------------|------------------|\n| `true` | `true` | `true` |\n| `false` | `true` | `false` |\n| `undefined` | `true` | `true` |\n\n---\n\n## 相关命令脚本\n\n项目在 `package.json` 中定义了与配置相关的构建和测试脚本：\n\n| 脚本命令 | 说明 |\n|---------|------|\n| `pnpm build` | 编译 TypeScript 代码并设置执行权限 |\n| `pnpm prepare` | 准备阶段：运行 husky 和构建 |\n| `pnpm inspect` | 使用 MCP inspector 检查服务器 |\n| `pnpm test` | 运行单元测试 |\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsc && shx chmod +x dist/*.js\",\n \"prepare\": \"husky && pnpm build\",\n \"inspector\": \"npx @modelcontextprotocol/inspector build/index.js\",\n \"test\": \"vitest run\"\n }\n}\n```\n\n资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [配置参数](#page-configuration), [MCP 客户端集成](#page-mcp-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [cli.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/cli.js)\n \n\n# 部署指南\n\n本页面详细说明如何部署和配置 Browserbase MCP 服务器。该服务器基于 Model Context Protocol (MCP) 构建，通过 Browserbase 和 Stagehand 实现 AI 网页自动化功能。\n\n## 部署架构概览\n\nBrowserbase MCP 服务器支持两种主要的运行时部署模式：\n\n```mermaid\ngraph TD\n A[用户 MCP 客户端] --> B{传输协议选择}\n B -->|SHTTP| C[Browserbase 托管服务
https://mcp.browserbase.com/mcp]\n B -->|STDIO| D[本地 MCP 服务器]\n C --> E[Gemini 模型]\n D --> F[Browserbase Cloud]\n D --> G[本地浏览器]\n F --> H[Stagehand 引擎]\n G --> H\n```\n\n## 前提条件\n\n| 要求 | 说明 |\n|------|------|\n| Node.js | 版本 18.x 或更高 |\n| Docker | 仅在使用 Docker 部署时需要 |\n| Browserbase 账户 | 用于获取 API Key 和 Project ID |\n| Gemini API Key | 用于 AI 模型调用 |\n\n## 安装方式\n\n### 方式一：直接安装\n\n通过 Git 克隆源码后自行编译：\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\n编译完成后，CLI 入口文件位于 `cli.js`，可通过以下命令验证：\n\n```bash\nnode cli.js --version\n```\n\n资料来源：[README.md:1-12]()\n\n### 方式二：使用 NPM 包\n\n通过 npx 直接运行官方发布的 NPM 包：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:65-77]()\n\n### 方式三：Docker 部署\n\n使用 Docker 构建自定义镜像：\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\nDocker 部署特别适合隔离环境依赖，或在不支持 Node.js 的系统上运行。\n\n资料来源：[README.md:8-11]()\n\n## 环境变量配置\n\nMCP 服务器运行时需要以下环境变量：\n\n| 环境变量 | 必填 | 说明 |\n|---------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目标识符 |\n| `GEMINI_API_KEY` | 条件必填 | Gemini 模型 API 密钥（当 `modelApiKey` 未设置时使用） |\n| `GOOGLE_API_KEY` | 条件必填 | 备用 Gemini API 密钥 |\n\n服务器启动时会优先使用 `modelApiKey` 配置参数，其次回退到 `GEMINI_API_KEY`，最后使用 `GOOGLE_API_KEY`。\n\n资料来源：[src/config.ts:30-35]()\n\n## 命令行配置选项\n\n服务器支持丰富的命令行参数配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--browserbaseApiKey` | string | 环境变量 | Browserbase API 密钥 |\n| `--browserbaseProjectId` | string | 环境变量 | Browserbase 项目 ID |\n| `--proxies` | boolean | false | 启用 Browserbase 代理 |\n| `--verified` | boolean | false | 启用 Browserbase 验证身份（仅限 Scale 计划用户） |\n| `--advancedStealth` | boolean | false | 已弃用，与 `--verified` 等效 |\n| `--contextId` | string | - | Browserbase 上下文 ID |\n| `--persist` | boolean | false | 持久化会话 |\n| `--port` | number | - | HTTP 传输监听端口 |\n| `--host` | string | - | HTTP 传输监听主机 |\n| `--browserWidth` | number | 1024 | 浏览器视口宽度 |\n| `--browserHeight` | number | 768 | 浏览器视口高度 |\n| `--modelName` | string | google/gemini-2.5-flash-lite | 使用的 AI 模型名称 |\n| `--modelApiKey` | string | - | 模型 API 密钥 |\n| `--keepAlive` | boolean | - | 保持连接活跃 |\n| `--experimental` | boolean | false | 启用实验性功能 |\n\n资料来源：[src/config.ts:7-24]()\n\n## 传输协议配置\n\n### STDIO 传输模式\n\nSTDIO 是本地进程间通信的标准方式，适合桌面 MCP 客户端（如 Claude Desktop、Cursor）。\n\n#### 直接安装配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### Docker 配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:18-60]()\n\n### SHTTP 传输模式\n\nSHTTP (Streamable HTTP) 是现代化的传输协议，支持服务端推送和流式响应。\n\n#### 托管服务（推荐）\n\nBrowserbase 提供托管 MCP 服务器，无需本地运行：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n如果客户端不支持原生 SHTTP，可使用 `mcp-remote` 代理：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:82-102]()\n\n#### 自托管 HTTP 服务\n\n使用 `--port` 和 `--host` 参数启动自托管 HTTP 服务器：\n\n```bash\nnode cli.js --port 8080 --host 0.0.0.0\n```\n\n服务器启动后会输出配置信息：\n\n```\nListening on http://localhost:8080\nPut this in your client config:\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:8080/mcp\"\n }\n }\n}\nIf your client supports streamable HTTP, you can use the /mcp endpoint instead.\n```\n\n资料来源：[src/transport.ts:1-45]()\n\n## 部署拓扑图\n\n```mermaid\ngraph LR\n subgraph \"客户端层\"\n A[MCP 客户端]\n end\n \n subgraph \"传输层\"\n B[STDIO]\n C[HTTP/SHTTP]\n end\n \n subgraph \"服务层\"\n D[本地部署]\n E[托管服务
mcp.browserbase.com]\n end\n \n subgraph \"后端服务\"\n F[Browserbase Cloud]\n G[Gemini API]\n end\n \n A --> B\n A --> C\n B --> D\n C --> D\n C --> E\n D --> F\n D --> G\n E --> F\n E --> G\n```\n\n## 完整配置示例\n\n### 完整 STDIO 配置（本地部署）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\n \"/usr/local/bin/mcp-server-browserbase/cli.js\",\n \"--modelName\",\n \"google/gemini-2.5-flash-lite\",\n \"--browserWidth\",\n \"1920\",\n \"--browserHeight\",\n \"1080\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key-here\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id-here\",\n \"GEMINI_API_KEY\": \"your-gemini-key-here\"\n }\n }\n }\n}\n```\n\n### 使用代理的配置\n\n```bash\nnode cli.js --proxies --verified\n```\n\n### 自定义模型配置\n\n如需使用不同的 AI 模型，添加 `--modelName` 参数并提供相应的 API 密钥：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-3-5-sonnet\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"MODEL_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[src/config.ts:22]()\n\n## 部署验证\n\n部署完成后，可通过以下方式验证：\n\n1. **CLI 版本检查**：运行 `node cli.js --version`\n2. **MCP Inspector**：使用官方检查器测试工具连接\n ```bash\n npm run inspector\n ```\n3. **功能测试**：使用 MCP 客户端发送测试请求到服务器\n\n资料来源：[package.json:34]()\n\n## 常见部署问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 连接超时 | 检查防火墙设置，确保端口可访问 |\n| API Key 无效 | 验证 Browserbase 和 Gemini 密钥是否正确 |\n| 浏览器启动失败 | 检查系统是否安装 Chromium，Docker 模式下确保沙箱配置正确 |\n| 会话不稳定 | 添加 `--keepAlive` 参数保持连接 |\n\n## 版本信息\n\n当前稳定版本为 **3.0.0**，主要变化包括：\n\n- 工具名称与托管服务对齐\n- 默认模型更新为 `google/gemini-2.5-flash-lite`\n- 移除 Smithery 相关依赖\n\n资料来源：[package.json:3-4]()\n\n---\n\n\n\n## MCP 客户端集成\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment), [工具集概述](#page-tools-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n- [src/mcp/resources.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# MCP 客户端集成\n\n## 概述\n\nMCP 客户端集成是指将 Browserbase MCP 服务器与支持 Model Context Protocol 的客户端应用（如 Claude Desktop、Cursor、Cody 等）进行连接的配置过程。该服务器基于 `@modelcontextprotocol/sdk` 构建，提供浏览器自动化能力，允许 AI 助手通过自然语言控制浏览器执行网页导航、元素交互和数据提取等操作。\n\n资料来源：[src/index.ts:1-25]()\n\n## 架构设计\n\n### 服务器层级结构\n\n```mermaid\ngraph TD\n A[MCP 客户端
Claude Desktop / Cursor] --> B[MCP Server
McpServer 实例]\n B --> C[Context 上下文
会话管理器]\n C --> D[SessionManager
浏览器会话管理]\n D --> E[Stagehand 实例
浏览器自动化]\n F[Tools 工具集
start/navigate/act/observe/extract] --> B\n```\n\nBrowserbase MCP 服务器采用分层架构设计：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 协议层 | `McpServer` | 处理 MCP 协议通信，注册工具和资源 |\n| 业务层 | `Context` | 执行工具逻辑，管理工具生命周期 |\n| 会话层 | `SessionManager` | 管理多个浏览器会话，验证会话状态 |\n| 自动化层 | `Stagehand` | 基于 Playwright 的浏览器自动化执行 |\n\n资料来源：[src/server.ts:3-27]()[src/context.ts:1-50]()\n\n### 工具注册机制\n\n服务器启动时，所有工具通过统一接口注册到 MCP 协议层：\n\n```typescript\n// 伪代码展示工具注册流程\ntools.forEach((tool) => {\n server.tool(\n tool.schema.name, // 工具名称\n tool.schema.description, // 工具描述\n tool.schema.inputSchema.shape, // 输入参数 schema\n async (params) => {\n const result = await context.run(tool, params);\n return result;\n }\n );\n});\n```\n\n资料来源：[src/index.ts:45-70]()\n\n## 支持的传输方式\n\n### 传输方式对比\n\n| 传输方式 | 说明 | 推荐场景 | 配置复杂度 |\n|----------|------|----------|------------|\n| **STDI O** | 标准输入输出流 | 本地运行、自托管 | 低 |\n| **SHTTP** | Server-Sent HTTP | 托管服务、远程访问 | 中 |\n| **Docker** | 容器化部署 | 生产环境隔离 | 中 |\n\n资料来源：[README.md:1-80]()\n\n### STDIO 传输配置\n\nSTDIO 传输适用于本地部署场景，服务器通过标准输入输出与客户端通信。\n\n**NPM 方式（推荐）**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**本地构建方式**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:30-60]()\n\n### SHTTP 传输配置\n\nSHTTP（Server-Sent HTTP）传输允许客户端通过 HTTP 协议连接到托管的 MCP 服务器：\n\n**支持 SHTTP 的客户端**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n**不支持 SHTTP 的客户端**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:62-85]()\n\n### Docker 部署配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:18-28]()\n\n## 配置参数详解\n\n### 环境变量\n\n| 环境变量 | 必需 | 说明 |\n|----------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目标识符 |\n| `GEMINI_API_KEY` | 是 | Google Gemini 模型 API 密钥（用于 AI 驱动的浏览器自动化） |\n| `GOOGLE_API_KEY` | 否 | Google API 密钥备选（当 GEMINI_API_KEY 未设置时使用） |\n\n资料来源：[src/config.ts:40-55]()\n\n### 命令行参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--browserbaseApiKey` | string | Browserbase API 密钥 |\n| `--browserbaseProjectId` | string | Browserbase 项目 ID |\n| `--proxies` | boolean | 启用 Browserbase 代理 |\n| `--verified` | boolean | 使用 Browserbase 验证身份（仅 Scale 计划可用） |\n| `--advancedStealth` | boolean | 已废弃，等同于 `--verified` |\n| `--contextId` | string | 指定 Browserbase 上下文 ID |\n| `--keepAlive` | boolean | 保持浏览器会话活跃 |\n| `--modelName` | string | 使用的 AI 模型名称（默认：`google/gemini-2.5-flash-lite`） |\n| `--modelApiKey` | string | 模型 API 密钥 |\n\n资料来源：[src/program.ts:28-50]()\n\n### 默认配置\n\n```typescript\nconst defaultConfig: Config = {\n browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? \"\",\n browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? \"\",\n proxies: false,\n server: {\n port: undefined,\n host: undefined,\n },\n viewPort: {\n browserWidth: 1024,\n browserHeight: 768,\n },\n modelName: \"google/gemini-2.5-flash-lite\",\n};\n```\n\n资料来源：[src/config.ts:28-40]()\n\n## 资源与模板\n\n### 资源注册\n\nMCP 协议支持资源管理功能，Browserbase MCP 服务器当前提供了空的资源集合：\n\n```typescript\nexport const RESOURCES = [];\nexport const RESOURCE_TEMPLATES = [];\n\nexport function listResources() {\n return { resources: [] };\n}\n\nexport function listResourceTemplates() {\n return { resourceTemplates: [] };\n}\n\nexport function readResource(uri: string) {\n return { contents: [{ uri, text: `Resource not found: ${uri}` }] };\n}\n```\n\n资料来源：[src/mcp/resources.ts:1-20]()\n\n服务器通过 MCP 协议注册了资源处理器：\n\n```typescript\nserver.server.setRequestHandler(ListResourcesRequestSchema, async () => {\n return listResources();\n});\n\nserver.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {\n return { resourceTemplates: RESOURCE_TEMPLATES };\n});\n\nserver.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {\n return readResource(request.params.uri);\n});\n```\n\n资料来源：[src/index.ts:30-45]()\n\n## 工具能力\n\n### 核心工具集\n\n| 工具名称 | 功能 | 输入参数 |\n|----------|------|----------|\n| `start` | 创建新的浏览器会话 | _(无)_ |\n| `end` | 关闭当前浏览器会话 | _(无)_ |\n| `navigate` | 导航到指定 URL | `{ url: string }` |\n| `act` | 执行页面操作 | `{ action: string }` |\n| `observe` | 观察页面可交互元素 | `{ instruction: string }` |\n| `extract` | 从页面提取数据 | `{ instruction?: string }` |\n\n资料来源：[README.md:1-15]()[src/tools/extract.ts:1-55]()\n\n### 工具定义结构\n\n```typescript\nexport type Tool = {\n capability: string; // 能力分类：core\n schema: ToolSchema;\n handle: (context: Context, params: z.output) => Promise;\n};\n\nexport type ToolResult = {\n action?: () => Promise;\n waitForNetwork: boolean;\n};\n```\n\n资料来源：[src/tools/tool.ts:18-30]()\n\n## 服务器生命周期\n\n### 服务端点\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as McpServer\n participant Context as Context\n participant SessionManager as SessionManager\n participant Stagehand as Stagehand\n\n Client->>Server: 初始化连接\n Server->>Context: 创建上下文\n Context->>SessionManager: 初始化会话管理器\n Server->>Server: 注册工具处理器\n Server->>Server: 注册资源处理器\n \n Client->>Server: 工具调用 (tool/Call)\n Server->>Context: 执行工具 (context.run)\n Context->>SessionManager: 获取/创建会话\n SessionManager->>Stagehand: 操作浏览器\n Stagehand-->>SessionManager: 执行结果\n SessionManager-->>Context: 工具结果\n Context-->>Server: MCP 响应\n Server-->>Client: 返回结果\n\n Client->>Server: 关闭连接\n Server->>SessionManager: 关闭所有会话\n Server->>Server: 清理资源\n```\n\n### 服务器管理\n\n```typescript\nexport class ServerList {\n private _servers: Server[] = [];\n private _serverFactory: () => Promise;\n\n async create() {\n const server = await this._serverFactory();\n this._servers.push(server);\n return server;\n }\n\n async close(server: Server) {\n await server.close();\n const index = this._servers.indexOf(server);\n if (index !== -1) this._servers.splice(index, 1);\n }\n\n async closeAll() {\n await Promise.all(this._servers.map((server) => server.close()));\n }\n}\n```\n\n资料来源：[src/server.ts:3-27]()\n\n## 错误处理\n\n### 工具执行错误\n\n当工具执行失败时，错误信息通过 MCP 协议返回：\n\n```typescript\ntry {\n const result = await context.run(tool, params);\n return result;\n} catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n process.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`,\n );\n throw new Error(`Failed to run tool '${tool.schema.name}': ${errorMessage}`);\n}\n```\n\n资料来源：[src/index.ts:62-73]()\n\n### 会话验证错误\n\n会话管理器会自动检测失效会话并触发重建：\n\n```typescript\ntry {\n const pages = this.defaultBrowserSession.stagehand.context.pages();\n if (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n }\n} catch {\n needsReCreation = true;\n // 关闭并重建会话\n await this.closeBrowserGracefully(this.defaultBrowserSession, sessionId);\n this.defaultBrowserSession = null;\n}\n```\n\n资料来源：[src/sessionManager.ts:80-105]()\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\n### 2. 配置环境变量\n\n创建 `.env` 文件：\n\n```bash\nBROWSERBASE_API_KEY=your_api_key\nBROWSERBASE_PROJECT_ID=your_project_id\nGEMINI_API_KEY=your_gemini_key\n```\n\n### 3. 配置客户端\n\n根据使用的客户端，将以下配置添加到 MCP 配置文件中：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your_api_key\",\n \"BROWSERBASE_PROJECT_ID\": \"your_project_id\",\n \"GEMINI_API_KEY\": \"your_gemini_key\"\n }\n }\n }\n}\n```\n\n### 4. 重启客户端\n\n重新加载 MCP 客户端以应用配置变更。\n\n## 版本兼容性\n\n### 3.0.0 重大变更\n\n版本 3.0.0 带来了以下破坏性变更，以与托管服务对齐：\n\n| 旧名称 | 新名称 |\n|--------|--------|\n| `browserbase_session_create` | `start` |\n| `browserbase_session_close` | `end` |\n| `browserbase_stagehand_navigate` | `navigate` |\n| `browserbase_stagehand_act` | `act` |\n| `browserbase_stagehand_observe` | `observe` |\n| `browserbase_stagehand_extract` | `extract` |\n\n默认模型已从 `gemini-2.0-flash` 更改为 `google/gemini-2.5-flash-lite`。\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 相关文档\n\n- [Browserbase MCP 官方文档](https://docs.browserbase.com/integrations/mcp/introduction)\n- [Model Context Protocol 规范](https://modelcontextprotocol.io/docs/concepts/resources)\n- [Stagehand 浏览器自动化](https://www.stagehand.dev)\n\n---\n\n\n\n## 模型配置\n\n### 相关页面\n\n相关主题：[配置参数](#page-configuration), [工具集概述](#page-tools-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# 模型配置\n\n## 概述\n\n模型配置是 Browserbase MCP Server 的核心功能之一，用于控制浏览器自动化操作所使用的 AI 模型。该配置通过 [Stagehand](https://www.stagehand.dev) 框架实现网页自动化操作，包括页面导航（navigate）、元素操作（act）、页面观察（observe）和数据提取（extract）。\n\n默认情况下，服务器使用 Google 的 Gemini 2.5 Flash Lite 模型，该模型在 Stagehand 的自动化评估中表现优异。用户也可以配置其他支持的模型（如 GPT-4o、Claude 等）来满足特定需求。\n\n资料来源：[README.md:1-50]()\n\n## 配置架构\n\nMCP Server 的模型配置遵循以下层次结构：\n\n```mermaid\ngraph TD\n A[默认配置] --> B[环境变量]\n B --> C[CLI 参数]\n C --> D[最终配置]\n \n A1[\"defaultConfig
modelName: google/gemini-2.5-flash-lite\"] --> A\n B1[\"GEMINI_API_KEY
GOOGLE_API_KEY\"] --> B\n C1[\"--modelName
--modelApiKey\"] --> C\n```\n\n配置优先级顺序为：**默认值 < 环境变量 < CLI 参数**\n\n资料来源：[src/config.ts:1-30]()\n\n## 配置参数详解\n\n### 主要配置项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `modelName` | string | `google/gemini-2.5-flash-lite` | 使用的 AI 模型标识符 |\n| `modelApiKey` | string | 环境变量 | 自定义模型的 API 密钥 |\n| `experimental` | boolean | `false` | 是否启用实验性功能 |\n\n资料来源：[src/index.ts:1-50]()\n\n### CLI 选项定义\n\n```typescript\nmodelName: z\n .string()\n .optional()\n .describe(\n \"The model to use for Stagehand (default: google/gemini-2.5-flash-lite)\",\n ),\nmodelApiKey: z\n .string()\n .optional()\n .describe(\n \"API key for the custom model provider. Required when using a model other than the default google/gemini-2.5-flash-lite\",\n ),\n```\n\n资料来源：[src/index.ts:50-65]()\n\n## 配置验证机制\n\n服务器实现了严格的配置验证逻辑，确保在使用非默认模型时必须提供相应的 API 密钥。\n\n```mermaid\ngraph TD\n A[配置输入] --> B{modelName 是否为默认值?}\n B -->|是| C[无需 API Key]\n B -->|否| D{modelApiKey 是否存在且有效?}\n D -->|是| E[验证通过]\n D -->|否| F[抛出验证错误]\n \n F --> F1[\"modelApiKey is required
when specifying a custom model\"]\n```\n\n### 验证规则\n\n服务器使用 Zod schema 进行配置验证，核心验证逻辑如下：\n\n```typescript\n.refine(\n (data) => {\n // 如果指定了非默认模型，API 密钥是必需的\n if (data.modelName && data.modelName !== \"google/gemini-2.5-flash-lite\") {\n return (\n data.modelApiKey !== undefined &&\n typeof data.modelApiKey === \"string\" &&\n data.modelApiKey.length > 0\n );\n }\n return true;\n },\n {\n message: \"modelApiKey is required when specifying a custom model\",\n path: [\"modelApiKey\"],\n },\n);\n```\n\n资料来源：[src/index.ts:65-85]()\n\n## 环境变量配置\n\n### 优先级顺序\n\n系统按以下顺序查找 API 密钥：\n\n| 优先级 | 环境变量名 | 说明 |\n|--------|------------|------|\n| 1 | `modelApiKey` (CLI) | 通过命令行直接指定 |\n| 2 | `GEMINI_API_KEY` | Gemini 专用环境变量 |\n| 3 | `GOOGLE_API_KEY` | Google 通用 API 密钥 |\n\n```typescript\n// --- Add Browserbase Env Vars ---\nif (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n}\n```\n\n资料来源：[src/config.ts:45-50]()\n\n## 配置示例\n\n### 使用默认模型\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\n### 使用自定义模型（Claude）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4-5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:80-100]()\n\n## 支持的模型\n\n根据 Stagehand 的支持列表，用户可以使用以下类型的模型：\n\n| 模型类别 | 示例模型 | 提供商 |\n|----------|----------|--------|\n| Gemini 系列 | `google/gemini-2.5-flash-lite` | Google |\n| Claude 系列 | `anthropic/claude-sonnet-4-5` | Anthropic |\n| GPT 系列 | `openai/gpt-4o` | OpenAI |\n\n> **注意**：自定义模型必须在 Stagehand 支持的模型列表中，具体支持情况请参阅 [Stagehand 文档](https://docs.stagehand.dev/examples/custom_llms#supported-llms)。\n\n资料来源：[README.md:95-100]()\n\n## 完整配置流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as MCP Server\n participant C as Config 模块\n participant S as SessionManager\n participant SB as Stagehand\n\n U->>M: 启动服务器 (带模型配置)\n M->>C: resolveConfig(cliOptions)\n C->>C: 合并默认配置\n C->>C: 加载环境变量\n C->>C: 应用 CLI 参数\n C-->>M: 返回最终 Config\n M->>S: 创建会话 (config)\n S->>SB: 初始化 Stagehand\n SB->>SB: 使用配置的 modelName\n \n alt 非默认模型\n C->>C: 验证 modelApiKey 存在\n C-->>M: 验证通过或抛出错误\n end\n```\n\n## 配置代码参考\n\n### 默认配置对象\n\n```typescript\nconst defaultConfig: Config = {\n browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? \"\",\n browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? \"\",\n proxies: false,\n server: {\n port: undefined,\n host: undefined,\n },\n viewPort: {\n browserWidth: 1024,\n browserHeight: 768,\n },\n modelName: \"google/gemini-2.5-flash-lite\", // 默认模型\n};\n```\n\n资料来源：[src/config.ts:20-35]()\n\n### CLI 选项类型定义\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string; // 模型名称\n modelApiKey?: string; // 模型 API 密钥\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\n资料来源：[src/config.ts:1-25]()\n\n## 依赖关系\n\n模型配置功能的实现依赖于以下核心包：\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `@browserbasehq/stagehand` | ^3.3.0 | 浏览器自动化核心框架 |\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP 协议实现 |\n| `zod` | ^3.25.67 | 配置验证 |\n| `commander` | ^14.0.0 | CLI 参数解析 |\n\n资料来源：[package.json:1-30]()\n\n## 常见问题\n\n### 1. 模型配置验证失败\n\n**问题**：使用自定义模型时收到 \"modelApiKey is required\" 错误。\n\n**解决方案**：确保在使用非默认模型时，通过 `--modelApiKey` 参数或 `GEMINI_API_KEY` 环境变量提供了有效的 API 密钥。\n\n### 2. 模型不支持\n\n**问题**：配置的模型在 Stagehand 中不被支持。\n\n**解决方案**：请查阅 [Stagehand 支持的模型列表](https://docs.stagehand.dev/examples/custom_llms#supported-llms)，选择支持的模型。\n\n### 3. API 密钥优先级\n\n**问题**：不确定哪个环境变量会被使用。\n\n**优先级**：`--modelApiKey` > `GEMINI_API_KEY` > `GOOGLE_API_KEY`\n\n## 版本变更记录\n\n| 版本 | 变更内容 |\n|------|----------|\n| 3.0.0 | 默认模型从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`，工具名称与托管服务对齐 |\n| 2.4.0 | 新增 stagehand agent 工具支持 |\n| 2.3.0 | 初始阶段hand集成 |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：browserbase/mcp-server-browserbase\n\n摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives。\n\n## 1. 安全/权限坑 · 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令: `npx @browserbasehq/mcp`\n- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n\n## 3. 安装坑 · 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：Add MCPpedia security badge to README\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安全/权限坑 · 来源证据：Add policy enforcement for cloud browser sessions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown\n\n\n",
"markdown_key": "mcp-server-browserbase",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:899184149",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/browserbase/mcp-server-browserbase"
},
{
"evidence_id": "art_889d6bbaa27a4978989c3e2408bad577",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/browserbase/mcp-server-browserbase#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mcp-server-browserbase 说明书",
"toc": [
"https://github.com/browserbase/mcp-server-browserbase 项目说明书",
"目录",
"项目介绍",
"1 项目概述",
"2 核心功能",
"3 技术架构",
"4 依赖关系",
"5 部署方式",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "1e196b3d3c4dc70944e0d19038dd9eb3608b207a",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"Dockerfile",
"package.json",
"README.md",
"src/index.ts",
"src/config.ts",
"src/server.ts",
"src/program.ts",
"src/config.test.ts",
"src/transport.ts",
"src/sessionManager.ts",
"src/context.ts",
"src/mcp/sampling.ts",
"src/mcp/resources.ts",
"src/tools/navigate.ts",
"src/tools/observe.ts",
"src/tools/index.ts",
"src/tools/act.ts",
"src/tools/extract.ts",
"src/tools/session.ts",
"src/tools/tool.ts",
"src/types/types.ts",
"src/tools/__tests__/tools.test.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @browserbasehq/mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @browserbasehq/mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `git clone https://github.com/browserbase/mcp-server-browserbase.git` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npm install && npm run build` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `evals/mcp-eval-basic.config.json`, `evals/mcp-eval-minimal.config.json`, `evals/mcp-eval.config.json` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：50\n- 重要文件覆盖：36/50\n- 证据索引条目：35\n- 角色 / Skill 条目：4\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @browserbasehq/mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @browserbasehq/mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @browserbasehq/mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 4 个角色 / Skill / 项目文档条目。\n\n- **Changesets**（project_doc）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **Browserbase MCP Server**（project_doc）：The Model Context Protocol MCP https://modelcontextprotocol.io/introduction is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Rename Advanced Stealth To Verified**（project_doc）：Add verified as the canonical Browserbase Verified Identity setting while preserving advancedStealth as a deprecated alias. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/rename-advanced-stealth-to-verified.md`\n- **@browserbasehq/mcp**（project_doc）：- 8f0b070: Align tool names and schemas with the hosted Browserbase MCP server at mcp.browserbase.com. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n\n## 证据索引\n\n- 共索引 35 条证据。\n\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`.changeset/README.md`\n- **Browserbase MCP Server**（documentation）：The Model Context Protocol MCP https://modelcontextprotocol.io/introduction is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need. 证据：`README.md`\n- **Package**（package_manifest）：{ \"name\": \"@browserbasehq/mcp\", \"version\": \"3.0.0\", \"description\": \"MCP server for AI web browser automation using Browserbase and Stagehand\", \"mcpName\": \"io.github.browserbase/mcp-server-browserbase\", \"license\": \"Apache-2.0\", \"author\": \"Browserbase, Inc. https://www.browserbase.com/ \", \"homepage\": \"https://www.browserbase.com\", \"bugs\": \"https://github.com/browserbase/mcp-server-browserbase/issues\", \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/browserbase/mcp-server-browserbase\" }, \"type\": \"module\", \"main\": \"./cli.js\", \"module\": \"./src/index.ts\", \"bin\": { \"mcp-server-browserbase\": \"cli.js\" }, \"files\": \"assets\", \"README.md\", \"dist\", \"cli.js\", \"index.d.ts\", \"index.js\", \"config.d.… 证据：`package.json`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Rename Advanced Stealth To Verified**（documentation）：Add verified as the canonical Browserbase Verified Identity setting while preserving advancedStealth as a deprecated alias. 证据：`.changeset/rename-advanced-stealth-to-verified.md`\n- **@browserbasehq/mcp**（documentation）：- 8f0b070: Align tool names and schemas with the hosted Browserbase MCP server at mcp.browserbase.com. 证据：`CHANGELOG.md`\n- **Config**（structured_config）：{ \"$schema\": \"https://unpkg.com/@changesets/config@3.1.1/schema.json\", \"changelog\": \"@changesets/cli/changelog\", \"commit\": false, \"fixed\": , \"linked\": , \"access\": \"public\", \"baseBranch\": \"main\", \"updateInternalDependencies\": \"patch\", \"ignore\": } 证据：`.changeset/config.json`\n- **Mcp Eval Basic.Config**（structured_config）：{ \"passThreshold\": 0.7, \"server\": { \"transport\": \"stdio\", \"command\": \"node\", \"args\": \"./cli.js\" , \"env\": { \"BROWSERBASE API KEY\": \"${BROWSERBASE API KEY}\", \"BROWSERBASE PROJECT ID\": \"${BROWSERBASE PROJECT ID}\", \"GEMINI API KEY\": \"${GEMINI API KEY}\" } }, \"timeout\": 180000, \"llmJudge\": false, \"workflows\": { \"name\": \"basic-navigation-test\", \"description\": \"Test basic browser navigation functionality\", \"steps\": { \"user\": \"Create a browser session, navigate to https://example.com, and close the session\", \"expectedState\": \"success\" } , \"expectTools\": \"start\", \"navigate\", \"end\" }, { \"name\": \"search-and-extract-test\", \"description\": \"Test navigation, search interaction, and data extraction\", \"steps… 证据：`evals/mcp-eval-basic.config.json`\n- **Mcp Eval Minimal.Config**（structured_config）：{ \"passThreshold\": 0.7, \"server\": { \"transport\": \"stdio\", \"command\": \"node\", \"args\": \"./cli.js\" , \"env\": { \"BROWSERBASE API KEY\": \"${BROWSERBASE API KEY}\", \"BROWSERBASE PROJECT ID\": \"${BROWSERBASE PROJECT ID}\", \"GEMINI API KEY\": \"${GEMINI API KEY}\" } }, \"timeout\": 60000, \"llmJudge\": false, \"workflows\": { \"name\": \"smoke-test-navigation\", \"description\": \"Quick test to verify basic navigation works\", \"steps\": { \"user\": \"Open a browser and go to example.org\", \"expectedState\": \"success\" }, { \"user\": \"Close the browser\", \"expectedState\": \"success\" } , \"expectTools\": \"start\", \"navigate\", \"end\" }, { \"name\": \"smoke-test-extraction\", \"description\": \"Quick test to verify data extraction works\", \"steps… 证据：`evals/mcp-eval-minimal.config.json`\n- **Mcp Eval.Config**（structured_config）：{ \"passThreshold\": 0.7, \"server\": { \"transport\": \"stdio\", \"command\": \"node\", \"args\": \"./cli.js\" , \"env\": { \"BROWSERBASE API KEY\": \"${BROWSERBASE API KEY}\", \"BROWSERBASE PROJECT ID\": \"${BROWSERBASE PROJECT ID}\", \"GEMINI API KEY\": \"${GEMINI API KEY}\" } }, \"timeout\": 180000, \"llmJudge\": false, \"workflows\": { \"name\": \"basic-navigation-test\", \"description\": \"Test basic browser navigation functionality\", \"steps\": { \"user\": \"Create a browser session, navigate to https://example.com, and close the session\", \"expectedState\": \"success\" } , \"expectTools\": \"start\", \"navigate\", \"end\" }, { \"name\": \"search-and-extract-test\", \"description\": \"Test navigation, search interaction, and data extraction\", \"steps… 证据：`evals/mcp-eval.config.json`\n- **Gemini Extension**（structured_config）：{ \"name\": \"mcp-server-browserbase\", \"version\": \"2.4.1\", \"mcpServers\": { \"mcp-server-browserbase\": { \"command\": \"npx\", \"args\": \"@browserbasehq/mcp\" } } } 证据：`gemini-extension.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json\", \"name\": \"io.github.browserbase/mcp-server-browserbase\", \"description\": \"MCP server for AI web browser automation using Browserbase and Stagehand\", \"status\": \"active\", \"repository\": { \"url\": \"https://github.com/browserbase/mcp-server-browserbase\", \"source\": \"github\" }, \"version\": \"2.2.0\", \"packages\": { \"registry type\": \"npm\", \"registry base url\": \"https://registry.npmjs.org\", \"identifier\": \"@browserbasehq/mcp\", \"version\": \"2.2.0\", \"transport\": { \"type\": \"stdio\" }, \"environment variables\": { \"description\": \"Your Browserbase API key\", \"is required\": true, \"format\": \"string\", \"is secret\": true, \"name\":… 证据：`server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"ESNext\", \"moduleResolution\": \"bundler\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"outDir\": \"dist\", \"rootDir\": \"src\", \"noErrorTruncation\": false }, \"include\": \"src/ / .ts\" , \"exclude\": \"node modules\" } 证据：`tsconfig.json`\n- **Dependencies**（source_file）：Documentation .md !README.md assets/ 证据：`.dockerignore`\n- **.gitattributes**（source_file）：package-lock.json linguist-generated=true 证据：`.gitattributes`\n- **Logs**（source_file）：Logs logs .log npm-debug.log yarn-debug.log yarn-error.log lerna-debug.log .pnpm-debug.log 证据：`.gitignore`\n- **!/bin/sh**（source_file）：!/bin/sh pnpm install pnpm build pnpm pre-commit 证据：`.husky/pre-commit`\n- **Use npm for package management**（source_file）：Use npm for package management engine-strict=true 证据：`.npmrc`\n- **Dockerfile**（source_file）：COPY package.json pnpm-lock.yaml ./ RUN --mount=type=cache,id=pnpm,target=/pnpm/store \\ pnpm install --frozen-lockfile --ignore-scripts 证据：`Dockerfile`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node import \"./dist/program.js\"; 证据：`cli.js`\n- **Config.D**（source_file）：import type { AvailableModelSchema } from \"@browserbasehq/stagehand\"; 证据：`config.d.ts`\n- **Eslint.Config**（source_file）：import js from \"@eslint/js\"; import globals from \"globals\"; import tseslint from \"typescript-eslint\"; import { defineConfig } from \"eslint/config\"; 证据：`eslint.config.js`\n- **!/usr/bin/env tsx**（source_file）：import { Command } from \"commander\"; import as fs from \"fs/promises\"; import as path from \"path\"; import { evaluate } from \"mcpvals\"; import os from \"os\"; import chalk from \"chalk\"; 证据：`evals/run-evals.ts`\n- **Index.D**（source_file）：import type { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; 证据：`index.d.ts`\n- **Index**（source_file）：import { createServer } from \"./dist/index.js\"; export default { createServer }; 证据：`index.js`\n- **Config.Test**（source_file）：import { describe, expect, it } from \"vitest\"; 证据：`src/config.test.ts`\n- **Config**（source_file）：import type { Config } from \"../config.d.ts\"; 证据：`src/config.ts`\n- **Context**（source_file）：import type { Stagehand } from \"@browserbasehq/stagehand\"; import { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; import type { Config } from \"../config.d.ts\"; import { CallToolResult } from \"@modelcontextprotocol/sdk/types.js\"; import { listResources, readResource } from \"./mcp/resources.js\"; import { SessionManager } from \"./sessionManager.js\"; import type { MCPTool } from \"./types/types.js\"; 证据：`src/context.ts`\n- **Index**（source_file）：import as dotenv from \"dotenv\"; dotenv.config ; 证据：`src/index.ts`\n- **Program**（source_file）：import { program } from \"commander\"; import as fs from \"fs\"; import as path from \"path\"; import { fileURLToPath } from \"url\"; 证据：`src/program.ts`\n- **Server**（source_file）：import { Server } from \"@modelcontextprotocol/sdk/server/index.js\"; 证据：`src/server.ts`\n- **Sessionmanager**（source_file）：import { Stagehand } from \"@browserbasehq/stagehand\"; import type { Config } from \"../config.d.ts\"; 证据：`src/sessionManager.ts`\n- **Transport**（source_file）：import http from \"node:http\"; import assert from \"node:assert\"; import crypto from \"node:crypto\"; 证据：`src/transport.ts`\n- **Smoke.Test**（source_file）：import { describe, it, expect } from \"vitest\"; import { Client } from \"@modelcontextprotocol/sdk/client/index.js\"; import { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\"; 证据：`tests/smoke.test.ts`\n- **Vitest.Config**（source_file）：import { defineConfig } from \"vitest/config\"; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, package.json, index.js\n- **安装指南**：importance `high`\n - source_paths: Dockerfile, package.json, tsconfig.json\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/server.ts, src/program.ts, src/transport.ts\n- **核心组件**：importance `high`\n - source_paths: src/config.ts, src/context.ts, src/types/types.ts, src/sessionManager.ts\n- **工具集概述**：importance `high`\n - source_paths: src/tools/index.ts, src/tools/tool.ts, src/tools/navigate.ts, src/tools/act.ts, src/tools/observe.ts\n- **会话管理**：importance `high`\n - source_paths: src/tools/session.ts, src/sessionManager.ts, src/tools/index.ts\n- **配置参数**：importance `high`\n - source_paths: src/config.ts, config.d.ts, cli.js\n- **部署指南**：importance `high`\n - source_paths: Dockerfile, src/transport.ts, cli.js, server.json\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `1e196b3d3c4dc70944e0d19038dd9eb3608b207a`\n- inspected_files: `pnpm-lock.yaml`, `Dockerfile`, `package.json`, `README.md`, `src/index.ts`, `src/config.ts`, `src/server.ts`, `src/program.ts`, `src/config.test.ts`, `src/transport.ts`, `src/sessionManager.ts`, `src/context.ts`, `src/mcp/sampling.ts`, `src/mcp/resources.ts`, `src/tools/navigate.ts`, `src/tools/observe.ts`, `src/tools/index.ts`, `src/tools/act.ts`, `src/tools/extract.ts`, `src/tools/session.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Add MCPpedia security badge to README\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：Add policy enforcement for cloud browser sessions\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：browserbase/mcp-server-browserbase\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 来源证据：Your MCP server is now indexed on Joy Trust Network（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/browserbase/mcp-server-browserbase 项目说明书\n\n生成时间: 2026-05-21 16:34:02 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [安装指南](#page-installation)\n- [系统架构](#page-architecture)\n- [核心组件](#page-core-components)\n- [工具集概述](#page-tools-overview)\n- [会话管理](#page-session-management)\n- [配置参数](#page-configuration)\n- [部署指南](#page-deployment)\n- [MCP 客户端集成](#page-mcp-integration)\n- [模型配置](#page-model-configuration)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [安装指南](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [server.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/server.json)\n \n\n# 项目介绍\n\n## 1 项目概述\n\n`@browserbasehq/mcp` 是一个基于 Model Context Protocol (MCP) 的服务器实现，专门用于通过 Browserbase 和 Stagehand 实现 AI 驱动的 Web 浏览器自动化操作。该项目为 AI 助手提供了与浏览器交互的能力，支持导航网页、执行操作、观察页面元素以及提取数据等核心功能。\n\n项目基本信息如下：\n\n| 属性 | 值 |\n|------|-----|\n| 项目名称 | @browserbasehq/mcp |\n| 当前版本 | 3.0.0 |\n| 许可证 | Apache-2.0 |\n| MCP 协议名称 | io.github.browserbase/mcp-server-browserbase |\n| 开发者 | Browserbase, Inc. |\n| 仓库地址 | https://github.com/browserbase/mcp-server-browserbase |\n\n资料来源：[package.json:1-15]()\n\n## 2 核心功能\n\n该项目作为 MCP 协议的服务器实现，提供了一套完整的浏览器自动化工具集。根据 README.md 的说明，服务器暴露以下核心工具：\n\n| 工具名称 | 功能描述 | 参数 |\n|---------|---------|------|\n| `start` | 创建新的浏览器会话 | _(none)_ |\n| `end` | 关闭浏览器会话 | _(none)_ |\n| `navigate` | 导航到指定 URL | `{ url: string }` |\n| `act` | 在页面上执行操作 | `{ action: string }` |\n| `observe` | 观察页面上的可操作元素 | `{ instruction: string }` |\n| `extract` | 从页面提取数据 | `{ instruction?: string }` |\n\n资料来源：[README.md:48-54]()\n\n### 2.1 工具功能详解\n\n#### start 工具\n用于启动一个新的浏览器会话。在 3.0.0 版本中，该工具不再接受 `sessionId` 参数，这与之前版本的 `browserbase_session_create` 工具存在差异。\n\n#### end 工具\n用于关闭当前活动的浏览器会话，对应旧版本的 `browserbase_session_close`。\n\n#### navigate 工具\n通过接收 URL 参数，将浏览器导航到指定网页地址。\n\n#### act 工具\n在当前页面执行指定的操作。该操作由 AI 模型理解并转换为实际的浏览器操作。注意：在 3.0.0 版本中，`act` 工具不再接受 `variables` 参数。\n\n#### observe 工具\n根据给定的指令观察页面上的可操作元素，帮助 AI 理解页面结构。\n\n#### extract 工具\n从当前页面提取数据。`instruction` 参数现在变为可选，与 Browserbase 托管服务保持一致。\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 3 技术架构\n\n### 3.1 架构概览\n\n项目采用模块化架构设计，主要包含以下核心模块：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B[MCP 服务器]\n B --> C[工具注册层]\n C --> D[上下文管理]\n D --> E[会话管理器]\n E --> F[Stagehand 实例]\n F --> G[Browserbase 云服务]\n G --> H[远程浏览器]\n```\n\n### 3.2 核心模块职责\n\n#### 入口模块 (src/index.ts)\n作为应用程序的主入口，负责初始化 MCP 服务器、注册工具、处理请求路由等核心功能。服务器通过 `server.tool()` 方法注册各个工具，每个工具都关联到对应的处理函数。\n\n```typescript\ntools.forEach((tool) => {\n if (tool.schema.inputSchema instanceof z.ZodObject) {\n server.tool(\n tool.schema.name,\n tool.schema.description,\n tool.schema.inputSchema.shape,\n async (params: z.infer) => {\n const result = await context.run(tool, params);\n return result;\n }\n );\n }\n});\n```\n\n资料来源：[src/index.ts:1-30]()\n\n#### 配置模块 (src/config.ts)\n负责管理和解析应用配置，支持多种配置来源的合并：\n\n- 默认配置\n- 环境变量\n- 命令行参数\n- 配置文件\n\n默认模型为 `google/gemini-2.5-flash-lite`，这与托管 MCP 服务器保持一致。\n\n#### 会话管理器 (src/sessionManager.ts)\n负责管理浏览器会话的生命周期，包括：\n\n- 创建新的浏览器会话\n- 验证会话状态\n- 清理过期会话\n- 批量关闭所有会话\n- 默认会话的自动维护\n\n会话管理器包含以下关键功能：\n\n| 方法 | 功能 |\n|------|------|\n| `getOrCreateSession` | 获取或创建会话 |\n| `createNewBrowserSession` | 创建新的浏览器会话 |\n| `cleanupSession` | 清理指定会话 |\n| `closeAllSessions` | 关闭所有会话 |\n| `ensureDefaultSession` | 确保默认会话存在 |\n\n资料来源：[src/sessionManager.ts:1-80]()\n\n#### 资源模块 (src/mcp/resources.ts)\n实现了 MCP 协议的资源相关接口：\n\n- `listResources()` - 列出可用资源\n- `listResourceTemplates()` - 列出资源模板\n- `readResource(uri)` - 读取指定资源\n\n当前实现中，资源功能返回空列表。\n\n#### 传输层 (src/transport.ts)\n支持两种传输方式：\n\n1. **STDIO** - 标准输入输出传输\n2. **SHTTP** - Streamable HTTP 传输\n\n服务器可以监听指定端口，提供 HTTP 服务供支持 SHTTP 的 MCP 客户端连接。\n\n## 4 依赖关系\n\n### 4.1 主要生产依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| @browserbasehq/sdk | ^2.6.0 | Browserbase SDK |\n| @browserbasehq/stagehand | ^3.3.0 | 浏览器自动化框架 |\n| @modelcontextprotocol/sdk | ^1.13.1 | MCP 协议实现 |\n| commander | ^14.0.0 | 命令行参数解析 |\n| dotenv | ^16.4.6 | 环境变量加载 |\n| zod | ^3.25.67 | 数据验证 |\n\n资料来源：[package.json:27-35]()\n\n### 4.2 关键外部服务\n\n- **Browserbase** - 提供云端浏览器基础设施\n- **Stagehand** - AI 驱动的浏览器自动化框架\n- **Gemini** - 默认使用的 AI 模型（由 GEMINI_API_KEY 或 GOOGLE_API_KEY 配置）\n\n## 5 部署方式\n\n项目支持两种部署方式：\n\n### 5.1 直接安装\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\n### 5.2 Docker 部署\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\n## 6 配置说明\n\n### 6.1 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| BROWSERBASE_API_KEY | 是 | Browserbase API 密钥 |\n| BROWSERBASE_PROJECT_ID | 是 | Browserbase 项目 ID |\n| GEMINI_API_KEY | 是 | Gemini API 密钥（默认模型使用） |\n| GOOGLE_API_KEY | 否 | Google API 密钥（备用） |\n\n### 6.2 命令行参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--proxies` | boolean | 启用代理 |\n| `--verified` | boolean | 启用验证模式 |\n| `--advancedStealth` | boolean | 启用高级隐身模式 |\n| `--contextId` | string | 指定上下文 ID |\n| `--persist` | boolean | 持久化会话 |\n| `--port` | number | HTTP 服务器端口 |\n| `--host` | string | HTTP 服务器主机 |\n| `--browserWidth` | number | 浏览器宽度 |\n| `--browserHeight` | number | 浏览器高度 |\n| `--modelName` | string | 使用的模型名称 |\n| `--modelApiKey` | string | 模型 API 密钥 |\n| `--keepAlive` | boolean | 保持连接活跃 |\n| `--experimental` | boolean | 启用实验性功能 |\n\n资料来源：[src/config.ts:10-28]()\n\n### 6.3 MCP 客户端配置示例\n\n#### STDIO 模式（自托管）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### NPM 模式\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### SHTTP 模式（托管服务）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n资料来源：[README.md:20-70]()\n\n## 7 版本演进\n\n### 7.1 3.0.0 版本重大变更\n\nv3.0.0 版本带来了多项重大变更：\n\n- **工具重命名**：所有工具名称与托管服务保持一致\n - `browserbase_session_create` → `start`\n - `browserbase_session_close` → `end`\n - `browserbase_stagehand_navigate` → `navigate`\n - `browserbase_stagehand_act` → `act`\n - `browserbase_stagehand_observe` → `observe`\n - `browserbase_stagehand_extract` → `extract`\n\n- **移除的工具**：\n - `browserbase_screenshot`\n - `browserbase_stagehand_get_url`\n - `browserbase_stagehand_agent`\n\n- **参数变更**：\n - `act` 工具不再接受 `variables` 参数\n - `start` 工具不再接受 `sessionId` 参数\n - `extract` 工具的 `instruction` 参数变为可选\n\n- **默认模型变更**：从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`\n\n- **依赖更新**：Stagehand 版本升级至 3.3.0\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 8 传输协议支持\n\n项目同时支持两种 MCP 传输协议：\n\n```mermaid\ngraph LR\n A[MCP 客户端] --> B{传输协议选择}\n B --> C[STDIO]\n B --> D[SHTTP]\n C --> E[本地服务器]\n D --> F[远程托管服务]\n E --> G[自托管 MCP 服务器]\n F --> H[mcp.browserbase.com]\n```\n\n### 8.1 STDIO 传输\n\n适用于本地运行场景，服务器通过标准输入输出与客户端通信。推荐使用 NPM 包 `@browserbasehq/mcp` 或直接运行构建后的代码。\n\n### 8.2 SHTTP 传输\n\n适用于使用托管服务场景。Browserbase 提供托管的 MCP 服务器，地址为 `https://mcp.browserbase.com/mcp`。这种方式可以免除本地运行和 LLM 成本。\n\n## 9 项目结构\n\n```\nmcp-server-browserbase/\n├── src/\n│ ├── index.ts # 主入口\n│ ├── context.ts # 上下文管理\n│ ├── config.ts # 配置管理\n│ ├── sessionManager.ts # 会话管理\n│ ├── transport.ts # 传输层\n│ ├── mcp/\n│ │ └── resources.ts # 资源接口\n│ └── tools/\n│ └── extract.ts # 提取工具\n├── cli.js # 命令行入口\n├── package.json # 包配置\n├── server.json # 服务器元数据\n└── README.md # 项目文档\n```\n\n## 10 相关资源\n\n- [Browserbase MCP 文档](https://docs.browserbase.com/integrations/mcp/introduction)\n- [MCP 协议文档](https://modelcontextprotocol.io/docs)\n- [MCP 协议规范](https://spec.modelcontextprotocol.io/)\n- [Stagehand 文档](https://docs.stagehand.dev/)\n\n---\n\n\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [部署指南](#page-deployment)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [Dockerfile](https://github.com/browserbase/mcp-server-browserbase/blob/main/Dockerfile)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n \n\n# 安装指南\n\n本页面详细介绍如何安装和配置 mcp-server-browserbase。MCP 服务器（Model Context Protocol Server）是 Browserbase 提供的 AI 网页自动化解决方案，通过集成 Stagehand 实现智能浏览器操作功能。\n\n## 系统要求\n\n### 运行环境\n\n| 要求项 | 最低版本 | 推荐版本 |\n|--------|----------|----------|\n| Node.js | 18.x | 20.x LTS |\n| npm/pnpm | 8.x | 最新稳定版 |\n| Docker | 24.x | 最新稳定版 |\n| Git | 2.x | 最新稳定版 |\n\n### 环境变量配置\n\n在开始安装前，需要准备以下环境变量：\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目 ID |\n| `GEMINI_API_KEY` | 是 | Gemini 模型 API 密钥（用于默认模型） |\n\n> [!TIP]\n> 如需使用其他模型，可通过 `--modelName` 参数指定，并提供对应的 API 密钥。\n\n资料来源：[README.md:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 安装方式\n\nmcp-server-browserbase 支持三种安装方式，适用于不同的使用场景：\n\n| 安装方式 | 适用场景 | 复杂度 | 更新维护 |\n|----------|----------|--------|----------|\n| NPM（推荐） | 快速集成、主流用户 | 低 | 自动 |\n| 直接安装 | 本地开发、自定义修改 | 中 | 手动 |\n| Docker | 生产环境、隔离部署 | 中 | 手动 |\n\n资料来源：[README.md:40-80](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### 方式一：NPM 安装（推荐）\n\nNPM 安装是最简洁的方式，适合大多数用户快速上手。\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### 安装步骤\n\n1. 确保已安装 Node.js 18+ 和 npm\n2. 在 MCP 配置文件中添加上述配置\n3. 填写对应的环境变量值\n4. 重启 MCP 客户端即可使用\n\n### 方式二：直接安装\n\n直接安装适合需要自定义修改或本地开发的用户。\n\n#### 前置条件\n\n- Git 已安装\n- Node.js 18+ 已安装\n- npm 或 pnpm 包管理器\n\n#### 安装命令\n\n```bash\n# 克隆仓库\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\n\n# 进入项目目录\ncd mcp-server-browserbase\n\n# 安装依赖并构建\nnpm install && npm run build\n```\n\n#### MCP 配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:10-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### 方式三：Docker 安装\n\nDocker 安装提供完整的隔离环境，适合生产部署。\n\n#### 构建镜像\n\n```bash\n# 克隆仓库\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\n\n# 进入项目目录\ncd mcp-server-browserbase\n\n# 构建 Docker 镜像\ndocker build -t mcp-browserbase .\n```\n\n#### MCP 配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:20-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 传输方式配置\n\nMCP 服务器支持两种传输协议，根据 MCP 客户端能力选择合适的传输方式：\n\n| 传输方式 | 说明 | 端口 | 推荐场景 |\n|----------|------|------|----------|\n| SHTTP（Streamable HTTP） | 推荐方式，性能最优 | 动态 | 支持 HTTP 的客户端 |\n| STDIO | 标准输入输出 | 无 | 命令行工具、本地开发 |\n\n资料来源：[src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n### SHTTP（托管服务）\n\n使用 Browserbase 托管的 MCP 服务器地址 `https://mcp.browserbase.com/mcp`，这是最简便的启动方式。\n\n#### 支持 SHTTP 的客户端配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n#### 不支持 SHTTP 的客户端配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:60-90](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n### STDIO（自托管）\n\nSTDIO 方式允许完全本地运行服务器。\n\n#### NPM 方式运行\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### 本地完全自托管\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@anthropic/mcp-remote\",\n \"node\",\n \"/path/to/mcp-server-browserbase/dist/index.js\",\n \"--apiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\"\n }\n }\n }\n}\n```\n\n> [!NOTE]\n> 如需使用不同的模型，需要添加 `--modelName` 参数并提供对应的密钥。\n\n资料来源：[README.md:95-130](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 命令行参数配置\n\n服务器支持丰富的命令行参数，用于自定义部署行为：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--proxies` | boolean | false | 启用代理功能 |\n| `--verified` | boolean | false | 启用验证模式 |\n| `--advancedStealth` | boolean | false | 启用高级隐身模式 |\n| `--contextId` | string | - | 指定上下文 ID |\n| `--persist` | boolean | false | 持久化会话 |\n| `--port` | number | - | HTTP 服务端口 |\n| `--host` | string | - | HTTP 服务主机 |\n| `--browserWidth` | number | 1024 | 浏览器窗口宽度 |\n| `--browserHeight` | number | 768 | 浏览器窗口高度 |\n| `--modelName` | string | google/gemini-2.5-flash-lite | 使用的模型名称 |\n| `--modelApiKey` | string | - | 模型 API 密钥 |\n| `--keepAlive` | boolean | false | 保持连接活跃 |\n| `--experimental` | boolean | false | 启用实验性功能 |\n\n资料来源：[src/config.ts:1-40](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 配置合并优先级\n\n系统配置采用分层合并策略，优先级从低到高如下：\n\n1. **默认配置** - 代码中的硬编码默认值\n2. **文件配置** - 配置文件中的设置\n3. **CLI 参数** - 命令行传入的参数（最高优先级）\n\n```mermaid\ngraph TD\n A[默认配置] --> B[合并文件配置]\n B --> C[合并CLI参数]\n C --> D[最终配置]\n```\n\n资料来源：[src/config.ts:45-60](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## 项目结构与构建\n\n### 项目依赖\n\n主要生产依赖包括：\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| `@browserbasehq/sdk` | ^2.6.0 | Browserbase SDK |\n| `@browserbasehq/stagehand` | ^3.3.0 | 浏览器自动化框架 |\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP 协议实现 |\n| `commander` | ^14.0.0 | 命令行工具 |\n| `dotenv` | ^16.4.6 | 环境变量加载 |\n| `zod` | ^3.25.67 | 数据验证 |\n\n资料来源：[package.json:30-45](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n### 构建命令\n\n| 命令 | 说明 |\n|------|------|\n| `npm run build` | 编译 TypeScript 并设置权限 |\n| `npm run watch` | 监听模式编译 |\n| `npm test` | 运行测试 |\n| `npm run inspector` | 启动 MCP 检查器 |\n\n#### 构建流程\n\n```bash\n# 开发构建\nnpm install && npm run build\n\n# 监听模式（开发时使用）\nnpm run watch\n\n# 运行测试\nnpm test\n```\n\n资料来源：[package.json:20-35](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 完整配置示例\n\n### 开发环境配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"bb-api-key-dev\",\n \"BROWSERBASE_PROJECT_ID\": \"project-dev-123\",\n \"GEMINI_API_KEY\": \"gemini-dev-key\"\n }\n }\n }\n}\n```\n\n### 生产环境配置（Docker）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"bb-api-key-prod\",\n \"BROWSERBASE_PROJECT_ID\": \"project-prod-456\",\n \"GEMINI_API_KEY\": \"gemini-prod-key\"\n }\n }\n }\n}\n```\n\n### 自定义模型配置\n\n如需使用不同的 AI 模型：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"ANTHROPIC_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n> [!WARNING]\n> 使用的模型必须在 Stagehand 支持的模型列表中。详情请参阅 [Stagehand 文档](https://docs.stagehand.dev/examples/custom_llms#supported-llms)。\n\n资料来源：[README.md:130-160](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 验证安装\n\n安装完成后，可以通过 MCP 检查器验证服务器是否正常工作：\n\n```bash\n# 使用 npm 脚本启动检查器\nnpm run inspector\n```\n\n检查器将启动可视化界面，可以测试 MCP 服务器的各项功能和工具。\n\n资料来源：[package.json:24](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接失败 | 环境变量未设置 | 检查 `BROWSERBASE_API_KEY` 等变量 |\n| 模型调用失败 | API 密钥无效 | 验证 `GEMINI_API_KEY` |\n| 浏览器启动失败 | 权限问题 | 确保 Docker 有足够权限 |\n| 构建失败 | Node 版本过低 | 升级到 Node.js 18+ |\n\n### 环境变量验证\n\n在启动服务器前，可以创建 `.env` 文件管理环境变量：\n\n```bash\n# 创建 .env 文件\ncat > .env << EOF\nBROWSERBASE_API_KEY=your_api_key_here\nBROWSERBASE_PROJECT_ID=your_project_id_here\nGEMINI_API_KEY=your_gemini_key_here\nEOF\n```\n\n资料来源：[src/config.ts:1-30](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n## 相关资源\n\n- [Browserbase MCP 官方文档](https://docs.browserbase.com/integrations/mcp/introduction)\n- [MCP 协议文档](https://modelcontextprotocol.io/docs)\n- [MCP 协议规范](https://spec.modelcontextprotocol.io/)\n- [Stagehand 文档](https://docs.stagehand.dev/)\n- [GitHub 仓库](https://github.com/browserbase/mcp-server-browserbase)\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [核心组件](#page-core-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n \n\n# 系统架构\n\n## 概述\n\nmcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 模型提供网页自动化能力。该服务器通过集成 Browserbase 基础设施和 Stagehand 浏览器自动化框架，使 LLM 能够通过标准化接口执行网页操作。\n\n资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 核心架构组件\n\n### 组件层次结构\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n MCP_CLIENT[MCP 客户端]\n end\n \n subgraph \"传输层\"\n STDIO[STDIO 传输]\n HTTP[HTTP/SHTTP 传输]\n end\n \n subgraph \"核心服务层\"\n MCP_SERVER[MCP 服务器]\n SERVER_LIST[ServerList 管理器]\n end\n \n subgraph \"业务逻辑层\"\n CONTEXT[Context 上下文]\n SESSION_MANAGER[SessionManager 会话管理器]\n end\n \n subgraph \"工具层\"\n START[start 工具]\n END[end 工具]\n NAVIGATE[navigate 工具]\n ACT[act 工具]\n OBSERVE[observe 工具]\n EXTRACT[extract 工具]\n end\n \n subgraph \"外部集成\"\n STAGEHAND[Stagehand 框架]\n BROWSERBASE[Browserbase SDK]\n end\n \n MCP_CLIENT --> STDIO\n MCP_CLIENT --> HTTP\n STDIO --> MCP_SERVER\n HTTP --> MCP_SERVER\n MCP_SERVER --> CONTEXT\n CONTEXT --> SESSION_MANAGER\n SESSION_MANAGER --> STAGEHAND\n STAGEHAND --> BROWSERBASE\n \n START --> SESSION_MANAGER\n END --> SESSION_MANAGER\n NAVIGATE --> CONTEXT\n ACT --> CONTEXT\n OBSERVE --> CONTEXT\n EXTRACT --> CONTEXT\n```\n\n### 组件职责表\n\n| 组件名称 | 文件位置 | 职责描述 |\n|---------|---------|---------|\n| MCP_SERVER | src/index.ts | 注册 MCP 协议处理器，注册工具，处理请求路由 |\n| ServerList | src/server.ts | 管理多个服务器实例的生命周期 |\n| SessionManager | src/sessionManager.ts | 管理浏览器会话创建、验证、清理和复用 |\n| Context | src/context.ts | 提供工具执行上下文，集成 Stagehand 实例 |\n| Transport | src/transport.ts | 处理 HTTP 服务器启动和请求分发 |\n\n资料来源：[src/index.ts:1-100](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n## 传输层架构\n\n### 支持的传输方式\n\n该服务器支持两种传输协议，通过命令行参数指定：\n\n| 传输类型 | 配置方式 | 使用场景 |\n|---------|---------|---------|\n| STDIO | 命令行直接运行 | 本地部署，推荐用于 Claude Desktop |\n| HTTP/SHTTP | 启动 HTTP 服务器 | 远程部署，支持流式 HTTP |\n\n### HTTP 传输实现\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|HTTP POST /mcp| B[HTTP Server]\n B --> C[handleStreamable 函数]\n C --> D[ServerList]\n D --> E[MCP Server]\n E --> F[工具执行]\n```\n\nHTTP 服务器在指定端口启动，监听 `/mcp` 端点处理 MCP 请求：\n\n```typescript\nhttpServer.listen(port, hostname, () => {\n const message = [\n `Listening on ${url}`,\n \"Put this in your client config:\",\n JSON.stringify({\n mcpServers: {\n browserbase: {\n type: \"http\",\n url: `${url}/mcp`,\n },\n },\n }, undefined, 2),\n ].join(\"\\n\");\n console.log(message);\n});\n```\n\n资料来源：[src/transport.ts:1-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n\n## 会话管理架构\n\n### SessionManager 设计\n\nSessionManager 是核心的会话管理组件，负责浏览器实例的生命周期管理。\n\n```mermaid\ngraph TB\n subgraph \"SessionManager\"\n browsers[Map]\n activeSessionId[当前活动会话ID]\n defaultSessionId[默认会话ID: __default__]\n cleaningUpSessions[正在清理的会话集合]\n defaultSessionCreationPromise[创建互斥锁]\n end\n \n subgraph \"BrowserSession\"\n stagehand[Stagehand 实例]\n config[会话配置]\n end\n```\n\n### 会话状态管理\n\n| 状态 | 描述 | 处理逻辑 |\n|-----|------|---------|\n| VALID | 会话有效且可用 | 直接返回使用 |\n| STALE | 会话过期或无响应 | 关闭并重建 |\n| MISSING | 会话不存在 | 创建新会话 |\n| CREATING | 正在创建中 | 等待创建完成 |\n\n### 关键方法\n\n| 方法 | 功能 | 线程安全 |\n|-----|------|---------|\n| `ensureDefaultSession()` | 确保默认会话存在 | 使用互斥锁 |\n| `getSession()` | 获取或创建指定会话 | 支持并发 |\n| `cleanupSession()` | 清理指定会话 | 幂等操作 |\n| `closeAllSessions()` | 关闭所有会话 | 批量处理 |\n\n会话验证通过执行简单操作检测可用性：\n\n```typescript\nconst pages = this.defaultBrowserSession.stagehand.context.pages();\nif (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n}\n```\n\n资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## 工具系统架构\n\n### 工具注册流程\n\n```mermaid\ngraph TD\n A[TOOLS 数组] --> B[遍历工具]\n B --> C{schema 类型检查}\n C -->|ZodObject| D[server.tool 注册]\n C -->|非 ZodObject| E[警告日志输出]\n D --> F[MCP 服务器就绪]\n```\n\n### 内置工具列表\n\n| 工具名称 | 功能 | 必填参数 | 可选参数 |\n|---------|------|---------|---------|\n| start | 创建新浏览器会话 | 无 | proxies, modelName |\n| end | 关闭指定会话 | sessionId | 无 |\n| navigate | 导航到指定 URL | url | 无 |\n| act | 执行页面操作 | action | 无 |\n| observe | 观察可交互元素 | instruction | 无 |\n| extract | 提取页面数据 | 无 | instruction |\n\n### 工具执行流程\n\n```mermaid\nsequenceDiagram\n participant MCP as MCP 客户端\n participant Server as MCP Server\n participant Context as Context\n participant Tool as Tool Handler\n participant Stagehand as Stagehand\n\n MCP->>Server: 工具调用请求\n Server->>Context: context.run(tool, params)\n Context->>Tool: 调用 handle 方法\n Tool->>Stagehand: 执行实际操作\n Stagehand-->>Tool: 返回结果\n Tool-->>Context: 返回 ToolResult\n Context-->>Server: 返回执行结果\n Server-->>MCP: 返回响应\n```\n\n### 工具接口定义\n\n每个工具实现统一的接口结构：\n\n```typescript\ninterface Tool> {\n capability: \"core\" | \"extended\";\n schema: ToolSchema;\n handle: (context: Context, params: z.infer) => Promise;\n}\n```\n\n资料来源：[src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n\n## Context 上下文管理\n\n### 上下文职责\n\nContext 是连接 MCP 协议层和业务逻辑层的桥梁，负责：\n\n1. 提供 Stagehand 实例访问\n2. 管理活动会话\n3. 工具执行和错误处理\n\n```mermaid\ngraph TB\n subgraph \"Context\"\n sessionManager[SessionManager]\n activeSessionId[活动会话ID]\n end\n \n Context-->|获取| sessionManager\n Context-->|提供| stagehand\n```\n\n### 工具执行方法\n\n```typescript\nasync run(tool: Tool, params: any): Promise {\n // 调用工具的 handle 方法\n const result = await tool.handle(this, params);\n return result;\n}\n```\n\n资料来源：[src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## ServerList 服务器管理\n\n### 设计模式\n\nServerList 采用工厂模式管理多个服务器实例：\n\n```mermaid\nclassDiagram\n class ServerList {\n -_servers: Server[]\n -_serverFactory: () => Promise~Server~\n +create(): Promise~Server~\n +close(server: Server): Promise~void~\n +closeAll(): Promise~void~\n }\n```\n\n### 核心方法\n\n| 方法 | 签名 | 描述 |\n|-----|------|-----|\n| create | `() => Promise` | 创建新服务器并加入管理 |\n| close | `(server: Server) => Promise` | 关闭指定服务器 |\n| closeAll | `() => Promise` | 关闭所有服务器 |\n\n资料来源：[src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n\n## 数据流架构\n\n### 请求处理流程\n\n```mermaid\ngraph TD\n A[客户端请求] --> B{传输类型}\n B -->|STDIO| C[stdio 传输]\n B -->|HTTP| D[HTTP 服务器]\n \n C --> E[MCP Server.handle]\n D --> E\n \n E --> F[路由到工具处理器]\n F --> G[Context.run]\n G --> H[Tool.handle]\n H --> I[Stagehand 操作]\n I --> J[浏览器执行]\n J --> K[结果返回]\n K --> L[格式化响应]\n L --> M[返回给客户端]\n```\n\n### 会话创建流程\n\n```mermaid\ngraph TB\n A[start 工具调用] --> B{是否存在默认会话}\n B -->|否| C[调用 createNewBrowserSession]\n B -->|是| D{会话是否有效}\n D -->|有效| E[返回现有会话]\n D -->|无效| F[关闭旧会话]\n F --> C\n C --> G[创建 Stagehand 实例]\n G --> H[配置 Browserbase]\n H --> I[返回 BrowserSession]\n I --> J[存储到 browsers Map]\n J --> K[标记为活动会话]\n```\n\n## 配置体系\n\n### 环境变量配置\n\n| 变量名 | 必填 | 描述 |\n|-------|-----|------|\n| BROWSERBASE_API_KEY | 是 | Browserbase API 密钥 |\n| BROWSERBASE_PROJECT_ID | 是 | Browserbase 项目 ID |\n| GEMINI_API_KEY | 是 | Gemini API 密钥（用于 LLM 操作） |\n\n### 命令行参数\n\n| 参数 | 描述 | 默认值 |\n|-----|------|-------|\n| `--proxies` | 启用代理支持 | false |\n| `--modelName` | 指定使用的模型名称 | google/gemini-2.5-flash-lite |\n\n### MCP 配置示例\n\n**STDIO 模式：**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**HTTP 模式：**\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n## 依赖关系\n\n### 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|-----|-----|\n| @modelcontextprotocol/sdk | ^1.13.1 | MCP 协议实现 |\n| @browserbasehq/stagehand | ^3.3.0 | 浏览器自动化框架 |\n| @browserbasehq/sdk | ^2.6.0 | Browserbase API 客户端 |\n| zod | ^3.25.67 | Schema 验证 |\n\n### 开发依赖\n\n| 依赖包 | 版本 | 用途 |\n|-------|-----|-----|\n| typescript | ^5.6.2 | TypeScript 编译 |\n| vitest | ^4.1.2 | 单元测试 |\n| eslint | ^9.29.0 | 代码检查 |\n| prettier | ^3.6.1 | 代码格式化 |\n\n资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n## 部署模式\n\n### 自托管部署\n\n```mermaid\ngraph LR\n A[本地机器] -->|npm run build| B[构建产物]\n B --> C[cli.js]\n C --> D[MCP 客户端]\n D --> E[Browserbase 云服务]\n```\n\n### Docker 部署\n\n```mermaid\ngraph TB\n A[Dockerfile] --> B[docker build]\n B --> C[mcp-browserbase 镜像]\n C --> D[docker run]\n D --> E[MCP 客户端连接]\n```\n\n构建命令：\n```bash\ndocker build -t mcp-browserbase .\n```\n\n运行配置：\n```json\n{\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"BROWSERBASE_API_KEY\", \"-e\", \"BROWSERBASE_PROJECT_ID\", \"-e\", \"GEMINI_API_KEY\", \"mcp-browserbase\"]\n}\n```\n\n## 安全考虑\n\n### 会话隔离\n\n- 每个会话独立的 BrowserSession 实例\n- 会话清理使用互斥锁防止竞态条件\n- 过期会话自动检测和清理\n\n### 错误处理\n\n```mermaid\ngraph TB\n A[异常发生] --> B{异常类型}\n B -->|Stagehand 错误| C[记录错误日志]\n B -->|会话无效| D[清理会话]\n B -->|创建失败| E[重试一次]\n C --> F[返回错误响应]\n D --> F\n E --> G{重试成功?}\n E -->|否| F\n G -->|是| H[返回成功]\n```\n\n### 敏感信息管理\n\n- API 密钥通过环境变量传递\n- 不在日志中输出敏感配置\n- 命令行参数支持但不推荐传递密钥\n\n## 扩展性设计\n\n### 添加新工具\n\n1. 在 `src/tools/` 目录创建新工具文件\n2. 实现 Tool 接口的 schema 和 handle 方法\n3. 将工具添加到 TOOLS 数组导出\n4. 工具将自动注册到 MCP 服务器\n\n### 自定义传输\n\n传输层支持扩展，可通过修改 `src/transport.ts` 添加新的传输协议实现。\n\n## 总结\n\nmcp-server-browserbase 采用分层架构设计，通过清晰的责任分离实现了：\n\n- **可维护性**：各组件职责明确，易于理解和修改\n- **可扩展性**：工具系统支持灵活扩展新功能\n- **可靠性**：会话管理和错误处理机制完善\n- **兼容性**：支持多种 MCP 客户端和部署方式\n\n该架构为 AI 模型提供了标准化的网页自动化接口，同时保持了与 Browserbase 生态系统的深度集成。\n\n---\n\n\n\n## 核心组件\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [工具集概述](#page-tools-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [src/mcp/resources.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# 核心组件\n\n本文档详细介绍了 `mcp-server-browserbase` 项目的核心组件架构，包括配置管理、会话管理、工具系统、传输层和上下文管理等关键模块。\n\n## 概述\n\nmcp-server-browserbase 是一个基于 Model Context Protocol (MCP) 的服务器实现，用于通过 Browserbase 和 Stagehand 实现 AI 网页自动化。该项目采用 TypeScript 开发，使用 `@modelcontextprotocol/sdk` 作为 MCP 协议的实现基础。\n\n**项目技术栈：**\n\n| 类别 | 技术/库 |\n|------|---------|\n| 核心框架 | `@modelcontextprotocol/sdk: ^1.13.1` |\n| 浏览器自动化 | `@browserbasehq/stagehand: ^3.3.0` |\n| 浏览器控制 | `@browserbasehq/sdk: ^2.6.0` |\n| 数据验证 | `zod: ^3.25.67` |\n| CLI 参数解析 | `commander: ^14.0.0` |\n| 环境变量 | `dotenv: ^16.4.6` |\n\n资料来源：[package.json:1-30]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n A[MCP 客户端] -->|STDIO/SHTTP| B[MCP Server]\n B --> C[ServerList]\n C --> D[SessionManager]\n D --> E[Stagehand 实例]\n E --> F[浏览器会话]\n \n B --> G[Context]\n G --> H[工具系统]\n H --> I[extract]\n H --> J[act]\n H --> K[navigate]\n H --> L[observe]\n \n B --> M[Resources]\n B --> N[Transport]\n```\n\n## 1. 配置管理 (Config)\n\n### 1.1 配置结构\n\n配置管理模块负责集中管理所有运行时配置选项，包括环境变量、CLI 参数和默认配置值。\n\n资料来源：[src/config.ts:1-5]()\n\n**CLI 选项类型定义：**\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\n资料来源：[src/config.ts:10-25]()\n\n### 1.2 默认配置值\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `browserbaseApiKey` | `BROWSERBASE_API_KEY` 环境变量 | Browserbase API 密钥 |\n| `browserbaseProjectId` | `BROWSERBASE_PROJECT_ID` 环境变量 | Browserbase 项目 ID |\n| `proxies` | `false` | 是否启用代理 |\n| `browserWidth` | `1024` | 浏览器窗口宽度 |\n| `browserHeight` | `768` | 浏览器窗口高度 |\n| `modelName` | `google/gemini-2.5-flash-lite` | 默认模型名称 |\n| `modelApiKey` | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | 模型 API 密钥 |\n\n资料来源：[src/config.ts:28-40]()\n\n### 1.3 配置合并策略\n\n配置采用分层合并策略，优先级顺序为：**默认值 < 文件配置 < CLI 参数**\n\n```typescript\nexport async function resolveConfig(cliOptions: CLIOptions): Promise {\n const cliConfig = await configFromCLIOptions(cliOptions);\n const mergedConfig = normalizeVerifiedConfig(\n mergeConfig(defaultConfig, cliConfig),\n );\n // 环境变量补充\n if (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n }\n return mergedConfig;\n}\n```\n\n资料来源：[src/config.ts:45-58]()\n\n## 2. 会话管理器 (SessionManager)\n\n### 2.1 概述\n\nSessionManager 是整个系统的核心组件，负责管理多个浏览器会话的生命周期。每个会话对应一个独立的 Stagehand 实例和底层浏览器实例。\n\n资料来源：[src/sessionManager.ts:1-10]()\n\n### 2.2 核心数据结构\n\n```typescript\nclass SessionManager {\n private browsers: Map = new Map();\n private defaultSessionId: string = \"(default)\";\n private defaultBrowserSession: BrowserSession | null = null;\n private defaultSessionCreationPromise: Promise | null = null;\n private activeSessionId: string = \"(default)\";\n private cleaningUpSessions: Set = new Set();\n}\n\ntype BrowserSession = {\n stagehand: Stagehand;\n config: Config;\n};\n```\n\n资料来源：[src/sessionManager.ts:1-50]()\n\n### 2.3 会话生命周期\n\n```mermaid\nstateDiagram-v2\n [*] --> 创建中: createSession()\n 创建中 --> 活跃: 创建成功\n 创建中 --> [*]: 创建失败\n 活跃 --> 清理中: cleanupSession()\n 活跃 --> 失效: 检测到过期\n 失效 --> [*]: 自动清理\n 清理中 --> [*]: 清理完成\n```\n\n### 2.4 主要方法\n\n| 方法 | 功能 | 说明 |\n|------|------|------|\n| `createSession()` | 创建新会话 | 初始化 Stagehand 实例 |\n| `getOrCreateDefaultSession()` | 获取或创建默认会话 | 懒加载机制 |\n| `cleanupSession(sessionId)` | 清理指定会话 | 优雅关闭浏览器 |\n| `closeAllSessions()` | 关闭所有会话 | 批量清理 |\n| `setActiveSessionId(id)` | 设置活跃会话 | 管理当前会话 |\n\n资料来源：[src/sessionManager.ts:60-120]()\n\n### 2.5 会话验证机制\n\nSessionManager 实现了一套完整的会话有效性验证机制：\n\n1. **简单验证**：检查 `pages` 是否存在且数量大于 0\n2. **错误捕获**：任何操作异常都会触发会话重建\n3. **自动重试**：首次创建失败后自动重试一次\n\n```typescript\n// 会话有效性检查示例\nconst pages = this.defaultBrowserSession.stagehand.context.pages();\nif (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n}\n```\n\n资料来源：[src/sessionManager.ts:150-180]()\n\n### 2.6 并发控制\n\n为防止重复创建会话，SessionManager 使用 Promise 缓存机制：\n\n```typescript\nprivate defaultSessionCreationPromise: Promise | null = null;\n```\n\n当一个会话正在创建时，后续请求会等待同一 Promise，而不是触发新的创建操作。\n\n资料来源：[src/sessionManager.ts:100-110]()\n\n## 3. 上下文管理 (Context)\n\n### 3.1 概述\n\nContext 是工具执行时的运行时上下文，负责协调 SessionManager 和工具之间的交互。\n\n资料来源：[src/context.ts:1-10]()\n\n### 3.2 核心职责\n\n```mermaid\ngraph LR\n A[工具请求] --> B[Context.run]\n B --> C[SessionManager]\n C --> D[获取 Stagehand]\n D --> E[执行工具]\n E --> F[返回结果]\n```\n\n### 3.3 工具执行流程\n\n```typescript\nasync run(tool: Tool, params: unknown): Promise {\n const session = await this.sessionManager.getOrCreateDefaultSession();\n \n if (tool.handle) {\n const result = await tool.handle(this, params);\n return result;\n }\n \n throw new Error(`Tool ${tool.schema.name} does not have a handle method`);\n}\n```\n\n资料来源：[src/context.ts:30-50]()\n\n### 3.4 资源管理\n\nContext 还负责 MCP 资源的列表和读取操作：\n\n```typescript\nlistResources() {\n return listResources();\n}\n\nreadResource(uri: string) {\n return readResource(uri);\n}\n```\n\n资料来源：[src/context.ts:55-65]()\n\n## 4. 工具系统 (Tools)\n\n### 4.1 工具架构\n\n工具系统采用插件化架构，每个工具都是一个独立模块，遵循统一的接口定义。\n\n资料来源：[src/tools/tool.ts:1-40]()\n\n### 4.2 工具类型定义\n\n```typescript\nexport type Tool = {\n capability: string; // 工具能力分类\n schema: ToolSchema; // 工具元数据\n handle: (context: Context, params: z.output) => Promise;\n};\n\nexport type ToolResult = {\n action?: () => Promise;\n waitForNetwork: boolean;\n};\n```\n\n资料来源：[src/tools/tool.ts:20-35]()\n\n### 4.3 工具定义示例：extract\n\n以下以 `extract` 工具为例说明工具的实现方式：\n\n资料来源：[src/tools/extract.ts:1-50]()\n\n```typescript\nconst ExtractInputSchema = z.object({\n instruction: z.string().optional(),\n});\n\nconst extractSchema: ToolSchema = {\n name: \"extract\",\n description: \"Extract data from the page\",\n inputSchema: ExtractInputSchema,\n};\n\nasync function handleExtract(\n context: Context,\n params: ExtractInput,\n): Promise {\n const action = async (): Promise => {\n const stagehand = await context.getStagehand();\n const extraction = params.instruction\n ? await stagehand.extract(params.instruction)\n : await stagehand.extract({});\n return { content: [{ type: \"text\", text: JSON.stringify({ success: true, data: extraction }) }] };\n };\n return { action, waitForNetwork: false };\n}\n```\n\n资料来源：[src/tools/extract.ts:15-45]()\n\n### 4.4 核心工具列表\n\n| 工具名称 | 功能描述 | 输入参数 |\n|----------|----------|----------|\n| `start` | 创建新的浏览器会话 | `{ proxies?: boolean, verified?: boolean, ... }` |\n| `end` | 关闭当前会话 | - |\n| `navigate` | 导航到指定 URL | `{ url: string }` |\n| `act` | 执行页面操作 | `{ action: string }` |\n| `observe` | 观察页面可交互元素 | `{ instruction: string }` |\n| `extract` | 从页面提取数据 | `{ instruction?: string }` |\n\n资料来源：[README.md:1-50]()\n\n### 4.5 工具注册流程\n\n工具通过 `tools.ts` 统一注册到 MCP 服务器：\n\n```typescript\nconst tools: MCPToolsArray = [...TOOLS];\n\ntools.forEach((tool) => {\n if (tool.schema.inputSchema instanceof z.ZodObject) {\n server.tool(\n tool.schema.name,\n tool.schema.description,\n tool.schema.inputSchema.shape,\n async (params) => {\n const result = await context.run(tool, params);\n return result;\n }\n );\n }\n});\n```\n\n资料来源：[src/index.ts:50-80]()\n\n## 5. 传输层 (Transport)\n\n### 5.1 传输方式\n\nmcp-server-browserbase 支持两种传输方式：\n\n| 传输方式 | 说明 | 使用场景 |\n|----------|------|----------|\n| STDIO | 标准输入输出 | 本地 CLI 工具集成 |\n| SHTTP | 流式 HTTP | 远程/托管部署 |\n\n资料来源：[README.md:60-80]()\n\n### 5.2 HTTP 传输实现\n\n```mermaid\ngraph LR\n A[MCP 客户端] -->|HTTP 请求| B[HTTP Server]\n B --> C[handleStreamable]\n C --> D[ServerList]\n D --> E[Server 实例]\n```\n\n### 5.3 服务器地址解析\n\n传输层支持动态端口和地址解析：\n\n```typescript\nlet resolvedHost = address.family === \"IPv4\" \n ? address.address \n : `[${address.address}]`;\nif (resolvedHost === \"0.0.0.0\" || resolvedHost === \"[::]\") {\n resolvedHost = \"localhost\";\n}\n```\n\n资料来源：[src/transport.ts:50-70]()\n\n## 6. 服务器管理 (ServerList)\n\n### 6.1 概述\n\nServerList 负责管理多个 MCP Server 实例的生命周期。\n\n资料来源：[src/server.ts:1-30]()\n\n### 6.2 类结构\n\n```typescript\nexport class ServerList {\n private _servers: Server[] = [];\n private _serverFactory: () => Promise;\n\n async create(): Promise { /* ... */ }\n async close(server: Server): Promise { /* ... */ }\n async closeAll(): Promise { /* ... */ }\n}\n```\n\n资料来源：[src/server.ts:5-25]()\n\n## 7. 资源系统 (Resources)\n\n### 7.1 概述\n\nMCP 资源系统提供了只读数据的访问接口。当前实现为空结构，保留扩展能力。\n\n资料来源：[src/mcp/resources.ts:1-20]()\n\n### 7.2 资源定义\n\n```typescript\nexport const RESOURCES = [];\nexport const RESOURCE_TEMPLATES = [];\n\nexport function listResources() {\n return { resources: [] };\n}\n\nexport function listResourceTemplates() {\n return { resourceTemplates: [] };\n}\n\nexport function readResource(uri: string) {\n return { contents: [{ uri, text: `Resource not found: ${uri}` }] };\n}\n```\n\n资料来源：[src/mcp/resources.ts:1-25]()\n\n## 8. 组件交互关系\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP Server\n participant Context as Context\n participant SessionMgr as SessionManager\n participant Tool as Tool Handler\n participant Stagehand as Stagehand\n\n Client->>Server: 请求工具调用\n Server->>Context: run(tool, params)\n Context->>SessionMgr: getOrCreateDefaultSession()\n SessionMgr-->>Context: BrowserSession\n Context->>Tool: handle(context, params)\n Tool->>Stagehand: 执行操作\n Stagehand-->>Tool: 操作结果\n Tool-->>Context: ToolResult\n Context-->>Server: 执行结果\n Server-->>Client: MCP 响应\n```\n\n## 9. 错误处理机制\n\n### 9.1 工具执行错误\n\n```typescript\ntry {\n const result = await context.run(tool, params);\n return result;\n} catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n process.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`\n );\n throw new Error(`Failed to run tool '${tool.schema.name}': ${errorMessage}`);\n}\n```\n\n资料来源：[src/index.ts:60-75]()\n\n### 9.2 会话清理错误\n\nSessionManager 在清理会话时使用幂等设计，确保重复清理不会导致问题：\n\n```typescript\nif (this.cleaningUpSessions.has(sessionIdToLog)) {\n process.stderr.write(\n `[SessionManager] Session ${sessionIdToLog} is already being cleaned up, skipping.\\n`\n );\n return;\n}\n```\n\n资料来源：[src/sessionManager.ts:80-90]()\n\n## 10. 总结\n\nmcp-server-browserbase 的核心组件架构体现了清晰的职责分离：\n\n- **Config** 提供了统一的配置管理\n- **SessionManager** 实现了浏览器会话的完整生命周期管理\n- **Context** 作为运行时上下文连接各组件\n- **Tools** 采用插件化设计便于扩展\n- **Transport** 支持多种传输协议\n- **ServerList** 管理服务器实例\n\n这套架构确保了系统的可维护性、可扩展性和可靠性。\n\n---\n\n\n\n## 工具集概述\n\n### 相关页面\n\n相关主题：[会话管理](#page-session-management), [核心组件](#page-core-components)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n- [src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n- [src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n- [src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n \n\n# 工具集概述\n\n## 简介\n\nmcp-server-browserbase 的工具集（Tools）是该 MCP 服务器的核心功能模块，为大语言模型（LLM）提供浏览器自动化操作能力。通过这些工具，AI 模型可以控制浏览器执行网页导航、元素交互、页面观察和数据提取等任务。\n\n工具集基于 [Stagehand](https://www.stagehand.dev) 框架构建，封装了 Playwright 的底层能力，提供声明式的网页操作接口。每个工具都遵循统一的类型定义和注册机制，确保与 MCP 协议的无缝集成。\n\n**核心功能定位：**\n\n- 为 AI Agent 提供浏览器控制能力\n- 支持会话级别的浏览器状态管理\n- 通过自然语言指令驱动网页自动化操作\n\n## 架构设计\n\n### 工具类型系统\n\n工具系统采用泛型设计，通过 TypeScript 的类型约束确保类型安全。核心类型定义位于 `src/tools/tool.ts` 文件中。\n\n```typescript\nexport type ToolSchema = {\n name: string;\n description: string;\n inputSchema: Input;\n};\n```\n\n每个工具包含三个核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `capability` | `string` | 工具能力分类，如 \"core\" |\n| `schema` | `ToolSchema` | 工具元数据，包含名称、描述和输入模式 |\n| `handle` | `Function` | 工具执行逻辑，处理输入参数并返回结果 |\n\n**工具执行结果类型：**\n\n```typescript\nexport type ToolResult = {\n action?: () => Promise;\n waitForNetwork: boolean;\n};\n```\n\n资料来源：[src/tools/tool.ts:1-30]()\n\n### 工具执行流程\n\n工具的执行通过 `Context` 类的 `run` 方法统一调度。当 MCP 客户端调用工具时，系统按以下流程处理：\n\n```mermaid\ngraph TD\n A[MCP 客户端请求] --> B[Context.run 调度]\n B --> C{工具类型检查}\n C -->|标准工具| D[调用 tool.handle]\n C -->|代理工具| E[代理转发]\n D --> F[Stagehand 执行]\n E --> F\n F --> G[返回 ToolResult]\n G --> H[转换为 MCP 响应]\n```\n\n资料来源：[src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n\n## 核心工具列表\n\n### 工具注册机制\n\n所有工具通过 `src/tools/index.ts` 统一导出和管理。服务器启动时，工具被批量注册到 MCP 服务器实例：\n\n```typescript\nconst tools: MCPToolsArray = [...TOOLS];\n\ntools.forEach((tool) => {\n if (tool.schema.inputSchema instanceof z.ZodObject) {\n server.tool(\n tool.schema.name,\n tool.schema.description,\n tool.schema.inputSchema.shape,\n async (params) => {\n const result = await context.run(tool, params);\n return result;\n },\n );\n }\n});\n```\n\n资料来源：[src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n\n### 工具清单\n\n| 工具名称 | 功能描述 | 输入参数 | 核心能力 |\n|----------|----------|----------|----------|\n| `start` | 创建新浏览器会话 | `sessionId?: string` | 会话管理 |\n| `end` | 关闭浏览器会话 | `sessionId?: string` | 会话管理 |\n| `navigate` | 导航至指定 URL | `{ url: string }` | 页面访问 |\n| `act` | 执行页面动作 | `{ action: string, variables?: object }` | 元素交互 |\n| `observe` | 观察可操作元素 | `{ instruction: string }` | 元素识别 |\n| `extract` | 提取页面数据 | `{ instruction?: string }` | 数据采集 |\n\n资料来源：[README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n\n## 工具详解\n\n### navigate 工具\n\n`navigate` 工具负责将浏览器导航至指定的 URL 地址。\n\n**工具模式定义：**\n\n```typescript\nconst NavigateInputSchema = z.object({\n url: z.string().min(1),\n});\n\nconst navigateSchema: ToolSchema = {\n name: \"navigate\",\n description: \"Navigate to a URL\",\n inputSchema: NavigateInputSchema,\n};\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `url` | `string` | 是 | 目标网页 URL，必须为非空字符串 |\n\n**执行逻辑：**\n\n1. 通过 `context.getStagehand()` 获取当前 Stagehand 实例\n2. 获取浏览器上下文的页面列表\n3. 调用 `page.goto()` 导航至目标 URL\n4. 等待 DOM 内容加载完成（`domcontentloaded`）\n5. 返回导航结果 JSON\n\n**返回值示例：**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"url\": \"https://example.com\"\n }\n}\n```\n\n**错误处理：**\n\n- 当没有可用页面时抛出 `\"No active page available\"`\n- 导航失败时抛出具体错误信息\n\n资料来源：[src/tools/navigate.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/navigate.ts)\n\n### act 工具\n\n`act` 工具用于执行页面上的用户操作，如点击、输入文本等。\n\n**工具模式定义：**\n\n```typescript\nconst ActInputSchema = z.object({\n action: z.string().min(1),\n});\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `action` | `string` | 是 | 自然语言描述的待执行动作 |\n\n**执行逻辑：**\n\n`act` 工具将自然语言动作描述传递给 Stagehand 的 `act` 方法，由 AI 模型解析并执行相应的网页操作。\n\n资料来源：[src/tools/act.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/act.ts)\n\n### observe 工具\n\n`observe` 工具用于观察和识别页面上可交互的元素。\n\n**工具模式定义：**\n\n```typescript\nconst ObserveInputSchema = z.object({\n instruction: z.string().min(1),\n});\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `instruction` | `string` | 是 | 观察指令，描述要查找的元素或区域 |\n\n**执行逻辑：**\n\n`observe` 工具调用 Stagehand 的 `observe` 方法，识别页面中符合指令描述的可交互元素，并返回识别结果。\n\n资料来源：[src/tools/observe.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/observe.ts)\n\n### extract 工具\n\n`extract` 工具用于从当前页面提取结构化数据。\n\n**工具模式定义：**\n\n```typescript\nconst ExtractInputSchema = z.object({\n instruction: z.string().optional(),\n});\n\nconst extractSchema: ToolSchema = {\n name: \"extract\",\n description: \"Extract data from the page\",\n inputSchema: ExtractInputSchema,\n};\n```\n\n**输入参数：**\n\n| 参数名 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| `instruction` | `string` | 否 | 可选的提取指令，描述要提取的数据 |\n\n**执行逻辑：**\n\n1. 获取当前 Stagehand 实例\n2. 根据是否提供指令参数调用对应的提取方法：\n - 有指令时：`stagehand.extract(params.instruction)`\n - 无指令时：`stagehand.extract({})`\n3. 返回提取结果的 JSON 表示\n\n**返回值示例：**\n\n```json\n{\n \"success\": true,\n \"data\": {\n \"extracted_content\": \"...\"\n }\n}\n```\n\n**设计特点：**\n\n- `instruction` 参数为可选项，设计上兼容无参数的默认提取行为\n- 返回值统一封装在 `{ success, data }` 结构中\n\n资料来源：[src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n\n## 会话管理\n\n### BrowserSession 结构\n\n工具的执行依赖于 `BrowserSession` 对象，该对象封装了 Stagehand 实例和相关的会话状态：\n\n```typescript\ninterface BrowserSession {\n id: string;\n stagehand: Stagehand;\n config: Config;\n // ... 其他会话状态\n}\n```\n\n资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n### 会话生命周期\n\n```mermaid\ngraph LR\n A[创建会话] --> B[激活会话]\n B --> C[执行工具]\n C --> D[验证会话]\n D -->|正常| C\n D -->|失效| E[清理会话]\n E --> A\n C --> F[结束会话]\n```\n\n**会话创建流程：**\n\n1. 调用 `createSession(config)` 创建新会话\n2. 初始化 Stagehand 实例\n3. 将会话添加到 `browsers` Map 中\n4. 设置为活跃会话\n\n**会话验证机制：**\n\n- 定期检查会话有效性\n- 验证页面列表是否存在\n- 失效时自动重建会话\n\n资料来源：[src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n\n## 工具扩展\n\n### 定义新工具\n\n项目提供了 `defineTool` 辅助函数用于标准化工具定义：\n\n```typescript\nexport function defineTool(\n tool: Tool,\n): Tool {\n return tool;\n}\n```\n\n**创建新工具的步骤：**\n\n1. 定义 Zod 输入模式\n2. 创建工具模式对象（schema）\n3. 实现 handle 处理函数\n4. 组装并导出工具对象\n5. 在 `index.ts` 中注册工具\n\n### 工具能力分类\n\n工具通过 `capability` 属性进行分类：\n\n| 能力值 | 说明 |\n|--------|------|\n| `core` | 核心工具，MCP 服务器的标准能力 |\n| `extended` | 扩展工具，需额外配置启用 |\n\n资料来源：[src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n\n## 版本变更记录\n\n### v3.0.0 重大变更\n\n根据 CHANGELOG.md，3.0.0 版本对工具集进行了重大调整：\n\n| 旧工具名 | 新工具名 | 变更类型 |\n|----------|----------|----------|\n| `browserbase_session_create` | `start` | 重命名 |\n| `browserbase_session_close` | `end` | 重命名 |\n| `browserbase_stagehand_navigate` | `navigate` | 重命名 |\n| `browserbase_stagehand_act` | `act` | 重命名 |\n| `browserbase_stagehand_observe` | `observe` | 重命名 |\n| `browserbase_stagehand_extract` | `extract` | 重命名 |\n| `browserbase_screenshot` | - | 移除 |\n| `browserbase_stagehand_get_url` | - | 移除 |\n| `browserbase_stagehand_agent` | - | 移除 |\n\n**其他变更：**\n\n- `act` 工具不再接受 `variables` 参数\n- `start` 工具不再接受 `sessionId` 参数\n- `extract` 工具的 `instruction` 参数改为可选\n- 默认模型从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`\n\n资料来源：[CHANGELOG.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/CHANGELOG.md)\n\n## 总结\n\nmcp-server-browserbase 的工具集提供了完整的浏览器自动化能力封装。通过统一的类型系统、清晰的工具定义模式和模块化的架构设计，开发者可以便捷地扩展新的工具功能，同时保持与 MCP 协议的良好兼容性。工具集的核心价值在于将复杂的网页操作抽象为简单的自然语言指令，使 AI Agent 能够以声明式的方式控制浏览器完成各类自动化任务。\n\n---\n\n\n\n## 会话管理\n\n### 相关页面\n\n相关主题：[工具集概述](#page-tools-overview), [配置参数](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [src/tools/session.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/session.ts)\n- [src/tools/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/index.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/tools/extract.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/extract.ts)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n \n\n# 会话管理\n\n## 概述\n\n会话管理是 MCP Server Browserbase 的核心子系统，负责创建、管理和销毁浏览器会话实例。该系统基于 [Stagehand](https://www.stagehand.dev) 构建，通过 Browserbase 云基础设施提供稳定的浏览器自动化能力。\n\n会话管理器在整个 MCP 服务器中扮演中间层角色，连接上层的 MCP 协议处理与下层的 Stagehand 浏览器实例：\n\n- **上层**：接收 MCP 客户端的工具调用请求\n- **中层**：通过 SessionManager 管理会话生命周期和状态同步\n- **下层**：调用 Stagehand SDK 执行实际的浏览器操作 资料来源：[src/context.ts:49-56]()\n\n## 核心组件\n\n### BrowserSession 数据结构\n\n```typescript\ninterface BrowserSession {\n page: Page; // Playwright Page 实例\n sessionId: string; // Browserbase 会话 ID\n stagehand: Stagehand; // Stagehand 实例\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `page` | `Page` | Playwright 页面对象，用于执行浏览器操作 |\n| `sessionId` | `string` | Browserbase 云端会话的唯一标识符 |\n| `stagehand` | `Stagehand` | Stagehand SDK 实例，管理浏览器上下文 |\n\n资料来源：[src/sessionManager.ts:89-93]()\n\n### SessionManager 类\n\nSessionManager 是会话管理的中央控制器，负责维护会话状态机和管理会话集合。\n\n```mermaid\ngraph TD\n subgraph SessionManager 内部状态\n BM[browsers: Map]\n DS[defaultSessionId: string]\n AS[activeSessionId: string]\n DBS[defaultBrowserSession: BrowserSession | null]\n CP[defaultSessionCreationPromise: Promise | null]\n CS[cleaningUpSessions: Set]\n end\n \n subgraph 公共接口\n GI[getOrCreateSession]\n GC[getSession]\n CL[cleanupSession]\n CA[closeAllSessions]\n GA[getActiveSessionId]\n end\n```\n\n#### 关键属性\n\n| 属性 | 类型 | 默认值 | 用途 |\n|------|------|--------|------|\n| `browsers` | `Map` | 新建空 Map | 存储所有活跃会话 |\n| `defaultSessionId` | `string` | `\"default\"` | 默认会话标识符 |\n| `activeSessionId` | `string` | `\"default\"` | 当前活跃会话标识符 |\n| `defaultBrowserSession` | `BrowserSession \\| null` | `null` | 默认会话缓存引用 |\n| `defaultSessionCreationPromise` | `Promise \\| null` | `null` | 创建互斥锁，防止并发创建 |\n| `cleaningUpSessions` | `Set` | 新建空 Set | 跟踪正在清理的会话，防止重复关闭 |\n\n资料来源：[src/sessionManager.ts:75-88]()\n\n## 会话生命周期\n\n### 状态转换图\n\n```mermaid\nstateDiagram-v2\n [*] --> 不存在: 初始化\n 不存在 --> 活跃: createNewBrowserSession\n 活跃 --> 正在清理: cleanupSession / closeAllSessions\n 正在清理 --> 不存在: close 完成\n 活跃 --> 正在清理: 验证失败 (stale)\n 正在清理 --> 活跃: 自动重建 (仅限默认会话)\n```\n\n### 创建会话流程\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Context\n participant SessionManager\n participant Stagehand\n participant Browserbase\n\n Client->>Context: 调用 start 工具\n Context->>SessionManager: ensureDefaultSessionInternal()\n alt 默认会话不存在\n SessionManager->>SessionManager: 设置创建互斥锁\n SessionManager->>Stagehand: createStagehandInstance()\n Stagehand->>Browserbase: 创建云端会话\n Browserbase-->>Stagehand: 返回 sessionId\n Stagehand-->>SessionManager: 返回 Stagehand 实例\n SessionManager->>SessionManager: 存储到 browsers Map\n SessionManager->>SessionManager: 缓存到 defaultBrowserSession\n SessionManager->>SessionManager: 设置 activeSessionId\n else 存在但失效\n SessionManager->>SessionManager: 关闭旧会话\n SessionManager->>SessionManager: 重新创建\n end\n SessionManager-->>Context: BrowserSession\n Context-->>Client: 返回会话信息\n```\n\n#### 创建会话的核心逻辑\n\n```typescript\nasync createNewBrowserSession(\n newSessionId: string,\n config: Config,\n resumeSessionId?: string,\n): Promise\n```\n\n**前置条件校验**：\n\n1. 验证 `config.browserbaseApiKey` 存在\n2. 验证 `config.browserbaseProjectId` 存在\n\n**创建步骤**：\n\n1. 调用 `createStagehandInstance()` 创建 Stagehand 实例\n2. 获取 Playwright Page 实例：`stagehand.context.pages()[0]`\n3. 提取 Browserbase Session ID：`stagehand.browserbaseSessionId`\n4. 构造 BrowserSession 对象并存储到 Map\n\n资料来源：[src/sessionManager.ts:131-175]()\n\n### 验证与重建机制\n\nSessionManager 实现了自动健康检查机制，确保会话可用性：\n\n```mermaid\ngraph TD\n A[获取会话] --> B{会话存在?}\n B -->|否| C[创建新会话]\n B -->|是| D{会话有效?}\n D -->|是| E[返回会话]\n D -->|否| F[关闭失效会话]\n F --> G{是默认会话?}\n G -->|是| H[自动重建]\n G -->|否| I[返回 null]\n H --> C\n```\n\n**有效性检测**：\n\n```typescript\ntry {\n const pages = sessionObj.stagehand.context.pages();\n if (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n }\n} catch {\n // 标记为 stale，执行清理\n}\n```\n\n资料来源：[src/sessionManager.ts:114-130]()\n\n## 工具接口\n\n### 会话管理工具列表\n\n| 工具名称 | 描述 | 功能级别 |\n|----------|------|----------|\n| `start` | 启动新会话 | 核心 |\n| `end` | 关闭会话 | 核心 |\n\n资料来源：[src/tools/index.ts:14-15]()\n\n### start 工具\n\n启动一个新的 Browserbase 会话。\n\n**参数结构**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `resumeSessionId` | `string` | 否 | 可选的 Browserbase Session ID，用于恢复已有会话 |\n\n**返回值**：\n\n```json\n{\n \"sessionId\": \"string\",\n \"debuggerUrl\": \"string\"\n}\n```\n\n### end 工具\n\n优雅关闭指定会话。\n\n**参数结构**：\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `sessionId` | `string` | 是 | 要关闭的会话 ID |\n\n## 并发控制\n\n### 互斥锁模式\n\n为防止多个并发请求同时创建默认会话，SessionManager 实现了 Promise-based 互斥锁：\n\n```typescript\nasync ensureDefaultSessionInternal(config: Config): Promise {\n // 如果创建已在进行中，等待现有 Promise\n if (this.defaultSessionCreationPromise) {\n return await this.defaultSessionCreationPromise;\n }\n\n // 设置互斥锁并开始创建\n this.defaultSessionCreationPromise = (async () => {\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n } finally {\n this.defaultSessionCreationPromise = null; // 解锁\n }\n })();\n\n return await this.defaultSessionCreationPromise;\n}\n```\n\n### 清理状态追踪\n\n使用 Set 跟踪正在清理的会话，防止重复关闭：\n\n```typescript\nasync closeBrowserGracefully(\n session: BrowserSession | undefined | null,\n sessionIdToLog: string,\n): Promise {\n // 检查是否已在清理中\n if (this.cleaningUpSessions.has(sessionIdToLog)) {\n return; // 跳过\n }\n\n this.cleaningUpSessions.add(sessionIdToLog);\n try {\n if (session?.stagehand) {\n await session.stagehand.close();\n }\n } finally {\n this.cleaningUpSessions.delete(sessionIdToLog);\n }\n}\n```\n\n## Context 集成\n\n### SessionManager 在 Context 中的角色\n\nContext 类是 MCP 服务器的主控制器，通过 SessionManager 提供会话访问：\n\n```mermaid\ngraph LR\n subgraph Context\n SM[getSessionManager]\n CS[currentSessionId getter]\n GS[getStagehand]\n end\n \n SM --> |获取| SessionManager\n CS --> |代理| SessionManager.getActiveSessionId\n GS --> |委托| SessionManager.getSession\n```\n\n**关键方法**：\n\n| 方法 | 签名 | 说明 |\n|------|------|------|\n| `getSessionManager()` | `SessionManager` | 返回 SessionManager 实例 |\n| `currentSessionId` | `string` (getter) | 获取当前活跃会话 ID |\n| `getStagehand(sessionId?)` | `Promise` | 获取指定会话的 Stagehand 实例 |\n\n资料来源：[src/context.ts:61-78]()\n\n## 配置要求\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目 ID |\n| `GEMINI_API_KEY` | 否 | Gemini 模型 API 密钥（使用 Gemini 时必需） |\n\n### 命令行参数\n\n| 参数 | 说明 |\n|------|------|\n| `--modelName` | 指定使用的模型名称（如使用非 Gemini 模型） |\n| `--proxies` | 启用代理支持 |\n\n## 错误处理\n\n### 常见错误场景\n\n| 场景 | 错误信息 | 处理方式 |\n|------|----------|----------|\n| API Key 缺失 | `Browserbase API Key is missing in the configuration.` | 阻止会话创建 |\n| Project ID 缺失 | `Browserbase Project ID is missing in the configuration.` | 阻止会话创建 |\n| 会话创建失败 | `Failed to create/connect session ${sessionId}: ${errorMessage}` | 抛出异常，由调用方处理 |\n| 页面不可用 | `No pages available in Stagehand context` | 标记会话为 stale，触发重建 |\n\n### 重试机制\n\n默认会话创建失败后会自动重试一次：\n\n```typescript\n} catch (creationError) {\n // 首次失败，记录错误\n process.stderr.write(`[SessionManager] Initial attempt failed: ${errorMessage}\\n`);\n \n // 重试一次\n try {\n this.defaultBrowserSession = await this.createNewBrowserSession(...);\n } catch (retryError) {\n throw new Error(`Failed after initial error and retry: ${finalErrorMessage}`);\n }\n}\n```\n\n## 与其他模块的交互\n\n```mermaid\ngraph TD\n subgraph MCP Server\n Server[MCP Server]\n Tools[工具处理器]\n end\n \n subgraph Core\n Context[Context]\n SessionManager[SessionManager]\n end\n \n subgraph 工具层\n navigateTool[navigate]\n actTool[act]\n observeTool[observe]\n extractTool[extract]\n end\n \n subgraph 底层\n Stagehand[Stagehand SDK]\n Browserbase[Browserbase Cloud]\n end\n \n Server --> Context\n Tools --> Context.run\n Context --> SessionManager\n SessionManager --> Stagehand\n Stagehand --> Browserbase\n \n navigateTool --> Context.getStagehand\n actTool --> Context.getStagehand\n observeTool --> Context.getStagehand\n extractTool --> Context.getStagehand\n```\n\n## 最佳实践\n\n1. **使用默认会话**：大多数场景下无需指定会话 ID，系统会自动管理\n2. **避免手动关闭会话**：使用 `end` 工具而非直接操作 SessionManager\n3. **监控会话状态**：通过 Browserbase Live Debugger URL 监控会话：`https://www.browserbase.com/sessions/${sessionId}`\n4. **处理并发请求**：系统内置互斥锁，但建议限制并发调用频率\n5. **会话清理**：长时间空闲后再次使用会自动验证并重建会话\n\n---\n\n\n\n## 配置参数\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment), [安装指南](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n- [cli.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/cli.js)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# 配置参数\n\n## 概述\n\n配置参数系统是 mcp-server-browserbase 项目中用于控制 MCP 服务器行为的核心模块。该系统通过整合环境变量、命令行参数和默认配置值，为服务器提供灵活的运行时配置能力。配置参数决定了浏览器会话的创建方式、代理设置、模型选择、视图端口尺寸等关键运行参数。\n\n配置系统的设计遵循分层覆盖原则，优先级顺序为：默认值 < 环境变量 < 命令行参数。这种设计允许用户通过多种途径自定义服务器行为，同时保持合理的默认值以简化初次使用体验。\n\n---\n\n## 配置参数类型\n\n### 环境变量\n\n环境变量是配置服务器的基础方式，特别适用于生产环境部署和 Docker 容器化场景。系统支持以下环境变量：\n\n| 环境变量名 | 说明 | 必填 | 示例 |\n|-----------|------|------|------|\n| `BROWSERBASE_API_KEY` | Browserbase 平台的 API 密钥，用于身份验证 | 是 | `bb_xxxxxxxxxxxx` |\n| `BROWSERBASE_PROJECT_ID` | Browserbase 项目标识符 | 是 | `proj_xxxxxxxxxxxx` |\n| `GEMINI_API_KEY` | Google Gemini API 密钥，用于 AI 模型调用 | 是 | `AIza...` |\n| `GOOGLE_API_KEY` | Google API 密钥的别名 | 否 | `AIza...` |\n\n资料来源：[src/config.ts:30-32](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n系统会优先使用 `GEMINI_API_KEY`，如果未设置则回退到 `GOOGLE_API_KEY`。这一设计提供了配置的灵活性。\n\n### 命令行参数\n\n命令行参数通过 CLI 界面传递，提供细粒度的运行时控制。`CLIOptions` 类型定义了所有支持的命令行标志：\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string;\n modelApiKey?: string;\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\n资料来源：[src/config.ts:8-22](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n---\n\n## 配置数据结构\n\n完整的配置通过 `Config` 类型定义，包含了所有运行时需要的参数：\n\n| 字段 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `browserbaseApiKey` | `string` | `process.env.BROWSERBASE_API_KEY` | Browserbase API 密钥 |\n| `browserbaseProjectId` | `string` | `process.env.BROWSERBASE_PROJECT_ID` | Browserbase 项目 ID |\n| `proxies` | `boolean` | `false` | 是否启用代理 |\n| `verified` | `boolean` | `false` | 是否启用经验证模式 |\n| `advancedStealth` | `boolean` | `false` | 高级隐身模式（`verified` 的别名） |\n| `contextId` | `string` | `undefined` | 浏览器上下文 ID |\n| `persist` | `boolean` | `false` | 是否持久化会话 |\n| `server.port` | `number \\| undefined` | `undefined` | HTTP 服务器端口 |\n| `server.host` | `string \\| undefined` | `undefined` | HTTP 服务器主机 |\n| `viewPort.browserWidth` | `number` | `1024` | 浏览器窗口宽度 |\n| `viewPort.browserHeight` | `number` | `768` | 浏览器窗口高度 |\n| `modelName` | `string` | `google/gemini-2.5-flash-lite` | AI 模型名称 |\n| `modelApiKey` | `string` | `process.env.GEMINI_API_KEY` | 模型 API 密钥 |\n| `keepAlive` | `boolean` | `false` | 是否保持连接活跃 |\n\n资料来源：[config.d.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/config.d.ts)\n\n---\n\n## 配置解析流程\n\n配置解析采用链式合并策略，将不同来源的配置参数按照优先级合并成最终的有效配置。\n\n```mermaid\ngraph TD\n A[默认配置 defaultConfig] --> B{mergeConfig}\n C[CLI 配置 cliConfig] --> B\n B --> D[合并配置 mergedConfig]\n D --> E{normalizeVerifiedConfig}\n E --> F[规范化配置 normalizedConfig]\n F --> G{检查 modelApiKey}\n G -->|未设置| H[使用 GEMINI_API_KEY]\n G -->|已设置| I[保持不变]\n H --> J[最终配置 finalConfig]\n I --> J\n```\n\n`resolveConfig` 函数是配置解析的核心入口，负责协调整个合并过程：\n\n```typescript\nexport async function resolveConfig(cliOptions: CLIOptions): Promise {\n const cliConfig = await configFromCLIOptions(cliOptions);\n // 优先级: 默认值 < 文件配置 < CLI 参数\n const mergedConfig = normalizeVerifiedConfig(\n mergeConfig(defaultConfig, cliConfig),\n );\n\n if (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n }\n\n return mergedConfig;\n}\n```\n\n资料来源：[src/config.ts:35-50](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 配置优先级\n\n配置参数的优先级从低到高排列如下：\n\n1. **默认值** (`defaultConfig`) - 提供最基础的配置值\n2. **环境变量** - 通过 `process.env` 读取\n3. **CLI 参数** (`cliOptions`) - 命令行传入的参数具有最高优先级\n\n这种设计确保了灵活性的同时，用户可以通过命令行快速覆盖任何配置。\n\n---\n\n## 默认配置值\n\n系统预设了一套合理的默认配置值，用户无需修改即可启动服务器：\n\n| 配置项 | 默认值 | 说明 |\n|--------|--------|------|\n| `proxies` | `false` | 默认不启用代理 |\n| `viewPort.browserWidth` | `1024` | 默认窗口宽度 1024px |\n| `viewPort.browserHeight` | `768` | 默认窗口高度 768px |\n| `modelName` | `google/gemini-2.5-flash-lite` | 默认使用 Gemini 2.5 Flash Lite |\n\n```typescript\nconst defaultConfig: Config = {\n browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? \"\",\n browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? \"\",\n proxies: false,\n server: {\n port: undefined,\n host: undefined,\n },\n viewPort: {\n browserWidth: 1024,\n browserHeight: 768,\n },\n modelName: \"google/gemini-2.5-flash-lite\",\n};\n```\n\n资料来源：[src/config.ts:24-36](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n---\n\n## 命令行标志详解\n\n### 代理与安全\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--proxies` | `boolean` | 启用代理支持 |\n| `--verified` | `boolean` | 启用经验证的浏览器模式 |\n| `--advancedStealth` | `boolean` | 高级隐身模式（`--verified` 的别名） |\n\n资料来源：[src/config.ts:8-10](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n### 会话管理\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--contextId` | `string` | 指定浏览器上下文 ID |\n| `--persist` | `boolean` | 启用会话持久化 |\n| `--keepAlive` | `boolean` | 保持连接活跃 |\n\n### 服务器配置\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--port` | `number` | HTTP 服务器监听端口 |\n| `--host` | `string` | HTTP 服务器监听主机 |\n\n### 浏览器视图\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--browserWidth` | `number` | 浏览器窗口宽度（像素） |\n| `--browserHeight` | `number` | 浏览器窗口高度（像素） |\n\n### 模型配置\n\n| 标志 | 类型 | 说明 |\n|------|------|------|\n| `--modelName` | `string` | AI 模型名称（如需使用不同模型必须指定） |\n| `--modelApiKey` | `string` | AI 模型 API 密钥 |\n\n> **注意**：如果需要使用不同的模型，必须通过 `--modelName` 参数指定，并在环境变量或参数中提供对应的 API 密钥。\n\n---\n\n## 配置示例\n\n### 环境变量配置\n\n```bash\nexport BROWSERBASE_API_KEY=\"bb_your_api_key_here\"\nexport BROWSERBASE_PROJECT_ID=\"proj_your_project_id_here\"\nexport GEMINI_API_KEY=\"your_gemini_key_here\"\n```\n\n### Docker 部署配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### NPM 部署配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### 自定义视图端口配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\n \"/path/to/mcp-server-browserbase/cli.js\",\n \"--browserWidth\",\n \"1920\",\n \"--browserHeight\",\n \"1080\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n---\n\n## verified 与 advancedStealth 兼容性\n\n系统维护了向后兼容性，`advancedStealth` 参数作为 `verified` 的别名存在。配置规范化函数会处理这种映射关系：\n\n```typescript\nexport function normalizeVerifiedConfig(config: Config): Config {\n // 如果设置了 advancedStealth 但未设置 verified，则将 verified 设置为 true\n if (config.advancedStealth && !config.verified) {\n return { ...config, verified: true };\n }\n return config;\n}\n```\n\n资料来源：[src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n\n当同时设置 `verified` 和 `advancedStealth` 时，`verified` 的值优先：\n\n| verified | advancedStealth | 最终 verified 值 |\n|----------|-----------------|------------------|\n| `true` | `true` | `true` |\n| `false` | `true` | `false` |\n| `undefined` | `true` | `true` |\n\n---\n\n## 相关命令脚本\n\n项目在 `package.json` 中定义了与配置相关的构建和测试脚本：\n\n| 脚本命令 | 说明 |\n|---------|------|\n| `pnpm build` | 编译 TypeScript 代码并设置执行权限 |\n| `pnpm prepare` | 准备阶段：运行 husky 和构建 |\n| `pnpm inspect` | 使用 MCP inspector 检查服务器 |\n| `pnpm test` | 运行单元测试 |\n\n```json\n{\n \"scripts\": {\n \"build\": \"tsc && shx chmod +x dist/*.js\",\n \"prepare\": \"husky && pnpm build\",\n \"inspector\": \"npx @modelcontextprotocol/inspector build/index.js\",\n \"test\": \"vitest run\"\n }\n}\n```\n\n资料来源：[package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n\n---\n\n\n\n## 部署指南\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [配置参数](#page-configuration), [MCP 客户端集成](#page-mcp-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n- [src/transport.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/transport.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [cli.js](https://github.com/browserbase/mcp-server-browserbase/blob/main/cli.js)\n \n\n# 部署指南\n\n本页面详细说明如何部署和配置 Browserbase MCP 服务器。该服务器基于 Model Context Protocol (MCP) 构建，通过 Browserbase 和 Stagehand 实现 AI 网页自动化功能。\n\n## 部署架构概览\n\nBrowserbase MCP 服务器支持两种主要的运行时部署模式：\n\n```mermaid\ngraph TD\n A[用户 MCP 客户端] --> B{传输协议选择}\n B -->|SHTTP| C[Browserbase 托管服务
https://mcp.browserbase.com/mcp]\n B -->|STDIO| D[本地 MCP 服务器]\n C --> E[Gemini 模型]\n D --> F[Browserbase Cloud]\n D --> G[本地浏览器]\n F --> H[Stagehand 引擎]\n G --> H\n```\n\n## 前提条件\n\n| 要求 | 说明 |\n|------|------|\n| Node.js | 版本 18.x 或更高 |\n| Docker | 仅在使用 Docker 部署时需要 |\n| Browserbase 账户 | 用于获取 API Key 和 Project ID |\n| Gemini API Key | 用于 AI 模型调用 |\n\n## 安装方式\n\n### 方式一：直接安装\n\n通过 Git 克隆源码后自行编译：\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\n编译完成后，CLI 入口文件位于 `cli.js`，可通过以下命令验证：\n\n```bash\nnode cli.js --version\n```\n\n资料来源：[README.md:1-12]()\n\n### 方式二：使用 NPM 包\n\n通过 npx 直接运行官方发布的 NPM 包：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:65-77]()\n\n### 方式三：Docker 部署\n\n使用 Docker 构建自定义镜像：\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\ndocker build -t mcp-browserbase .\n```\n\nDocker 部署特别适合隔离环境依赖，或在不支持 Node.js 的系统上运行。\n\n资料来源：[README.md:8-11]()\n\n## 环境变量配置\n\nMCP 服务器运行时需要以下环境变量：\n\n| 环境变量 | 必填 | 说明 |\n|---------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目标识符 |\n| `GEMINI_API_KEY` | 条件必填 | Gemini 模型 API 密钥（当 `modelApiKey` 未设置时使用） |\n| `GOOGLE_API_KEY` | 条件必填 | 备用 Gemini API 密钥 |\n\n服务器启动时会优先使用 `modelApiKey` 配置参数，其次回退到 `GEMINI_API_KEY`，最后使用 `GOOGLE_API_KEY`。\n\n资料来源：[src/config.ts:30-35]()\n\n## 命令行配置选项\n\n服务器支持丰富的命令行参数配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `--browserbaseApiKey` | string | 环境变量 | Browserbase API 密钥 |\n| `--browserbaseProjectId` | string | 环境变量 | Browserbase 项目 ID |\n| `--proxies` | boolean | false | 启用 Browserbase 代理 |\n| `--verified` | boolean | false | 启用 Browserbase 验证身份（仅限 Scale 计划用户） |\n| `--advancedStealth` | boolean | false | 已弃用，与 `--verified` 等效 |\n| `--contextId` | string | - | Browserbase 上下文 ID |\n| `--persist` | boolean | false | 持久化会话 |\n| `--port` | number | - | HTTP 传输监听端口 |\n| `--host` | string | - | HTTP 传输监听主机 |\n| `--browserWidth` | number | 1024 | 浏览器视口宽度 |\n| `--browserHeight` | number | 768 | 浏览器视口高度 |\n| `--modelName` | string | google/gemini-2.5-flash-lite | 使用的 AI 模型名称 |\n| `--modelApiKey` | string | - | 模型 API 密钥 |\n| `--keepAlive` | boolean | - | 保持连接活跃 |\n| `--experimental` | boolean | false | 启用实验性功能 |\n\n资料来源：[src/config.ts:7-24]()\n\n## 传输协议配置\n\n### STDIO 传输模式\n\nSTDIO 是本地进程间通信的标准方式，适合桌面 MCP 客户端（如 Claude Desktop、Cursor）。\n\n#### 直接安装配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n#### Docker 配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:18-60]()\n\n### SHTTP 传输模式\n\nSHTTP (Streamable HTTP) 是现代化的传输协议，支持服务端推送和流式响应。\n\n#### 托管服务（推荐）\n\nBrowserbase 提供托管 MCP 服务器，无需本地运行：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n如果客户端不支持原生 SHTTP，可使用 `mcp-remote` 代理：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:82-102]()\n\n#### 自托管 HTTP 服务\n\n使用 `--port` 和 `--host` 参数启动自托管 HTTP 服务器：\n\n```bash\nnode cli.js --port 8080 --host 0.0.0.0\n```\n\n服务器启动后会输出配置信息：\n\n```\nListening on http://localhost:8080\nPut this in your client config:\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:8080/mcp\"\n }\n }\n}\nIf your client supports streamable HTTP, you can use the /mcp endpoint instead.\n```\n\n资料来源：[src/transport.ts:1-45]()\n\n## 部署拓扑图\n\n```mermaid\ngraph LR\n subgraph \"客户端层\"\n A[MCP 客户端]\n end\n \n subgraph \"传输层\"\n B[STDIO]\n C[HTTP/SHTTP]\n end\n \n subgraph \"服务层\"\n D[本地部署]\n E[托管服务
mcp.browserbase.com]\n end\n \n subgraph \"后端服务\"\n F[Browserbase Cloud]\n G[Gemini API]\n end\n \n A --> B\n A --> C\n B --> D\n C --> D\n C --> E\n D --> F\n D --> G\n E --> F\n E --> G\n```\n\n## 完整配置示例\n\n### 完整 STDIO 配置（本地部署）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\n \"/usr/local/bin/mcp-server-browserbase/cli.js\",\n \"--modelName\",\n \"google/gemini-2.5-flash-lite\",\n \"--browserWidth\",\n \"1920\",\n \"--browserHeight\",\n \"1080\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key-here\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id-here\",\n \"GEMINI_API_KEY\": \"your-gemini-key-here\"\n }\n }\n }\n}\n```\n\n### 使用代理的配置\n\n```bash\nnode cli.js --proxies --verified\n```\n\n### 自定义模型配置\n\n如需使用不同的 AI 模型，添加 `--modelName` 参数并提供相应的 API 密钥：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-3-5-sonnet\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"MODEL_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[src/config.ts:22]()\n\n## 部署验证\n\n部署完成后，可通过以下方式验证：\n\n1. **CLI 版本检查**：运行 `node cli.js --version`\n2. **MCP Inspector**：使用官方检查器测试工具连接\n ```bash\n npm run inspector\n ```\n3. **功能测试**：使用 MCP 客户端发送测试请求到服务器\n\n资料来源：[package.json:34]()\n\n## 常见部署问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 连接超时 | 检查防火墙设置，确保端口可访问 |\n| API Key 无效 | 验证 Browserbase 和 Gemini 密钥是否正确 |\n| 浏览器启动失败 | 检查系统是否安装 Chromium，Docker 模式下确保沙箱配置正确 |\n| 会话不稳定 | 添加 `--keepAlive` 参数保持连接 |\n\n## 版本信息\n\n当前稳定版本为 **3.0.0**，主要变化包括：\n\n- 工具名称与托管服务对齐\n- 默认模型更新为 `google/gemini-2.5-flash-lite`\n- 移除 Smithery 相关依赖\n\n资料来源：[package.json:3-4]()\n\n---\n\n\n\n## MCP 客户端集成\n\n### 相关页面\n\n相关主题：[部署指南](#page-deployment), [工具集概述](#page-tools-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/server.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/server.ts)\n- [src/context.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/context.ts)\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/program.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/program.ts)\n- [src/tools/tool.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/tools/tool.ts)\n- [src/mcp/resources.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/mcp/resources.ts)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# MCP 客户端集成\n\n## 概述\n\nMCP 客户端集成是指将 Browserbase MCP 服务器与支持 Model Context Protocol 的客户端应用（如 Claude Desktop、Cursor、Cody 等）进行连接的配置过程。该服务器基于 `@modelcontextprotocol/sdk` 构建，提供浏览器自动化能力，允许 AI 助手通过自然语言控制浏览器执行网页导航、元素交互和数据提取等操作。\n\n资料来源：[src/index.ts:1-25]()\n\n## 架构设计\n\n### 服务器层级结构\n\n```mermaid\ngraph TD\n A[MCP 客户端
Claude Desktop / Cursor] --> B[MCP Server
McpServer 实例]\n B --> C[Context 上下文
会话管理器]\n C --> D[SessionManager
浏览器会话管理]\n D --> E[Stagehand 实例
浏览器自动化]\n F[Tools 工具集
start/navigate/act/observe/extract] --> B\n```\n\nBrowserbase MCP 服务器采用分层架构设计：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 协议层 | `McpServer` | 处理 MCP 协议通信，注册工具和资源 |\n| 业务层 | `Context` | 执行工具逻辑，管理工具生命周期 |\n| 会话层 | `SessionManager` | 管理多个浏览器会话，验证会话状态 |\n| 自动化层 | `Stagehand` | 基于 Playwright 的浏览器自动化执行 |\n\n资料来源：[src/server.ts:3-27]()[src/context.ts:1-50]()\n\n### 工具注册机制\n\n服务器启动时，所有工具通过统一接口注册到 MCP 协议层：\n\n```typescript\n// 伪代码展示工具注册流程\ntools.forEach((tool) => {\n server.tool(\n tool.schema.name, // 工具名称\n tool.schema.description, // 工具描述\n tool.schema.inputSchema.shape, // 输入参数 schema\n async (params) => {\n const result = await context.run(tool, params);\n return result;\n }\n );\n});\n```\n\n资料来源：[src/index.ts:45-70]()\n\n## 支持的传输方式\n\n### 传输方式对比\n\n| 传输方式 | 说明 | 推荐场景 | 配置复杂度 |\n|----------|------|----------|------------|\n| **STDI O** | 标准输入输出流 | 本地运行、自托管 | 低 |\n| **SHTTP** | Server-Sent HTTP | 托管服务、远程访问 | 中 |\n| **Docker** | 容器化部署 | 生产环境隔离 | 中 |\n\n资料来源：[README.md:1-80]()\n\n### STDIO 传输配置\n\nSTDIO 传输适用于本地部署场景，服务器通过标准输入输出与客户端通信。\n\n**NPM 方式（推荐）**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n**本地构建方式**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:30-60]()\n\n### SHTTP 传输配置\n\nSHTTP（Server-Sent HTTP）传输允许客户端通过 HTTP 协议连接到托管的 MCP 服务器：\n\n**支持 SHTTP 的客户端**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.browserbase.com/mcp\"\n }\n }\n}\n```\n\n**不支持 SHTTP 的客户端**\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"mcp-remote\", \"https://mcp.browserbase.com/mcp\"]\n }\n }\n}\n```\n\n资料来源：[README.md:62-85]()\n\n### Docker 部署配置\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"BROWSERBASE_API_KEY\",\n \"-e\",\n \"BROWSERBASE_PROJECT_ID\",\n \"-e\",\n \"GEMINI_API_KEY\",\n \"mcp-browserbase\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"\",\n \"BROWSERBASE_PROJECT_ID\": \"\",\n \"GEMINI_API_KEY\": \"\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:18-28]()\n\n## 配置参数详解\n\n### 环境变量\n\n| 环境变量 | 必需 | 说明 |\n|----------|------|------|\n| `BROWSERBASE_API_KEY` | 是 | Browserbase 平台 API 密钥 |\n| `BROWSERBASE_PROJECT_ID` | 是 | Browserbase 项目标识符 |\n| `GEMINI_API_KEY` | 是 | Google Gemini 模型 API 密钥（用于 AI 驱动的浏览器自动化） |\n| `GOOGLE_API_KEY` | 否 | Google API 密钥备选（当 GEMINI_API_KEY 未设置时使用） |\n\n资料来源：[src/config.ts:40-55]()\n\n### 命令行参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `--browserbaseApiKey` | string | Browserbase API 密钥 |\n| `--browserbaseProjectId` | string | Browserbase 项目 ID |\n| `--proxies` | boolean | 启用 Browserbase 代理 |\n| `--verified` | boolean | 使用 Browserbase 验证身份（仅 Scale 计划可用） |\n| `--advancedStealth` | boolean | 已废弃，等同于 `--verified` |\n| `--contextId` | string | 指定 Browserbase 上下文 ID |\n| `--keepAlive` | boolean | 保持浏览器会话活跃 |\n| `--modelName` | string | 使用的 AI 模型名称（默认：`google/gemini-2.5-flash-lite`） |\n| `--modelApiKey` | string | 模型 API 密钥 |\n\n资料来源：[src/program.ts:28-50]()\n\n### 默认配置\n\n```typescript\nconst defaultConfig: Config = {\n browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? \"\",\n browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? \"\",\n proxies: false,\n server: {\n port: undefined,\n host: undefined,\n },\n viewPort: {\n browserWidth: 1024,\n browserHeight: 768,\n },\n modelName: \"google/gemini-2.5-flash-lite\",\n};\n```\n\n资料来源：[src/config.ts:28-40]()\n\n## 资源与模板\n\n### 资源注册\n\nMCP 协议支持资源管理功能，Browserbase MCP 服务器当前提供了空的资源集合：\n\n```typescript\nexport const RESOURCES = [];\nexport const RESOURCE_TEMPLATES = [];\n\nexport function listResources() {\n return { resources: [] };\n}\n\nexport function listResourceTemplates() {\n return { resourceTemplates: [] };\n}\n\nexport function readResource(uri: string) {\n return { contents: [{ uri, text: `Resource not found: ${uri}` }] };\n}\n```\n\n资料来源：[src/mcp/resources.ts:1-20]()\n\n服务器通过 MCP 协议注册了资源处理器：\n\n```typescript\nserver.server.setRequestHandler(ListResourcesRequestSchema, async () => {\n return listResources();\n});\n\nserver.server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => {\n return { resourceTemplates: RESOURCE_TEMPLATES };\n});\n\nserver.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {\n return readResource(request.params.uri);\n});\n```\n\n资料来源：[src/index.ts:30-45]()\n\n## 工具能力\n\n### 核心工具集\n\n| 工具名称 | 功能 | 输入参数 |\n|----------|------|----------|\n| `start` | 创建新的浏览器会话 | _(无)_ |\n| `end` | 关闭当前浏览器会话 | _(无)_ |\n| `navigate` | 导航到指定 URL | `{ url: string }` |\n| `act` | 执行页面操作 | `{ action: string }` |\n| `observe` | 观察页面可交互元素 | `{ instruction: string }` |\n| `extract` | 从页面提取数据 | `{ instruction?: string }` |\n\n资料来源：[README.md:1-15]()[src/tools/extract.ts:1-55]()\n\n### 工具定义结构\n\n```typescript\nexport type Tool = {\n capability: string; // 能力分类：core\n schema: ToolSchema;\n handle: (context: Context, params: z.output) => Promise;\n};\n\nexport type ToolResult = {\n action?: () => Promise;\n waitForNetwork: boolean;\n};\n```\n\n资料来源：[src/tools/tool.ts:18-30]()\n\n## 服务器生命周期\n\n### 服务端点\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as McpServer\n participant Context as Context\n participant SessionManager as SessionManager\n participant Stagehand as Stagehand\n\n Client->>Server: 初始化连接\n Server->>Context: 创建上下文\n Context->>SessionManager: 初始化会话管理器\n Server->>Server: 注册工具处理器\n Server->>Server: 注册资源处理器\n \n Client->>Server: 工具调用 (tool/Call)\n Server->>Context: 执行工具 (context.run)\n Context->>SessionManager: 获取/创建会话\n SessionManager->>Stagehand: 操作浏览器\n Stagehand-->>SessionManager: 执行结果\n SessionManager-->>Context: 工具结果\n Context-->>Server: MCP 响应\n Server-->>Client: 返回结果\n\n Client->>Server: 关闭连接\n Server->>SessionManager: 关闭所有会话\n Server->>Server: 清理资源\n```\n\n### 服务器管理\n\n```typescript\nexport class ServerList {\n private _servers: Server[] = [];\n private _serverFactory: () => Promise;\n\n async create() {\n const server = await this._serverFactory();\n this._servers.push(server);\n return server;\n }\n\n async close(server: Server) {\n await server.close();\n const index = this._servers.indexOf(server);\n if (index !== -1) this._servers.splice(index, 1);\n }\n\n async closeAll() {\n await Promise.all(this._servers.map((server) => server.close()));\n }\n}\n```\n\n资料来源：[src/server.ts:3-27]()\n\n## 错误处理\n\n### 工具执行错误\n\n当工具执行失败时，错误信息通过 MCP 协议返回：\n\n```typescript\ntry {\n const result = await context.run(tool, params);\n return result;\n} catch (error) {\n const errorMessage = error instanceof Error ? error.message : String(error);\n process.stderr.write(\n `[MCP Error] ${new Date().toISOString()} Error running tool ${tool.schema.name}: ${errorMessage}\\n`,\n );\n throw new Error(`Failed to run tool '${tool.schema.name}': ${errorMessage}`);\n}\n```\n\n资料来源：[src/index.ts:62-73]()\n\n### 会话验证错误\n\n会话管理器会自动检测失效会话并触发重建：\n\n```typescript\ntry {\n const pages = this.defaultBrowserSession.stagehand.context.pages();\n if (!pages || pages.length === 0) {\n throw new Error(\"No pages available\");\n }\n} catch {\n needsReCreation = true;\n // 关闭并重建会话\n await this.closeBrowserGracefully(this.defaultBrowserSession, sessionId);\n this.defaultBrowserSession = null;\n}\n```\n\n资料来源：[src/sessionManager.ts:80-105]()\n\n## 快速开始\n\n### 1. 安装依赖\n\n```bash\ngit clone https://github.com/browserbase/mcp-server-browserbase.git\ncd mcp-server-browserbase\nnpm install && npm run build\n```\n\n### 2. 配置环境变量\n\n创建 `.env` 文件：\n\n```bash\nBROWSERBASE_API_KEY=your_api_key\nBROWSERBASE_PROJECT_ID=your_project_id\nGEMINI_API_KEY=your_gemini_key\n```\n\n### 3. 配置客户端\n\n根据使用的客户端，将以下配置添加到 MCP 配置文件中：\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/mcp-server-browserbase/cli.js\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your_api_key\",\n \"BROWSERBASE_PROJECT_ID\": \"your_project_id\",\n \"GEMINI_API_KEY\": \"your_gemini_key\"\n }\n }\n }\n}\n```\n\n### 4. 重启客户端\n\n重新加载 MCP 客户端以应用配置变更。\n\n## 版本兼容性\n\n### 3.0.0 重大变更\n\n版本 3.0.0 带来了以下破坏性变更，以与托管服务对齐：\n\n| 旧名称 | 新名称 |\n|--------|--------|\n| `browserbase_session_create` | `start` |\n| `browserbase_session_close` | `end` |\n| `browserbase_stagehand_navigate` | `navigate` |\n| `browserbase_stagehand_act` | `act` |\n| `browserbase_stagehand_observe` | `observe` |\n| `browserbase_stagehand_extract` | `extract` |\n\n默认模型已从 `gemini-2.0-flash` 更改为 `google/gemini-2.5-flash-lite`。\n\n资料来源：[CHANGELOG.md:1-30]()\n\n## 相关文档\n\n- [Browserbase MCP 官方文档](https://docs.browserbase.com/integrations/mcp/introduction)\n- [Model Context Protocol 规范](https://modelcontextprotocol.io/docs/concepts/resources)\n- [Stagehand 浏览器自动化](https://www.stagehand.dev)\n\n---\n\n\n\n## 模型配置\n\n### 相关页面\n\n相关主题：[配置参数](#page-configuration), [工具集概述](#page-tools-overview)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/config.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/config.ts)\n- [src/index.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/index.ts)\n- [src/sessionManager.ts](https://github.com/browserbase/mcp-server-browserbase/blob/main/src/sessionManager.ts)\n- [README.md](https://github.com/browserbase/mcp-server-browserbase/blob/main/README.md)\n- [package.json](https://github.com/browserbase/mcp-server-browserbase/blob/main/package.json)\n \n\n# 模型配置\n\n## 概述\n\n模型配置是 Browserbase MCP Server 的核心功能之一，用于控制浏览器自动化操作所使用的 AI 模型。该配置通过 [Stagehand](https://www.stagehand.dev) 框架实现网页自动化操作，包括页面导航（navigate）、元素操作（act）、页面观察（observe）和数据提取（extract）。\n\n默认情况下，服务器使用 Google 的 Gemini 2.5 Flash Lite 模型，该模型在 Stagehand 的自动化评估中表现优异。用户也可以配置其他支持的模型（如 GPT-4o、Claude 等）来满足特定需求。\n\n资料来源：[README.md:1-50]()\n\n## 配置架构\n\nMCP Server 的模型配置遵循以下层次结构：\n\n```mermaid\ngraph TD\n A[默认配置] --> B[环境变量]\n B --> C[CLI 参数]\n C --> D[最终配置]\n \n A1[\"defaultConfig
modelName: google/gemini-2.5-flash-lite\"] --> A\n B1[\"GEMINI_API_KEY
GOOGLE_API_KEY\"] --> B\n C1[\"--modelName
--modelApiKey\"] --> C\n```\n\n配置优先级顺序为：**默认值 < 环境变量 < CLI 参数**\n\n资料来源：[src/config.ts:1-30]()\n\n## 配置参数详解\n\n### 主要配置项\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `modelName` | string | `google/gemini-2.5-flash-lite` | 使用的 AI 模型标识符 |\n| `modelApiKey` | string | 环境变量 | 自定义模型的 API 密钥 |\n| `experimental` | boolean | `false` | 是否启用实验性功能 |\n\n资料来源：[src/index.ts:1-50]()\n\n### CLI 选项定义\n\n```typescript\nmodelName: z\n .string()\n .optional()\n .describe(\n \"The model to use for Stagehand (default: google/gemini-2.5-flash-lite)\",\n ),\nmodelApiKey: z\n .string()\n .optional()\n .describe(\n \"API key for the custom model provider. Required when using a model other than the default google/gemini-2.5-flash-lite\",\n ),\n```\n\n资料来源：[src/index.ts:50-65]()\n\n## 配置验证机制\n\n服务器实现了严格的配置验证逻辑，确保在使用非默认模型时必须提供相应的 API 密钥。\n\n```mermaid\ngraph TD\n A[配置输入] --> B{modelName 是否为默认值?}\n B -->|是| C[无需 API Key]\n B -->|否| D{modelApiKey 是否存在且有效?}\n D -->|是| E[验证通过]\n D -->|否| F[抛出验证错误]\n \n F --> F1[\"modelApiKey is required
when specifying a custom model\"]\n```\n\n### 验证规则\n\n服务器使用 Zod schema 进行配置验证，核心验证逻辑如下：\n\n```typescript\n.refine(\n (data) => {\n // 如果指定了非默认模型，API 密钥是必需的\n if (data.modelName && data.modelName !== \"google/gemini-2.5-flash-lite\") {\n return (\n data.modelApiKey !== undefined &&\n typeof data.modelApiKey === \"string\" &&\n data.modelApiKey.length > 0\n );\n }\n return true;\n },\n {\n message: \"modelApiKey is required when specifying a custom model\",\n path: [\"modelApiKey\"],\n },\n);\n```\n\n资料来源：[src/index.ts:65-85]()\n\n## 环境变量配置\n\n### 优先级顺序\n\n系统按以下顺序查找 API 密钥：\n\n| 优先级 | 环境变量名 | 说明 |\n|--------|------------|------|\n| 1 | `modelApiKey` (CLI) | 通过命令行直接指定 |\n| 2 | `GEMINI_API_KEY` | Gemini 专用环境变量 |\n| 3 | `GOOGLE_API_KEY` | Google 通用 API 密钥 |\n\n```typescript\n// --- Add Browserbase Env Vars ---\nif (!mergedConfig.modelApiKey) {\n mergedConfig.modelApiKey =\n process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY;\n}\n```\n\n资料来源：[src/config.ts:45-50]()\n\n## 配置示例\n\n### 使用默认模型\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\"@browserbasehq/mcp\"],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\",\n \"GEMINI_API_KEY\": \"your-gemini-key\"\n }\n }\n }\n}\n```\n\n### 使用自定义模型（Claude）\n\n```json\n{\n \"mcpServers\": {\n \"browserbase\": {\n \"command\": \"npx\",\n \"args\": [\n \"@browserbasehq/mcp\",\n \"--modelName\",\n \"anthropic/claude-sonnet-4-5\",\n \"--modelApiKey\",\n \"your-anthropic-api-key\"\n ],\n \"env\": {\n \"BROWSERBASE_API_KEY\": \"your-api-key\",\n \"BROWSERBASE_PROJECT_ID\": \"your-project-id\"\n }\n }\n }\n}\n```\n\n资料来源：[README.md:80-100]()\n\n## 支持的模型\n\n根据 Stagehand 的支持列表，用户可以使用以下类型的模型：\n\n| 模型类别 | 示例模型 | 提供商 |\n|----------|----------|--------|\n| Gemini 系列 | `google/gemini-2.5-flash-lite` | Google |\n| Claude 系列 | `anthropic/claude-sonnet-4-5` | Anthropic |\n| GPT 系列 | `openai/gpt-4o` | OpenAI |\n\n> **注意**：自定义模型必须在 Stagehand 支持的模型列表中，具体支持情况请参阅 [Stagehand 文档](https://docs.stagehand.dev/examples/custom_llms#supported-llms)。\n\n资料来源：[README.md:95-100]()\n\n## 完整配置流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant M as MCP Server\n participant C as Config 模块\n participant S as SessionManager\n participant SB as Stagehand\n\n U->>M: 启动服务器 (带模型配置)\n M->>C: resolveConfig(cliOptions)\n C->>C: 合并默认配置\n C->>C: 加载环境变量\n C->>C: 应用 CLI 参数\n C-->>M: 返回最终 Config\n M->>S: 创建会话 (config)\n S->>SB: 初始化 Stagehand\n SB->>SB: 使用配置的 modelName\n \n alt 非默认模型\n C->>C: 验证 modelApiKey 存在\n C-->>M: 验证通过或抛出错误\n end\n```\n\n## 配置代码参考\n\n### 默认配置对象\n\n```typescript\nconst defaultConfig: Config = {\n browserbaseApiKey: process.env.BROWSERBASE_API_KEY ?? \"\",\n browserbaseProjectId: process.env.BROWSERBASE_PROJECT_ID ?? \"\",\n proxies: false,\n server: {\n port: undefined,\n host: undefined,\n },\n viewPort: {\n browserWidth: 1024,\n browserHeight: 768,\n },\n modelName: \"google/gemini-2.5-flash-lite\", // 默认模型\n};\n```\n\n资料来源：[src/config.ts:20-35]()\n\n### CLI 选项类型定义\n\n```typescript\nexport type CLIOptions = {\n proxies?: boolean;\n verified?: boolean;\n advancedStealth?: boolean;\n contextId?: string;\n persist?: boolean;\n port?: number;\n host?: string;\n browserWidth?: number;\n browserHeight?: number;\n modelName?: string; // 模型名称\n modelApiKey?: string; // 模型 API 密钥\n keepAlive?: boolean;\n experimental?: boolean;\n};\n```\n\n资料来源：[src/config.ts:1-25]()\n\n## 依赖关系\n\n模型配置功能的实现依赖于以下核心包：\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `@browserbasehq/stagehand` | ^3.3.0 | 浏览器自动化核心框架 |\n| `@modelcontextprotocol/sdk` | ^1.13.1 | MCP 协议实现 |\n| `zod` | ^3.25.67 | 配置验证 |\n| `commander` | ^14.0.0 | CLI 参数解析 |\n\n资料来源：[package.json:1-30]()\n\n## 常见问题\n\n### 1. 模型配置验证失败\n\n**问题**：使用自定义模型时收到 \"modelApiKey is required\" 错误。\n\n**解决方案**：确保在使用非默认模型时，通过 `--modelApiKey` 参数或 `GEMINI_API_KEY` 环境变量提供了有效的 API 密钥。\n\n### 2. 模型不支持\n\n**问题**：配置的模型在 Stagehand 中不被支持。\n\n**解决方案**：请查阅 [Stagehand 支持的模型列表](https://docs.stagehand.dev/examples/custom_llms#supported-llms)，选择支持的模型。\n\n### 3. API 密钥优先级\n\n**问题**：不确定哪个环境变量会被使用。\n\n**优先级**：`--modelApiKey` > `GEMINI_API_KEY` > `GOOGLE_API_KEY`\n\n## 版本变更记录\n\n| 版本 | 变更内容 |\n|------|----------|\n| 3.0.0 | 默认模型从 `gemini-2.0-flash` 改为 `google/gemini-2.5-flash-lite`，工具名称与托管服务对齐 |\n| 2.4.0 | 新增 stagehand agent 工具支持 |\n| 2.3.0 | 初始阶段hand集成 |\n\n资料来源：[CHANGELOG.md:1-30]()\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：browserbase/mcp-server-browserbase\n\n摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives。\n\n## 1. 安全/权限坑 · 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令: `npx @browserbasehq/mcp`\n- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n\n## 3. 安装坑 · 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：Add MCPpedia security badge to README\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安全/权限坑 · 来源证据：Add policy enforcement for cloud browser sessions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：browserbase/mcp-server-browserbase\n\n摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives。\n\n## 1. 安全/权限坑 · 来源证据：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Browser Automation Platforms Comparison: Browserbase vs. Kernel vs. Alternatives\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3f3713f7877146edb5a3e4a757649326 | https://github.com/browserbase/mcp-server-browserbase/issues/127 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mcp-server-browserbase` 与安装入口 `@browserbasehq/mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令: `npx @browserbasehq/mcp`\n- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | repo=mcp-server-browserbase; install=@browserbasehq/mcp\n\n## 3. 安装坑 · 来源证据：Your MCP server is now indexed on Joy Trust Network\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Your MCP server is now indexed on Joy Trust Network\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_799b517ef2c24dc6af45a04e4fff4c42 | https://github.com/browserbase/mcp-server-browserbase/issues/174 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | README/documentation is current enough for a first validation pass.\n\n## 5. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | last_activity_observed missing\n\n## 6. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 7. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 来源证据：Add MCPpedia security badge to README\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add MCPpedia security badge to README\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49127f0ff1d042b1bb4e2a0ed463a451 | https://github.com/browserbase/mcp-server-browserbase/issues/175 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安全/权限坑 · 来源证据：Add policy enforcement for cloud browser sessions\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add policy enforcement for cloud browser sessions\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7b66fd703d8643c4a3f9b0ffa3b61ce5 | https://github.com/browserbase/mcp-server-browserbase/issues/176 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:899184149 | https://github.com/browserbase/mcp-server-browserbase | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mcp-server-browserbase - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-server-browserbase 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Allow LLMs to control a browser with Browserbase and Stagehand 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-core-components：核心组件。围绕“核心组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-overview：工具集概述。围绕“工具集概述”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-core-components\n输入：用户提供的“核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-overview\n输入：用户提供的“工具集概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-core-components：Step 4 必须围绕“核心组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-overview：Step 5 必须围绕“工具集概述”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/browserbase/mcp-server-browserbase\n- https://github.com/browserbase/mcp-server-browserbase#readme\n- README.md\n- package.json\n- index.js\n- Dockerfile\n- tsconfig.json\n- src/index.ts\n- src/server.ts\n- src/program.ts\n- src/transport.ts\n- src/config.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-server-browserbase 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：browserbase/mcp-server-browserbase\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx @browserbasehq/mcp\n```\n\n来源：https://github.com/browserbase/mcp-server-browserbase#readme\n\n## 来源\n\n- repo: https://github.com/browserbase/mcp-server-browserbase\n- docs: https://github.com/browserbase/mcp-server-browserbase#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_c54342a96f3141908b3d3ae8102ada57"
}