npm package: @sunshanpeng/hybrid-browser
Description: Enhanced MCP browser server with hybrid browser+HTTP mode for AI agents
Latest version: 0.1.2

# HybridBrowser

一个面向 AI Agent 的浏览器能力层，支持真实浏览器操作，采用 **CLI + MCP 双入口**。

- GitHub：<https://github.com/sunshanpeng/hybrid-browser>
- npm：<https://www.npmjs.com/package/@sunshanpeng/hybrid-browser>

## 当前状态（2026-03-01）

- 版本：`0.1.2`
- 阶段：**Phase 1 完成 + CLI MVP 第一版完成**
- 构建：`npm run build` ✅

---

## 30 秒上手（推荐，免源码）

### 方式 A：直接 npx（零安装）

```bash
# 查看帮助
npx -y --package @sunshanpeng/hybrid-browser hybridbrowser --help

# 初始化会话
npx -y --package @sunshanpeng/hybrid-browser hybridbrowser session init --session demo --mode state --json

# 导航
npx -y --package @sunshanpeng/hybrid-browser hybridbrowser nav https://example.com --session demo --headless --json
```

### 方式 B：全局安装

```bash
npm i -g @sunshanpeng/hybrid-browser

hybridbrowser --help
hybridbrowser session init --session demo --mode state --json
```

---

## MCP 接入（Codex / Claude Code 等）

HybridBrowser 的 MCP 入口是 **stdio**。

### 推荐命令（基于 npm 包）

```bash
npx -y --package @sunshanpeng/hybrid-browser hybridbrowser-mcp
```

在 MCP 客户端配置中可写为：

```json
{
  "mcpServers": {
    "hybridbrowser": {
      "command": "npx",
      "args": ["-y", "--package", "@sunshanpeng/hybrid-browser", "hybridbrowser-mcp"]
    }
  }
}
```

### 本地源码方式（开发者）

```bash
npm install
npm run build
npm run mcp:stdio
# 等价于：node dist/index.js
```

接入后可调用工具：

- `browser_navigate`
- `browser_snapshot`
- `browser_click`
- `browser_type`
- `browser_scroll`
- `browser_wait_for`
- `browser_get_content`

建议最小验证流程：

1. `browser_navigate("https://example.com")`
2. `browser_snapshot()`
3. `browser_get_content("text")`

---

## 已实现能力

### MCP（stdio）

- `browser_navigate`
- `browser_snapshot`
- `browser_click`
- `browser_type`
- `browser_scroll`
- `browser_wait_for`
- `browser_get_content`（markdown/text/screenshot）

### CLI（MVP）

- `session init/info/clear`
- `nav`
- `snapshot`
- `act click/type`
- `content`
- `fetch`（基于 Playwright request，复用同会话 Cookie）
- `run`（多步流程编排，单进程保留页面上下文）
- `run --file`（从 YAML/JSON 文件加载流程）
- `resume` / `run-state`（人工接入后恢复）
- `handoff-ui --port 7788`（本地人工接管面板，网页点 Resume）
- `session export/import`（会话目录导出与恢复）
- `act press/wait/select`（补齐关键交互动作）

### 基础反检测

- Playwright + Chromium
- `playwright-extra` + stealth plugin

---

## 快速开始（CLI）

```bash
# 初始化会话
hybridbrowser session init --session demo --mode state --json

# 导出/导入会话
hybridbrowser session export --session demo --out /tmp/hb-export --json
hybridbrowser session import --session demo2 --in /tmp/hb-export/demo --json

# 导航
hybridbrowser nav https://example.com --session demo --headless --json

# HTTP 直请求（复用会话）
hybridbrowser fetch https://example.com --session demo --method GET --json
```

---

## 尚未完成（下一阶段）

- `fetch` 返回体结构化（JSON 自动识别、二进制处理）
- 人工接管（`wait_for_human` + UI）
- MCP 与 CLI 全量能力对齐

---

## 核心设计方向

采用“三层同源”架构，避免能力重复实现：

1. **Core Runtime**：浏览器、会话、HTTP 的统一能力
2. **CLI Adapter**：`hybridbrowser` 子命令（优先用于 Skill）
3. **MCP Adapter**：将同一套能力暴露为 MCP tools

## 会话设计（重点）

为支持“登录 → 浏览 → 填表”多步流程，会话支持双模式：

- `state` 模式：基于 `storageState`，速度快，实现简单
- `profile` 模式：基于 `user-data-dir` 持久 profile，抗风控更稳

详细命令与 JSON 规范见：

- <https://github.com/sunshanpeng/hybrid-browser/blob/main/docs/CLI_SPEC_v0.1.md>
- <https://github.com/sunshanpeng/hybrid-browser/blob/main/docs/CODEX_INTEGRATION.md>

---

## 本地开发

```bash
npm install
npm run dev     # MCP server
npm run build
npm start
```

## 目录（当前）

```text
src/
  cli.ts
  index.ts
  server.ts
  browser.ts
  runtime/
    session.ts
    browser-runtime.ts
  tools/
    navigate.ts
    snapshot.ts
    click.ts
    type.ts
    scroll.ts
    wait.ts
    content.ts
```

## 测试

需求先写测试用例，再开发实现。当前测试与案例对照见：

- <https://github.com/sunshanpeng/hybrid-browser/blob/main/docs/FEATURE_TEST_MATRIX.md>
- <https://github.com/sunshanpeng/hybrid-browser/blob/main/tests/TEST_CASES.md>

核心回归用例（TC-01 ~ TC-12）已覆盖：

- 会话生命周期（state/profile）、导入导出
- 单命令路径（nav/snapshot/content）
- run 多步、run --file、wait_for_human/resume、run-state
- handoff-ui 恢复
- MCP tools/list 能力清单

执行：

```bash
npm run build
npm test
```