Brave MCP

勇敢的mcp

brave-mcp 是一个完整的本地控制栈，允许Codex通过MCP操作Brave浏览器。

它由三个相互配合的部分组成：

• Brave兼容的MV3扩展
• 拥有配对、路由和运行时状态的localhost守护进程
• Codex可以在本地注册的MCP服务器

目标不仅仅是“浏览器自动化”，而是一个可共享的浏览器控制产品，具有干净的安装故事、明确的安全边界和稳定的工具合同。

这个项目做什么

随着 brave-mcp，食品法典委员会可以：

• 检查和切换选项卡和窗口
• 浏览页面并等待页面状态更改
• 查询DOM状态和可见文本
• 单击、键入、滚动、拖动、上传文件，然后按键
• 捕获屏幕截图、PDF、控制台日志、Cookie和网络跟踪
• 应用页面范围的覆盖，如用户代理和媒体模拟
• 拦截请求、模拟响应、限制网络和导出会话状态

此仓库包含该工具表面的实现和机器可读合约。

入门指南

构建工作区，启动本地守护进程，然后从加载解压缩的扩展 apps/extension/dist 在 brave://extensions 并对其进行配置 ws://127.0.0.1:39200/extension/connect 加上配对密码 daemon-config.json连接扩展后，在Codex中注册MCP服务器 codex mcp add brave-mcp --env BRAVE_MCP_CONFIG_DIR=/tmp/brave-mcp-smoke -- node /absolute/path/to/apps/mcp/dist/index.js，开始新的Codex会议，并从那里使用Brave工具。有关完整的分步流程，请参阅 docs/local-install.md.

演示形状

预期的交互模型很简单：

1. Codex调用MCP工具，例如 open_tab, query_selector，或 capture_screenshot
2. MCP服务器验证请求并将其转发给本地守护进程
3. 守护进程将其路由到配对的Brave扩展
4. 扩展执行浏览器操作并返回键入的结果

守护程序RPC示例：

{
  "id": "req_123",
  "method": "tabs.navigate",
  "params": {
    "tabId": 401,
    "url": "https://example.com",
    "waitUntil": "load",
    "timeoutMs": 15000
  },
  "authToken": "redacted"
}

示例结果：

{
  "id": "req_123",
  "ok": true,
  "result": {
    "url": "https://example.com/",
    "status": "ok"
  }
}

为什么建筑看起来像这样

该项目有意采用三层设计。

1.延期

该扩展是唯一直接与Brave浏览器API和页面DOM对话的部分。

它处理：

• 选项卡和窗口API
• 通过注入脚本进行DOM交互
• 屏幕截图、下载、调试器支持的网络挂钩和其他浏览器功能
• 用户可见的配对和健康UI

2.守护进程

守护进程是Codex和浏览器之间仅限本地主机的控制平面。

它处理：

• 配对秘密生成与验证
• 扩展连接生命周期
• 请求路由和超时
• 健康终点
• 无论扩展传输如何演变，RPC语义都是稳定的

3.MCP服务器

MCP服务器是面向Codex的层。

它处理：

• MCP工具注册
• 输入验证
• 映射工具调用到守护进程RPC方法
• Codex的干净误差归一化

这种分离很重要，因为它保持了MCP层的稳定，而浏览器特定的逻辑在扩展和守护进程中保持隔离。

建筑

flowchart LR
    C[Codex] --> M[MCP server]
    M --> D[Local daemon
127.0.0.1]
    D |authenticated WebSocket| E[Brave MV3 extension]
    E --> B[Brave tabs windows DOM debugger APIs]

更多详细信息请参见 docs/architecture.md.

当前状态

该堆栈被实现并作为本地开发系统工作。

当前公共合同：

• 版本： 0.11.0
• 刀具计数： 48
• 守护进程传输：本地主机HTTP+WebSocket网桥
• Codex传输：本地MCP服务器 stdio

当前的机器可读合同存在于这里：

• 刀具目录
• 守护进程RPC架构

建筑设计文档位于此处：

• 实施蓝图

不断发展的交付清单就在这里：

• 工具实施检查表

支持文件：

• 建筑说明
• 本地安装和烟雾测试指南
• 贡献指南

工具覆盖范围

已实现的工具大致按如下方式分组。

浏览器和窗口控件

• list_tabs
• list_windows
• get_active_tab
• get_tab_info
• get_window_info
• open_tab
• new_window
• close_tab
• close_window
• switch_to_tab
• focus_tab
• set_viewport

导航

• navigate
• reload_tab
• back
• forward
• wait_for_navigation
• wait_for_idle

DOM发现和读取操作

• query_selector
• query_elements
• wait_for_selector
• get_visible_text
• get_dom
• elements_from_point

交互

• click
• hover
• type_text
• select_option
• press_key
• scroll_to
• drag_and_drop
• upload_file

捕获和诊断

• capture_screenshot
• capture_pdf
• get_console_logs
• download_asset
• execute_javascript
• network_log
• cookie_access
• session_export
• har_export

交通和存储控制

