# browser-store

<p align="center">
  <strong>浏览器多开管理 CLI</strong> —— 基于 Chrome/Edge 内核多开独立浏览器实例，每个实例独立 profile 与会话数据、独立 CDP 远程调试端口，可把每个实例的浏览器能力通过 <strong>MCP Server</strong> 暴露给 AI 客户端（如 Claude Desktop），并内置 umijs 管理台。
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@bysking/browser-store"><img src="https://img.shields.io/npm/v/@bysking/browser-store" alt="npm version"></a>
  <a href="https://www.npmjs.com/package/@bysking/browser-store"><img src="https://img.shields.io/npm/dt/@bysking/browser-store" alt="npm downloads"></a>
  <a href="https://github.com/bysking/browser-store/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT%20%2B%20商业授权-yellow.svg" alt="License"></a>
  <a href="https://github.com/bysking/browser-store/actions/workflows/ci.yml"><img src="https://github.com/bysking/browser-store/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://github.com/bysking/browser-store"><img src="https://img.shields.io/github/stars/bysking/browser-store" alt="GitHub stars"></a>
</p>

<p align="center">
  <code>npx -y @bysking/browser-store</code>
</p>

## 目录

- [核心能力](#核心能力)
- [安装](#安装)
- [快速开始](#快速开始)
- [命令参考](#命令参考)
- [MCP 接入 Claude Desktop](#mcp-接入-claude-desktop)
- [数据存储](#数据存储)
- [安全说明](#安全说明)
- [架构](#架构)
- [开发](#开发)
- [贡献](#贡献)
- [License](#license)

## 核心能力

| 能力 | 说明 |
|---|---|
| **多开实例** | 每个实例独立 `--user-data-dir` profile 目录，会话 / cookies / 登录态互不影响 |
| **独立 CDP 端口** | 每实例自动分配独立 `--remote-debugging-port`（默认 9222 起，冲突自动 +1 重分配） |
| **MCP Server** | 每实例可暴露为 MCP server，AI 客户端直接操控该浏览器（导航/截图/点击/填表/执行 JS 等 16 个工具） |
| **生命周期** | 新增 / 编辑 / 删除 / 启动 / 关闭 / 重置（清 profile 还原），状态机完整管理 |
| **管理台** | umijs 前端嵌入 CLI，`bs serve` 单端口出全站 |
| **发布** | esbuild 单文件 bundle，`npx` 即装即用，无需安装浏览器驱动 |

## 安装

```bash
npm i -g @bysking/browser-store   # 全局安装
# 或
npx -y @bysking/browser-store     # 免安装直接使用
```

> **要求**：Node.js >= 20.10.0

**从源码构建**：

```bash
git clone https://github.com/bysking/browser-store.git
cd browser-store
pnpm install
pnpm build                       # 产出 dist/cli.cjs + dist/public
node dist/cli.cjs --version      # 验证
```

## 快速开始

```bash
# 1. 探测本机已安装浏览器
bs discover

# 2. 新增实例
bs add work --engine chrome
bs add edge1 --engine edge --headless --urls https://example.com,https://github.com

# 3. 启动 / 停止 / 重启 / 重置
bs start work
bs stop work
bs restart work
bs reset work --yes          # 清空 profile 还原（自定义目录需 --force）

# 4. 即开即用：实例不存在自动创建，命令退出后浏览器保持运行
bs open work https://example.com

# 5. 查看状态 / 日志
bs ls
bs info work
bs logs work --follow

# 6. 启动常驻服务（API + 管理台 + HTTP MCP）
bs serve
# 浏览器打开 http://localhost:3210 进入管理台

# 7. 让 AI 操控浏览器（MCP）
bs mcp-register work          # 拿到 Claude Desktop 配置片段
```

### 帮助

```bash
$ bs --help

用法: bs [options] [command]

浏览器多开管理 CLI — 独立 profile / 独立 CDP 端口 / 每实例 MCP Server

选项:
  -v, --version              输出版本号
  -h, --help                 display help for command

命令:
  serve [options]            启动常驻服务（HTTP API + umijs 管理台 + 实例生命周期 + HTTP MCP）
  open [options] <name> [url] 即开即用：打开（必要时创建）实例并导航到 URL，命令退出后浏览器保持运行
  add [options] <name>       新增浏览器实例
  ls|list [options]          列出所有实例及状态
  start <name>               启动实例
  stop <name>                停止实例
  restart <name>             重启实例
  reset [options] <name>     重置实例：停止 + 清空 profile 还原（默认需确认）
  prune [options] [name]     清理实例的可再生缓存/指标目录（需先停止，不影响会话数据）
  rename <name> <newName>    重命名实例
  rm|remove [options] <name> 删除实例（需先停止）。默认保留 profile，--purge 连带删除
  mcp <name>                 为实例启动 stdio MCP server（供 Claude Desktop 等 AI 客户端接入）
  mcp-register <name>        打印/写入该实例的 Claude Desktop mcpServers 配置片段
  discover                   探测本机已安装浏览器
  doctor                     诊断：node 版本、浏览器、端口、CDP 可达性
  logs [options] <name>      查看实例日志
  info <name>                查看实例完整配置 + 状态 + CDP/MCP 地址
```

## 命令参考

| 命令 | 说明 |
|---|---|
| `bs serve [--port] [--host] [--stop-all-on-exit]` | 常驻服务：HTTP API + 管理台 + 生命周期 + HTTP MCP |
| `bs open <name> [url] [--engine]` | 即开即用：打开（必要时创建）实例并导航，命令退出浏览器保持运行 |
| `bs add <name> [--engine] [--profile-dir] [--debug-port] [--mcp-port] [--headless] [--urls] [--mcp-transport]` | 新增实例 |
| `bs ls / list [--json]` | 列出实例及状态 |
| `bs start / stop / restart <name>` | 启停 / 重启 |
| `bs reset <name> [--yes] [--no-start]` | 重置：停止 + 清空 profile 还原 |
| `bs rename <name> <newName>` | 重命名 |
| `bs rm <name> [--yes] [--purge]` | 删除实例（交互选择是否连带删 profile，`--purge` 连带删） |
| `bs mcp <name>` | 为该实例启动 stdio MCP server |
| `bs mcp-register <name>` | 打印 Claude Desktop mcpServers 配置片段 |
| `bs discover` | 探测本机浏览器 |
| `bs doctor` | 诊断：node / 浏览器 / 端口 / CDP 可达性 |
| `bs logs <name> [--follow] [--tail N]` | 查看 / 跟随日志 |
| `bs info <name>` | 完整配置 + 状态 + CDP/MCP 地址 |

## MCP 接入 Claude Desktop

对任一实例执行 `bs mcp-register <name>`，把输出的片段加入 Claude Desktop 配置，即可让 AI 直接操控该实例（详见 [docs/claude-desktop-setup.md](docs/claude-desktop-setup.md)）。

**HTTP 模式**：`bs serve` 后每个运行中的实例暴露 `http://localhost:<port>/mcp/<instanceId>`（Streamable HTTP），任何标准 MCP 客户端可连接。

## 数据存储

全部 JSON 存储于本地（可用 `BS_HOME` 覆盖根目录）：

```
~/.browser-store/
├── instances.json   # 实例配置（用户可编辑）
├── state.json       # 运行时状态（daemon 独占写）
├── daemon.json      # daemon 发现信息（CLI 路由用）
├── profiles/<id>/   # 受管 profile 目录
└── logs/<id>.log    # 实例日志
```

## 安全说明

- CDP 调试端点仅监听 `127.0.0.1`，启动参数含 `--remote-allow-origins=*`（Chrome 111+ CDP WebSocket 必需），仅限本地可信环境
- `reset` 默认只清受管目录的 profile；自定义目录需 `--force` 并确认，防误删用户数据
- `bs serve` 退出默认**不杀**已启动的浏览器（`--stop-all-on-exit` 才全停），实例可被下次启动的 daemon 收养

## 架构

```
browser-store/
├── bin/bs.ts           # CLI 入口（esbuild bundle）
├── src/
│   ├── cli.ts          # commander 命令定义
│   ├── commands.ts     # 命令实现
│   ├── serve.ts        # 常驻服务 + daemon.json + 孤儿收养
│   ├── config/         # instances.json / state.json / 路径
│   ├── engines/        # BrowserEngine 可插拔（chrome / edge）
│   ├── instance/       # 端口分配 / spawn / 状态机 / 进程管理
│   ├── cdp/session.ts  # chrome-remote-interface 封装
│   ├── mcp/            # MCP 工具 + stdio + Streamable HTTP
│   └── api/            # REST + SSE 事件流
├── web/                # umijs 管理台（构建产物嵌入 dist/public）
└── docs/
```

详细规划见 [docs/architecture-plan.md](docs/architecture-plan.md)，功能与使用技巧见 [docs/help-center.md](docs/help-center.md)。

## 开发

```bash
pnpm install
pnpm exec tsx bin/bs.ts --help     # dev 运行
pnpm typecheck                     # 类型检查
pnpm lint                          # 代码规范检查
pnpm build                         # esbuild bundle + web 构建 + 静态拷贝
node dist/cli.cjs --version        # 产物运行
pnpm test                          # 单元测试
```

## 贡献

欢迎参与贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发环境、提交规范与 PR 流程。提交前请确保 `pnpm typecheck`、`pnpm lint`、`pnpm test` 全部通过。

## License

本项目采用 **MIT + 商业授权** 双许可模式：

- **个人 / 开源 / 学术用途**：遵循 MIT 许可，完全免费
- **商业用途**：需取得作者书面授权，详见 [LICENSE](LICENSE)