MCP tool reference

Every tool returns a single text item containing a response envelope (see Responses and 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.

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.

#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.

Write receipts contain operationID, documentID, committedRevision and ownerProofSHA256.

#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.

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.

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.

#rooqi_query_pdf_operation

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

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