# MCP 工具参考

> RooQi MCP 服务提供的全部工具，含准确的输入 schema、结果与错误。

- Source: https://rooqi.cn/zh-hans/docs/developers/mcp-reference/
- Platforms: 仅 Mac（macOS 14 或更高版本）
- Version: MCP 服务“RooQi” 0.1.0 · 桥接协议 v1 · MCP Swift SDK 0.12.1
- Status: 预览——尚未公开发布
- Last verified: 2026-10-26，依据 Apps/RooQiMac/IPC/Sources/RooQiBridge/Main.swift 与 RooQiIPCShared/Wire.swift
- Known limitations: 缺少或多出字段一律返回 malformedRequest。请求与响应上限 16,384 字节。每个连接最多同时 8 个调用，单次 8 秒超时。

每个工具返回一个文本项，内容是**响应信封**（见[响应与错误](/zh-hans/docs/developers/errors/)）。`code` 不是 `ready` 时 `isError` 为 `true`。成功结果位于 `resultJSON`（JSON 字符串）。

所有 ID 均为 UUID 字符串。所有 schema 都设置 `additionalProperties: false`，并要求列出的全部字段。

## 状态

### rooqi_status

检查此 Mac 上的外部连接状态；不打开 App，不读取或修改文稿。

输入：`{}`

## 读取

### rooqi_request_read_access

请求 RooQi 显示原生窗口，授予一个项目 15 分钟的**只读**访问。首次返回 `approvalRequired`，用户批准后再次调用。

输入：`{}`

### rooqi_list_approved_documents

列出本连接可读取的文稿：文稿 ID 到标题的对象。

输入：`{}`

### rooqi_read_note

读取已授权文稿的**已保存文字块**与 revision；不含手写、图像、表格、导图、PDF 原文或未保存草稿。结果过大时返回 `resultTooLarge`，不会截断。

| 字段 | 类型 |
|---|---|
| `documentID` | string（UUID） |

结果：`{ "documentID", "revision", "scope", "text" }`

## 创建与追加

### rooqi_request_write_access

请求一个项目的创建与追加授权（15 分钟）。

输入：`{}`

### rooqi_create_note

在已授权项目中新建空白文稿，返回 revision 0 的持久回执。`operationID` 与 `documentID` 由调用者生成，**重试时原样复用**。

| 字段 | 类型 | 规则 |
|---|---|---|
| `operationID` | string（UUID） | 每个操作固定 |
| `documentID` | string（UUID） | 新文稿 ID |
| `title` | string | 1–200 个字符 |
| `provider` | string | ≤ 64 字节；调用方（如你的应用或模型厂商） |
| `model` | string | ≤ 64 字节；如实声明 |
| `promptVersion` | string | ≤ 64 字节 |

### rooqi_append_text

追加一个**新文字块**，不替换已有正文。`expectedVersion` 必须等于文稿当前 revision。使用同一 `operationID` 重试不会重复写入。

| 字段 | 类型 | 规则 |
|---|---|---|
| `operationID` | string（UUID） | 重试时复用 |
| `documentID` | string（UUID） | 已授权文稿 |
| `text` | string | 1–6,000 字节（UTF-8） |
| `expectedVersion` | 整数 ≥ 0 | 当前 revision |
| `provider`、`model`、`promptVersion` | string | 各 ≤ 64 字节 |

写入回执包含 `operationID`、`documentID`、`committedRevision` 与 `ownerProofSHA256`。

> **重要** 收到 `mutationUncertain` 表示写入可能已经发生，也可能没有。请核对文稿，或用**同一个** `operationID` 重试；不要换新 ID 重试。

## PDF 批注

### rooqi_request_pdf_annotation_access

单独请求 PDF 权限：读取所选项目中 PDF 的选区文字并新增批注。此前的读取或写入授权不包含此权限。

输入：`{}`

### rooqi_list_pdf_targets

列出已授权文稿中的 PDF surface，页索引从 0 开始。

| 字段 | 类型 |
|---|---|
| `documentID` | string（UUID） |

结果：`{ "documentID", "revision", "targets": [{ "surfaceID", "sourceAssetID", "sourceDigest", "sourcePageCount", "availableSourcePages" }] }`

### rooqi_read_pdf_page

读取真实源 PDF 某页矩形内的文字，并返回 digest 与页面几何。无文字的页面或过大的区域会被拒绝——RooQi 不会虚构 OCR。

| 字段 | 类型 | 规则 |
|---|---|---|
| `documentID` | string（UUID） | |
| `surfaceID` | string（UUID） | 来自 `rooqi_list_pdf_targets` |
| `pageIndex` | 整数 | 0 … 999,999 |
| `rect` | object | `{x, y, width, height}` |

`rect` 使用**显示坐标、左上角为原点、以页面的百万分之一为单位的整数**：`x`、`y` 取 0…999,999；`width`、`height` 取 1…1,000,000；且 `x + width`、`y + height` ≤ 1,000,000。

结果包含 `revision`、`sourceDigest`、`geometryDigest`、`pageTextDigest`、`selectionTextDigest`、`selectedText` 与 `lines`（每项 `{text, rect}`）。

### rooqi_annotate_pdf

新增一条高亮、下划线或评论，保留原 PDF 与已有批注。

| 字段 | 类型 | 规则 |
|---|---|---|
| `operationID` | string（UUID） | 重试时复用 |
| `query` | object | 与读取时完全相同的 `{documentID, surfaceID, pageIndex, rect}` |
| `expectedVersion` | 整数 ≥ 0 | 读取结果中的 `revision` |
| `sourceAssetID` | string（UUID） | 来自读取结果 |
| `sourceDigest`、`geometryDigest`、`selectionTextDigest` | string | 64 位小写十六进制，来自读取结果 |
| `kind` | string | `highlight`、`underline` 或 `comment` |
| `comment` | string | ≤ 2,000 字节；`comment` 类型必须非空 |
| `provider`、`model`、`promptVersion` | string | 各 1–64 字节 |

### rooqi_query_pdf_operation

按 `operationID` 查询此前批注的持久状态，不会写入。

| 字段 | 类型 |
|---|---|
| `documentID` | string（UUID） |
| `operationID` | string（UUID） |

结果中的 `state` 为 `committed`（附回执）、`prepared-not-submitted`、`submission-uncertain-do-not-use-new-id` 或 `not-found`。