# kimi-webbridge — 浏览器控制 CLI & MCP

让 AI Agent 通过 **`npx` 一键运行**的命令行工具，与 Kimi WebBridge Chrome 扩展通信，操控浏览器。

```bash
# 截图
npx kimi-webbridge screenshot

# 打开网页
npx kimi-webbridge navigate '{"url":"https://example.com"}'

# 启动 MCP 服务器（供 Claude Desktop 等使用）
npx kimi-webbridge mcp
```

> **无需安装。** `npx` 自动从 npm 下载依赖并缓存。

---

## 使用方式

### 方式一：CLI 工具（AI function calling）

```bash
npx kimi-webbridge navigate   '{"url":"https://www.google.com"}'
npx kimi-webbridge snapshot
npx kimi-webbridge click      '{"selector":"#submit-btn"}'
npx kimi-webbridge fill       '{"selector":"input[name=q]","value":"天气"}'
npx kimi-webbridge screenshot '{"format":"jpeg"}'
npx kimi-webbridge evaluate   '{"code":"document.title"}'
```

**function calling 配置模板：**

```json
{
  "type": "function",
  "function": {
    "name": "browser",
    "description": "控制浏览器（导航、点击、填表、截图等）",
    "parameters": {
      "type": "object",
      "properties": {
        "action": {
          "type": "string",
          "enum": ["navigate","snapshot","click","fill","evaluate","screenshot","send_keys","save_as_pdf","network","close_tab","list_tabs","upload"],
          "description": "要执行的操作"
        },
        "args": {
          "type": "object",
          "description": "操作参数，不同 action 不同"
        }
      },
      "required": ["action"]
    }
  }
}
```

### 方式二：MCP 服务器

```bash
npx kimi-webbridge mcp
```

**配置 Claude Desktop：**

```json
{
  "mcpServers": {
    "webbridge": {
      "command": "npx",
      "args": ["kimi-webbridge", "mcp"]
    }
  }
}
```

**配置 VS Code Agent（`.vscode/mcp.json`）：**

```json
{
  "servers": {
    "webbridge": {
      "type": "stdio",
      "command": "npx",
      "args": ["kimi-webbridge", "mcp"]
    }
  }
}
```

---

## 可用操作

| 操作             | 说明                 | 必填参数                     |
| ---------------- | -------------------- | ---------------------------- |
| `navigate`       | 打开网页             | `url`                        |
| `snapshot`       | 获取页面无障碍树结构 | —                            |
| `click`          | CSS 选择器点击       | `selector`                   |
| `snapshot_click` | 通过 @e ref 点击     | `ref`                        |
| `mouse_click`    | 物理鼠标点击         | `selector`                   |
| `fill`           | 填写表单             | `selector`, `value`          |
| `send_keys`      | 键盘按键             | `keys`                       |
| `key_type`       | 输入文本             | `text`                       |
| `evaluate`       | 执行 JavaScript      | `code`                       |
| `screenshot`     | 截图                 | `format`, `selector`（可选） |
| `save_as_pdf`    | 导出 PDF             | `paper_format`（可选）       |
| `network`        | 网络请求捕获         | `cmd`                        |
| `find_tab`       | 查找标签页           | `url`                        |
| `close_tab`      | 关闭标签页           | —                            |
| `list_tabs`      | 列出标签页           | —                            |
| `upload`         | 上传文件             | `selector`, `files[]`        |

---

## 前提

- Chrome 浏览器（安装 [Kimi WebBridge 扩展](https://chromewebstore.google.com/detail/kimi-webbridge/fldmhceldgbpfpkbgopacenieobmligc)）
- Node.js >= 18

扩展默认连接 `ws://127.0.0.1:10086/ws`。在扩展弹窗中点击图标 5 次可进入开发者模式修改地址。

## 环境变量

| 变量         | 默认值                    | 说明                          |
| ------------ | ------------------------- | ----------------------------- |
| `WS_URL`     | `ws://127.0.0.1:10086/ws` | WebSocket 地址（仅 CLI 模式） |
| `WS_TIMEOUT` | `60000`                   | 超时毫秒                      |

默认端口 10086。如需修改，先停止服务，编辑 `src/mcp.js` 中的 `CONFIG.WS_PORT`，
同时在扩展开发者模式中修改 WebSocket 地址为对应端口，然后重启。