# simple-qqdocs-mcp

配合 **Playwright MCP** 操作腾讯文档表格（`.excel-container>canvas`）的简易 MCP 服务。

## 前置条件

1. 用 Playwright MCP 打开 `docs.qq.com/sheet` 表格页
2. 浏览器开启 CDP，默认 `http://127.0.0.1:9222`
3. 若遇代理报错，在 MCP 配置中设置 `ALL_PROXY=""`

## 安装与配置

```bash
pnpm install
```

在 Cursor / MCP 配置中注册（路径按实际修改）：

```json
{
  "mcpServers": {
    "simple-qqdocs": {
      "command": "node",
      "args": ["d:/1024/llm/simple-qqdocs-mcp/src/index.js"],
      "env": {
        "CDP_ENDPOINT": "http://127.0.0.1:9222",
        "ALL_PROXY": ""
      }
    }
  }
}
```

## 使用流程

1. Playwright 打开腾讯文档表格
2. 调用 `refresh_grid_boundaries` 或直接使用默认工具（会自动重新识别网格）
3. 页面**滚动/缩放**后，优先用非 `quick_*` 工具，或先 `refresh_grid_boundaries`

### 工具选用

| 场景 | 推荐 |
|------|------|
| 常规操作 | `get_cell_bounds` / `click_cell` / `input_cell` |
| 用户明确要求 quick/快速/缓存 | `quick_get_cell_bounds` / `quick_click_cell` / `quick_input_cell` |

## Tools

### 坐标与操作

| Tool | 说明 |
|------|------|
| `refresh_grid_boundaries` | 识别并刷新列标 ABCD、行标 1234 的边界缓存 |
| `get_cell_bounds` | **默认** 获取单元格边界（每次重新识别） |
| `quick_get_cell_bounds` | 用缓存快速获取边界 |
| `click_cell` | **默认** 识别并点击单元格 |
| `quick_click_cell` | 用缓存快速点击 |
| `input_cell` | **默认** 点击单元格并输入文本 |
| `quick_input_cell` | 用缓存快速输入 |

**单元格引用**：`A1`（单格）、`A1:C2` 或 `A1C2`（范围）

**返回格式**：

- 单格 `A1` → `bounds: [[x1, x2], [y1, y2]]`
- 范围 `A1:C2` → `bounds: [[x1, x2, x3, x4], [y1, y2, y3]]`

### 基础 / 调试

| Tool | 说明 |
|------|------|
| `get_canvas_snapshot` | 获取 canvas 截图（base64 PNG） |
| `detect_grid` | 识别行标/列标区域与边界 |
| `recognize_cell_text` | 识别单元格文字，返回 `{ text, bcolor, fcolor }` |

## 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `CDP_ENDPOINT` | `http://127.0.0.1:9222` | 浏览器 CDP 地址 |