# MCP tool reference

> Every tool the RooQi MCP server exposes, with exact input schemas, results and errors.

- Source: https://rooqi.cn/docs/developers/mcp-reference/
- Platforms: Mac only (macOS 14 or later)
- Version: MCP server “RooQi” 0.1.0 · bridge protocol v1 · MCP Swift SDK 0.12.1
- Status: Preview — not yet publicly released
- Last verified: 2026-10-26 against Apps/RooQiMac/IPC/Sources/RooQiBridge/Main.swift and RooQiIPCShared/Wire.swift
- Known limitations: All tools reject unknown or missing fields with malformedRequest. Requests and responses are limited to 16,384 bytes. At most 8 calls can be in flight per connection; each times out after 8 seconds.

Every tool returns a single text item containing a **response envelope** (see [Responses and errors](/docs/developers/errors/)). `isError` is `true` whenever `code` is not `ready`. Successful payloads are in `resultJSON`, a JSON string.

All IDs are UUID strings. All schemas set `additionalProperties: false` and require every listed field.

## Status

### rooqi_status

Checks the external connection on this Mac. Doesn’t open RooQi or read or change documents.

Input: `{}`

## Read

### rooqi_request_read_access

Asks RooQi to show a native window granting **read-only** access to one project for 15 minutes. Returns `approvalRequired` the first time; call again after the user approves.

Input: `{}`

### rooqi_list_approved_documents

Lists the documents this connection may read: an object mapping document ID to title.

Input: `{}`

### rooqi_read_note

Reads the **saved text blocks** and revision of an approved document. Doesn’t include handwriting, images, tables, mind maps, PDF source text or unsaved drafts. If the result is too large it is refused with `resultTooLarge`, never truncated.

| Field | Type |
|---|---|
| `documentID` | string (UUID) |

Result: `{ "documentID", "revision", "scope", "text" }`

## Create and append

### rooqi_request_write_access

Requests create-and-append access for one project (15 minutes).

Input: `{}`

### rooqi_create_note

Creates an empty note in the approved project and returns a durable receipt at revision 0. Choose `operationID` and `documentID` yourself and **reuse them unchanged when retrying**.

| Field | Type | Rules |
|---|---|---|
| `operationID` | string (UUID) | Frozen per operation |
| `documentID` | string (UUID) | The new note’s ID |
| `title` | string | 1–200 characters |
| `provider` | string | ≤ 64 bytes; who is calling (e.g. your app or model vendor) |
| `model` | string | ≤ 64 bytes; declare truthfully |
| `promptVersion` | string | ≤ 64 bytes |

### rooqi_append_text

Appends a **new text block**; never replaces existing text. `expectedVersion` must match the document’s current revision. Retrying with the same `operationID` never writes twice.

| Field | Type | Rules |
|---|---|---|
| `operationID` | string (UUID) | Reuse on retry |
| `documentID` | string (UUID) | Approved document |
| `text` | string | 1–6,000 bytes (UTF-8) |
| `expectedVersion` | integer ≥ 0 | Current revision |
| `provider`, `model`, `promptVersion` | string | ≤ 64 bytes each |

Write receipts contain `operationID`, `documentID`, `committedRevision` and `ownerProofSHA256`.

> **Important** If you get `mutationUncertain`, the write may or may not have happened. Check the document (or retry with the **same** `operationID`). Never retry with a new ID.

## PDF annotation

### rooqi_request_pdf_annotation_access

Requests separate PDF access: read selection text and add annotations in PDFs of the chosen project. Earlier read or write grants do not include this.

Input: `{}`

### rooqi_list_pdf_targets

Lists the PDF surfaces of an approved document. Page indexes start at 0.

| Field | Type |
|---|---|
| `documentID` | string (UUID) |

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

### rooqi_read_pdf_page

Reads the text inside a rectangle of a real source PDF page, with digests and page geometry. Pages without text, or regions that are too large, are refused — RooQi doesn’t invent OCR.

| Field | Type | Rules |
|---|---|---|
| `documentID` | string (UUID) | |
| `surfaceID` | string (UUID) | From `rooqi_list_pdf_targets` |
| `pageIndex` | integer | 0 … 999,999 |
| `rect` | object | `{x, y, width, height}` |

`rect` uses **display coordinates with a top-left origin, in integer millionths** of the page: `x`, `y` in 0…999,999; `width`, `height` in 1…1,000,000; `x + width` and `y + height` ≤ 1,000,000.

Result includes `revision`, `sourceDigest`, `geometryDigest`, `pageTextDigest`, `selectionTextDigest`, `selectedText` and `lines` (each `{text, rect}`).

### rooqi_annotate_pdf

Adds one highlight, underline or comment. The original PDF and existing annotations are kept.

| Field | Type | Rules |
|---|---|---|
| `operationID` | string (UUID) | Reuse on retry |
| `query` | object | The exact `{documentID, surfaceID, pageIndex, rect}` you read |
| `expectedVersion` | integer ≥ 0 | `revision` from the read |
| `sourceAssetID` | string (UUID) | From the read |
| `sourceDigest`, `geometryDigest`, `selectionTextDigest` | string | 64 lowercase hex characters, from the read |
| `kind` | string | `highlight`, `underline` or `comment` |
| `comment` | string | ≤ 2,000 bytes; required (non-blank) for `comment` |
| `provider`, `model`, `promptVersion` | string | 1–64 bytes each |

### rooqi_query_pdf_operation

Looks up the durable state of an earlier annotation by its `operationID`. Doesn’t write anything.

| Field | Type |
|---|---|
| `documentID` | string (UUID) |
| `operationID` | string (UUID) |

Result `state` is one of `committed` (with a receipt), `prepared-not-submitted`, `submission-uncertain-do-not-use-new-id` or `not-found`.