开发者
MCP 工具参考
RooQi MCP 服务提供的全部工具，含准确的输入 schema、结果与错误。
每个工具返回一个文本项，内容是响应信封（见响应与错误）。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。
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。