# Patchright MCP Server

一个基于 [Patchright](https://github.com/nichlabs/patchright) 的 MCP (Model Context Protocol) 服务器，支持从 Chrome/Edge/Chromium 浏览器继承登录状态进行浏览器自动化操作。

## 特性

- **会话继承**: 支持从本地浏览器复制 Cookies、LocalStorage、IndexedDB 和 Session Storage
- **跨平台 Cookie 解密**: 支持 macOS (Keychain)、Windows (DPAPI) 和 Linux (libsecret)
- **隐蔽自动化**: 基于 Patchright 的反检测技术
- **完整的 MCP 工具集**: 浏览、交互、提取、导航、关闭

## 安装

```bash
npm install
npm run build
```

### 安装 Patchright 浏览器

```bash
npx patchright install chromium
```

## 使用方法

### 作为 MCP 服务器运行

```bash
npm start
```

### 开发模式

```bash
npm run dev
```

### Claude Desktop 配置

在 Claude Desktop 配置文件中添加:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "patchright": {
      "command": "node",
      "args": ["/path/to/patchright-mcp/dist/index.js"]
    }
  }
}
```

## MCP 工具

### 1. `browse` - 启动浏览器并导航

启动浏览器并导航到指定 URL，支持从本地浏览器继承会话状态。

**参数:**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|------|------|------|--------|------|
| url | string | 是 | - | 要访问的 URL |
| headless | boolean | 否 | false | 是否无头模式 |
| waitFor | number | 否 | 1000 | 页面加载等待时间 (ms) |
| userDataDir | string | 否 | - | 源浏览器用户数据目录路径 |
| browser | "chrome" \| "edge" \| "chromium" | 否 | "chrome" | 源浏览器类型 |
| profile | string | 否 | "Default" | 浏览器配置文件名 |
| inheritSession | boolean | 否 | true | 是否继承会话状态 |

**示例:**
```
使用 browse 工具访问 https://github.com，继承 Chrome 的登录状态
- userDataDir: ~/Library/Application Support/Google/Chrome
- browser: chrome
```

### 2. `interact` - 页面交互

在页面上执行点击、填充、选择等操作。

**参数:**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| browserId | string | 是 | 浏览器 ID |
| pageId | string | 是 | 页面 ID |
| action | "click" \| "fill" \| "select" \| "scroll" \| "hover" \| "press" \| "wait" | 是 | 操作类型 |
| selector | string | 否 | CSS 选择器 |
| value | string | 否 | fill/select/press 的值 |

### 3. `extract` - 提取内容

从页面提取文本、HTML、截图或存储数据。

**参数:**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| browserId | string | 是 | 浏览器 ID |
| pageId | string | 是 | 页面 ID |
| type | "text" \| "html" \| "screenshot" \| "cookies" \| "localStorage" \| "elements" | 是 | 提取类型 |
| selector | string | 否 | CSS 选择器 (用于元素提取) |

### 4. `navigate` - 导航操作

执行导航操作：前往 URL、后退、前进、刷新。

**参数:**
| 参数 | 类型 | 必需 | 描述 |
|------|------|------|------|
| browserId | string | 是 | 浏览器 ID |
| pageId | string | 是 | 页面 ID |
| action | "goto" \| "back" \| "forward" \| "reload" | 是 | 导航操作 |
| url | string | 否 | goto 的目标 URL |

### 5. `close` - 关闭浏览器

关闭浏览器并清理资源。

**参数:**
| 参数 | 类型 | 必需 | 默认值 | 描述 |
|------|------|------|--------|------|
| browserId | string | 是 | - | 浏览器 ID |
| cleanupWorkingDir | boolean | 否 | true | 是否清理临时工作目录 |

### 6. `list_browsers` - 列出活动浏览器

列出所有活动的浏览器实例。

## 浏览器用户数据目录

### 默认路径

| 平台 | Chrome | Edge |
|------|--------|------|
| macOS | `~/Library/Application Support/Google/Chrome` | `~/Library/Application Support/Microsoft Edge` |
| Windows | `%LOCALAPPDATA%\Google\Chrome\User Data` | `%LOCALAPPDATA%\Microsoft\Edge\User Data` |
| Linux | `~/.config/google-chrome` | `~/.config/microsoft-edge` |

## 会话继承说明

当启用会话继承时，服务器会：

1. **复制 Cookies**: 从 SQLite 数据库读取并解密 (跨平台)
2. **复制 LocalStorage**: 从 LevelDB 读取
3. **复制 IndexedDB**: 直接复制目录结构
4. **复制 Session Storage**: 从 LevelDB 读取

### 注意事项

- 浏览器运行时数据库可能被锁定，服务器会自动复制到临时目录
- Chrome 130+ 版本的 Cookie 加密格式可能有变化
- Session Storage 是会话级别的，通常在浏览器关闭后清空

## 平台特定说明

### macOS

Cookie 解密使用 Keychain 存储的密钥，需要用户授权访问。

### Windows

需要安装 `@aspect-build/dpapi` 包来解密 Cookies:

```bash
npm install @aspect-build/dpapi
```

### Linux

需要安装 `keytar` 并配置 libsecret。如果无法访问 keyring，会回退到硬编码密码。

## 开发

```bash
# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建
npm run build
```

## 许可证

MIT