• request_intercept
• mock_response
• throttle_network
• clear_storage
• grant_permissions

仿真

• set_user_agent
• emulate_media

geolocation_override 是原型，但故意从公共工具列表中删除，因为它在Brave中不够可靠，无法保留在支持的表面中。

安全模型

该项目有意将地方放在首位，并明确授权。

• 守护进程绑定到 127.0.0.1 只有。
• 该扩展使用每个用户的密钥进行身份验证。
• MCP从不直接与浏览器对话；它与守护进程对话。
• 浏览器变异工具是显式和类型化的。
• 该扩展仅在配对后有效。
• 守护进程可以报告运行状况和配对状态，而不会暴露浏览器内容。

这并不是一个看不见的无头浏览器场。浏览器是用户可见的，控制通道是本地的。

仓库的规划

.
├── apps
│   ├── daemon      # localhost bridge and RPC service
│   ├── extension   # Brave-compatible MV3 extension
│   └── mcp         # Codex-facing MCP server
├── docs
│   ├── implementation-blueprint.md
│   └── tool-implementation-checklist.md
├── install         # installer placeholders and packaging notes
├── packages
│   ├── protocol    # shared schemas and contracts
│   └── sdk         # test/simulation helpers
└── specs
    ├── rpc
    └── tools

包装级别说明：

• apps/扩展/README.md
• apps/daemon/README.md
• apps/mcp/README.md
• 包/协议/README.md
• 安装/README.md

地方发展快速启动

先决条件

• 节点 22+
• npm或pnpm
• Brave浏览器
• 支持MCP的Codex CLI

Repo本地安装程序

对于当前的本地仓库流，您可以让安装程序构建工件，创建守护进程配置，注册Codex，并打开Brave进行扩展设置：

./install/brave-mcp-install.sh

看 安装/README.md 用于标记和PowerShell入口点。

构建一切

npm run build:protocol
npm run build:sdk
npm run build:daemon
npm run build:extension
npm run build:mcp

启动守护进程

node apps/daemon/dist/index.js --port 39200 --config-dir /tmp/brave-mcp-smoke

或者让仓库为您启动本地堆栈：

npm run launch:brave

守护进程将其配对密钥写入：

/tmp/brave-mcp-smoke/daemon-config.json

在Brave中加载扩展

1. 打开 brave://extensions
2. 启用 Developer mode
3. 点击 Load unpacked
4. 选择 apps/extension/dist

然后打开扩展选项页面并配置：

• 守护程序URL: ws://127.0.0.1:39200/extension/connect
• 身份验证令牌： secret 从 daemon-config.json

在Codex中注册MCP服务器

codex mcp add brave-mcp --env BRAVE_MCP_CONFIG_DIR=/tmp/brave-mcp-smoke -- node /absolute/path/to/apps/mcp/dist/index.js

之后，开始新的Codex会议，以便更新的工具列表在会议中可见。

有关更完整的分步设置和烟雾测试流程，请参阅 docs/local-install.md.

健康检查

守护进程公开了有用的本地端点：

• GET /healthz
• GET /readyz
• POST /rpc

例子：

curl -s http://127.0.0.1:39200/readyz | jq

预期字段包括：

• ok
• ready
• extensionConnected
• paired

验证命令

回购包括包级验证流程：

npm run verify:protocol
npm run verify:daemon
npm run verify:mcp
npm run verify:extension

这些检查包括：

• 图式与契约有效性
• 具有模拟扩展桥的守护进程RPC行为
• MCP工具接线
• 扩展构建完整性

除此之外，该项目在实施过程中还进行了真正的Brave烟雾测试。

公共分配计划

长期的公共包装模式是：

• 通过Chrome网上应用商店为Brave用户发布扩展程序
• 将守护进程和MCP服务器作为可下载的本地二进制文件或包管理的工件发布
• 提供配置守护进程的安装程序流，打开扩展列表，并在Codex中注册MCP服务器

该计划的架构和安装程序脚手架已经存在于这个仓库中，但完善的公共安装程序/分发管道仍在进行中。

屏幕截图和演示资产

该仓库尚未包含精美的屏幕截图或发布工件。这仍然是缺失的工作，而不是故意的遗漏。目前的重点是实际的运行时堆栈和实时Brave验证。

非目标

本项目有意不试图：

• 一种隐形浏览器自动化框架
• 远程云浏览器网格
• 浏览器开发工具包
• 一个巨大的非类型化“任意运行浏览器魔术”端点

这里的设计偏差是明确的工具、类型化的合同、局部可见性和可修复的行为。

下一步是什么

下一批计划后 0.11.0 在检查表中跟踪，目前目标为：

1. set_timezone
2. cpu_throttle
3. device_metrics_override
4. set_extra_headers
5. download_control

贡献

如果你做出贡献，请保持主要项目规则不变：

只有当所有四个层都存在时，每个工具才被视为已实现：

• 协议模式
• 守护进程网桥支持
• 扩展运行时支持
• MCP暴露

在标记为完成之前，每个工具都应该在至少一个自动或真实的浏览器路径中进行验证。