内容
# 浏览器喷气式飞行员
[](https://github.com/0xABADBABE-ops/browser-jet-pilot/actions/workflows/ci.yml)
## 自豪地宣布！
### v1.0.1 — 上线且稳定 💅
- **API 密钥身份验证** — 使用 `API_KEY` 和 `X-API-Key` 头部确保您的 HTTP 传输安全
- **恒定时间身份验证** — `crypto.timingSafeEqual` 让恶意行为者摸不透
- **完整的测试套件** — 127 个 Vitest 测试，零失败，每次推送都通过 CI
- **开发者工具** — ESLint、Prettier、Husky、lint-staged 都已调好并正常运行
- **CI/CD 管道** — 跨 Node 20/22/24 进行类型检查 → 校验 → 格式检查 → 测试
- **着色器控制工具** — 使用 `browser_disable_shaders` 驯服那些占用大量资源的 WebGL 页面
- **错误修复** — SVG/MathML 处理、正确的浏览器清理、增强的类型安全性
### 让它变得特别 ✨
- **`browser_disable_shaders`** — 阻止 WebGL、冻结 CSS 动画、将 `requestAnimationFrame` 限制在约 1 FPS。适用于那些自以为是视频游戏的页面。
- **`browser_restore_shaders`** — 恢复光彩（WebGL/RAF 需要重新加载页面才能完全恢复，这是浏览器的性质）
## 这是什么？
一个用于浏览器自动化的自行托管的 MCP 服务器。连接到您自己的 Chromium via CDP — 无需订阅，无需云端，无需奇怪的每会话定价。只需您的浏览器、您的基础设施、您的规则。
替换 `@browserbasehq/mcp` 的替代品。相同的 MCP 协议，没有锁定。
## 功能
- **连接到您现有的浏览器** via Chrome DevTools Protocol，或 **启动一个由 Playwright 管理的新浏览器**
- **19 种确定性工具** — 基本浏览器控制无需 LLM
- **MCP 标准输入/输出传输** — 与 Claude Desktop、Cursor、任何 MCP 客户端配合使用
- **MCP HTTP 传输** — 作为服务公开，具有可选的 API 密钥身份验证
- **BrowserAgent** — AI 驱动的自主代理（OpenAI、Anthropic 或自定义端点）
- **BrowserSkill** — 代理框架的标准技能接口
- **多标签页工作流** — 因为一个标签页永远不够
- **截图** — base64 PNG，完整页面或单个元素
- **全面测试** — 127 个测试，Vitest，覆盖率报告
- **提交前钩子** — ESLint + Prettier 严格控制每次提交
## 小通知 🌸
我希望您了解这个仓库包含一个功能强大的工具集 — _极其_ 强大。
它在善意的基础上共享，期望您将这些工具用于教育目的，并对他人不造成伤害。没有任何防护措施、限制或功能标志会限制或改变其原始功能。
就像人们常说的，_武器仅取决于使用它的手的危险性。_ 权力本身是中立的 — 其后果完全由用户的使用意图和纪律决定。
我不会详细说明可能会发生什么或这些工具可能被滥用的许多方式。 如果您找到这个仓库时正在寻找 **_那个_**，您可能已经知道自己在做什么 — 而我不会是那个为您概述那些路径的人。 相反，下面您将找到有关如何 **应该** 使用这些工具的指导，以及它们旨在提供的有价值的实用功能。
请记住：这些工具具有非凡的强大能力，而这种能力完全掌握在您的手中。
如果由于数据泄露、自动化操作、重放机制或其他原因造成任何损害 — 责任不在于工具或这个项目。唯一的责任人是您。 ¯\\\_(ツ)\_/¯
## 快速开始
### 1. 运行带有 CDP 的浏览器
```bash
# 使用 Xvfb + Chromium：
chromium --no-sandbox --remote-debugging-port=9222 --disable-gpu
# 或指向您现有的 Chromium（确保它有 --remote-debugging-port=9222）
```
### 2. 安装并运行
```bash
npm install
npm run build
# 标准输入/输出模式（Claude Desktop、Cursor 等）
node dist/index.js
# HTTP 模式
node dist/index.js --port 3100
```
### 3. 连接到 Claude Desktop
将此内容放入您的 `claude_desktop_config.json` 中：
| 平台 | 配置路径 |
| -------- | ----------------------------------------------------------------- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
```json
{
"mcpServers": {
"browser": {
"command": "node",
"args": ["/absolute/path/to/dist/index.js"],
"env": {
"CDP_URL": "http://localhost:9222"
}
}
}
}
```
## 文档（Mintlify）
项目文档位于 `docs/` — Mintlify 格式，简洁实用。
```bash
npm install # 包括 Mint CLI 作为开发依赖
npm run docs:validate # 检查它是否构建干净
npm run docs:links # 不允许死链接
npm run docs:dev # 在本地浏览
```
## CI/CD
每次推送和 PR 都经过严格测试。工作流程位于 `.github/workflows/ci.yml`。
```
npm ci → typecheck → lint → format:check → test
```
跨 Node 20、22 和 24 — 因为我们不敷衍了事。 （Node 18 被礼貌地请离席 — vitest v4 需要 `styleText` from `node:util`, 它在 20.12.0 中引入。）
## 开发
### 随手可得的脚本
| 命令 | 功能 |
| --------------------------- | --------------------------------------- |
| `npm run build` | 编译 TypeScript → `dist/` |
| `npm run dev` | 开发模式，使用 `tsx`（热更新、快速、美妙） |
| `npm start` | 运行已构建的服务器 |
| `npm run agent` | BrowserAgent CLI |
| `npm run agent:seq` | 确定性工具序列（无需 AI） |
| `npm test` | 运行完整的 127 测试套件 |
| `npm run test:coverage` | 测试 + 覆盖率报告 |
| `npm run test:ui` | Vitest UI（很漂亮！） |
| `npm run lint` | ESLint 检查 |
| `npm run lint:fix` | ESLint 自动修复 |
| `npm run format` | Prettier — 让它变得漂亮 |
| `npm run format:check` | Prettier — 它漂亮吗？ |
| `npm run typecheck` | `tsc --noEmit` 类型安全检查 |
| `npm run reliability:check` | 完整的可靠性测试套件 |
### 提交前魔术
Husky + lint-staged 保持仓库的原始状态：
- `.ts`, `.tsx` → ESLint + Prettier
- `.json`, `.md`, `.yml` → Prettier
```bash
npm install # 钩子自动设置 via prepare 脚本 ✨
```
## Docker
### Compose（简单方式）
```bash
docker compose up -d --build
docker compose ps # 应该显示健康 💚
curl http://localhost:3100/healthz
```
您将获得：
- MCP 端点：`http://localhost:3100/mcp`
- 健康检查：`http://localhost:3100/healthz`
- 容器内置健康检查 `/healthz`
快速烟雾测试：
```bash
npm run agent -- --server-url http://localhost:3100/mcp --sequence \
browser_start "browser_navigate?url=https://example.com" \
"browser_get_content?selector=body&type=text" browser_end
```
> 首次构建需要一点时间 — Playwright Chromium 二进制文件在容器内安装。值得等待。
完整的可靠性测试（健康 + 生命周期 + 提取 + 多标签页，重复 5 次）：
```bash
npm run reliability:check
# 或针对自定义端点：
npm run reliability:check -- http://localhost:3100/mcp
```
### 清理
```bash
docker compose down
```
### 普通 Docker（无 Compose）
```bash
docker build -t browser-jet-pilot:local .
docker run --rm -p 3100:3100 --shm-size=1g \
-e PORT=3100 -e HOST=0.0.0.0 -e LAUNCH=true \
browser-jet-pilot:local
```
### 外部 Chromium（CDP 模式）
```bash
docker run --rm -p 3100:3100 --shm-size=1g \
-e PORT=3100 -e HOST=0.0.0.0 -e LAUNCH=false \
-e CDP_URL=http://host.docker.internal:9222 \
browser-jet-pilot:local
```
在 Linux 上，`host.docker.internal` 不会解析：
```bash
--add-host=host.docker.internal:host-gateway
```
## 工具
### 会话
| 工具 | 描述 |
| --------------- | ------------------------------------------------------------ |
| `browser_start` | 连接到浏览器（或启动一个）。始终调用此工具。 |
| `browser_end` | 关闭当前会话。再见！ |
### 导航
| 工具 | 参数 | 描述 |
| -------------------- | ---------- | ---------------------------- |
| `browser_navigate` | `url` | 访问 URL |
| `browser_new_tab` | `url?` | 打开新标签页 |
| `browser_list_tabs` | — | 列出所有打开的标签页 |
| `browser_switch_tab` | `index` | 切换到标签页索引 |
| `browser_get_info` | — | 当前 URL、标题、视口 |
### 交互
| 工具 | 参数 | 描述 |
| ---------------- | ----------------------------------- | --------------------------- |
| `browser_click` | `selector` | 点击元素 |
| `browser_fill` | `selector`, `value` | 清除并填充输入 |
| `browser_type` | `selector`, `text`, `delay?` | 按字符输入 |
| `browser_select` | `selector`, `value` | 选择下拉选项 |
| `browser_hover` | `selector` | 悬停在元素上 |
| `browser_scroll` | `direction`, `amount?`, `selector?` | 滚动页面或元素 |
### 观察
| 工具 | 参数 | 描述 |
| --------------------- | -------------------------------- | -------------------------- |
| `browser_screenshot` | `fullPage?`, `selector?` | 截图（base64 PNG） |
| `browser_get_content` | `type?`, `selector?` | 提取文本或 HTML |
| `browser_evaluate` | `script` | 在页面上运行 JavaScript |
| `browser_wait_for` | `selector`, `state?`, `timeout?` | 等待元素出现 |
### 着色器控制
| 工具 | 参数 | 描述 |
| ------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `browser_disable_shaders` | `webgl?`, `animations?`, `raf?` | 阻止 WebGL、冻结 CSS 动画、将 RAF 限制在 ~1 FPS。 在导航到高着色器页面之前使用此工具。 |
| `browser_restore_shaders` | — | 删除注入的样式覆盖。 WebGL/RAF 需要重新加载页面才能完全恢复 — 这是浏览器的运作方式。 |
## 配置
### CLI 标志
| 标志 | 环境变量 | 默认 | 功能 |
| ---------------------- | ---------------- | ----------------------- | ------------------------------------------ |
| `--port <n>` | `PORT` | （stdio） | HTTP 传输端口 |
| `--host <host>` | `HOST` | `localhost` | 绑定地址 |
| `--cdp-url <url>` | `CDP_URL` | `http://localhost:9222` | CDP 端点 |
| `--launch` | `LAUNCH=true` | `false` | 启动新的浏览器而不是连接 |
| `--browser-width <n>` | `BROWSER_WIDTH` | `1280` | 视口宽度 |
| `--browser-height <n>` | `BROWSER_HEIGHT` | `720` | 视口高度 |
### 环境
```bash
# .env 文件
CDP_URL=http://localhost:9222
LAUNCH=false
BROWSER_WIDTH=1280
BROWSER_HEIGHT=720
API_KEY=your-secret-api-key # 可选 — 锁定 HTTP 传输
```
### API 密钥身份验证 🔐
在 HTTP 模式下运行服务器时，您可以可选地在 HTTP 传输上设置 API 密钥身份验证：
```bash
export API_KEY=your-secret-api-key
```
然后，客户端在 `X-API-Key` 头部中包含它：
```bash
curl -H "X-API-Key: your-secret-api-key" http://localhost:3100/mcp
```
服务器使用 `crypto.timingSafeEqual` 进行恒定时间比较 — 不会在我们的监视下进行计时攻击。
## 示例
### HTTP 传输
```bash
node dist/index.js --port 3100 --host 0.0.0.0
# → http://0.0.0.0:3100/mcp
# 通过 Streamable HTTP 传输连接任何 MCP 客户端
```
### 启动模式
如果没有浏览器？让 Playwright 处理它：
```bash
node dist/index.js --launch --browser-width 1920 --browser-height 1080
```
## 与 Browserbase MCP 的比较
| 功能 | Browserbase MCP | Browser Jet Pilot |
| ------------------------ | ------------------- | -------------------------------------------------------- |
| 浏览器托管 | Browserbase 云 | 您的容器 💕 |
| 成本 | 每会话定价 | 免费（您的基础设施） |
| `act`（自然语言） | Stagehand + LLM | 使用确定性工具或 BrowserAgent |
| `observe` | Stagehand + LLM | `browser_get_content` + `browser_screenshot` |
| 截图 | 通过 Stagehand | 原生 `browser_screenshot` |
| 标签页管理 | 单页 | 多标签页 ✨ |
| 着色器控制 | ❌ | `browser_disable_shaders` / `browser_restore_shaders` ✨ |
| 数据驻留 | Browserbase 服务器 | 您的服务器，您的数据 |
## 架构
```mermaid
flowchart LR
subgraph App["您的应用程序"]
BS["BrowserSkill"]
BA["BrowserAgent (AI)"]
MC["MCP 客户端<br/>(Claude Desktop, Cursor, etc.)"]
end
BS -->|MCP JSON-RPC| MB["Browser Jet Pilot<br/>(stdio 或 HTTP)"]
BA -->|MCP JSON-RPC| MB
MC -->|MCP JSON-RPC| MB
MB --> PW["Playwright"]
PW -->|CDP| CH["您的 Chromium / Chrome"]
```
## BrowserAgent（AI-Powered） 🤖
一个自主代理，连接到 MCP 服务器并使用 LLM 来确定调用哪些工具、按什么顺序完成您的自然语言任务。
### CLI
```bash
# AI-Powered（需要 OPENAI_API_KEY 或 ANTHROPIC_API_KEY）
npm run agent -- --server-url http://localhost:3100/mcp \
"Go to start.gg and find the latest Tekken 7 tournament"
# Anthropic 口味
npm run agent -- --server-url http://localhost:3100/mcp \
--ai-provider anthropic --ai-model claude-sonnet-4-20250514 \
"Navigate to example.com and extract all links"
# 确定性模式（无需 AI，直接使用工具序列）
npm run agent -- --server-url http://localhost:3100/mcp --sequence \
browser_start \
"browser_navigate?url=https://example.com" \
browser_screenshot \
browser_end
```
### 编程方式
```typescript
import { BrowserAgent } from 'browser-jet-pilot/agent'
const agent = new BrowserAgent({
serverUrl: 'http://localhost:3100/mcp',
aiProvider: 'openai',
aiModel: 'gpt-4o',
// aiApiKey: 'sk-...', // 或设置 OPENAI_API_KEY
maxSteps: 20,
})
// AI-Powered 任务
const result = await agent.run(
'Go to start.gg/tournament/12345 and get the bracket'
)
console.log(result.summary)
console.log(
`步骤：${result.steps.length}，截图：${result.screenshots.length}`
)
// 确定性序列
const result2 = await agent.executeSequence([
{ tool: 'browser_start' },
{ tool: 'browser_navigate', args: { url: 'https://example.com' } },
{ tool: 'browser_screenshot' },
])
await agent.disconnect()
```
### 代理配置
| 选项 | 环境变量 | 默认 | 功能 |
| --------------- | ---------------- | --------------------- | -------------------------- |
| `serverUrl` | — | — | MCP 服务器 HTTP 端点 |
| `serverCommand` | — | `node` | MCP 服务器命令（stdio） |
| `serverArgs` | — | `['./dist/index.js']` | MCP 服务器参数（stdio） |
| `aiProvider` | — | `openai` | `openai` 或 `anthropic` |
| `aiModel` | — | `gpt-4o` | LLM 模型名称 |
| `aiApiKey` | `OPENAI_API_KEY` | — | 您的 API 密钥 |
| `aiBaseUrl` | — | 提供者默认值 | 自定义端点 |
| `maxSteps` | — | `30` | 任务安全限制 |
## BrowserSkill（代理框架集成） 🧩
一个标准化技能包装器，准备好插入任何代理框架。带有快速帮助方法和自动截图保存。
### 编程方式
```typescript
import { BrowserSkill } from 'browser-jet-pilot/skill'
const skill = new BrowserSkill({
serverUrl: 'http://localhost:3100/mcp',
saveScreenshots: true,
screenshotDir: './screenshots',
})
await skill.init()
// AI-Powered 浏览器任务
const result = await skill.execute(
'Go to start.gg and extract tournament data',
{ workDir: './workspace' }
)
console.log(result.summary) // "Found 3 tournaments..."
console.log(result.files) // ['./screenshots/step-3-1712...png']
console.log(result.metadata) // steps, duration, tool calls
// 快速帮助方法（无需 AI）
const page = await skill.goto('https://example.com')
const content = await skill.read('https://example.com', '#main-content')
const { base64, file } = await skill.capture('https://example.com', true)
const links = await skill.extract(
'https://example.com',
'Array.from(document.querySelectorAll("a")).map(a => ({text: a.innerText, href: a.href}))'
)
await skill.destroy()
```
### 技能接口
```typescript
interface SkillResult {
success: boolean
summary: string
files: string[] // 已保存的截图路径
data?: any // 从最后一步解析的 JSON
metadata: {
steps: number
screenshots: number
totalDuration: number
toolCalls: Array<{ tool: string; args: Record<string, unknown> }>
}
}
```
## 要求
- Node.js >= 20.12.0
- 带有 `--remote-debugging-port=9222` 的 Chromium（或启动模式）
- 用于 Playwright 浏览器启动：`npx playwright install chromium`
## 许可
MIT
由 head 设计、编写和编码，仅供您使用 `0xabadbabe`（Sudo Qt — jet'aime）
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器