Developers
Developer overview
What the RooQi MCP server and command-line bridge can do, where they run and what they can’t do.
RooQi for Mac includes a small, signed helper that lets local tools — AI assistants via the Model Context Protocol (MCP), or your own scripts via a command line — work with your notes, only after you approve each connection in RooQi.
What you can do
| Capability | MCP tool | CLI |
|---|---|---|
| Check that RooQi is reachable | rooqi_status | rooqi status |
| Read saved text of approved documents | rooqi_request_read_access, rooqi_list_approved_documents, rooqi_read_note | rooqi list, rooqi read <id> |
| Create a note / append text | rooqi_request_write_access, rooqi_create_note, rooqi_append_text | rooqi run |
| Read PDF selections and add highlights, underlines or comments | rooqi_request_pdf_annotation_access, rooqi_list_pdf_targets, rooqi_read_pdf_page, rooqi_annotate_pdf, rooqi_query_pdf_operation | rooqi pdf |
How it works
MCP client / script ──stdio──> rooqi (bridge) ──XPC──> RooQi broker ──> RooQi.app
(code-signature checked)- The bridge (
rooqi) runs as a child process of your client and talks JSON over stdin/stdout. - A broker registered by RooQi relays requests to the running app. Every hop checks code signatures.
- The app shows a native approval window and enforces scope, size limits and idempotency.
Design guarantees
- Nothing without approval. Each connection asks in a native RooQi window. Grants last 15 minutes and end when the connection closes. A new process never inherits another’s grant.
- One project. You pick a single project when approving; tools see only that project.
- Additive writes. Writes create notes, append new text blocks, or add PDF annotations. Existing text, original PDFs and existing annotations are never replaced or deleted.
- Separate permissions. Read, create/append and PDF annotation are approved separately.
- Honest failures. Oversized results are refused rather than truncated, and an uncertain write is reported as uncertain so you can query it instead of retrying blindly.
What it doesn’t do
- Read handwriting, images, tables, mind maps, PDF source text outside a selected region, or unsaved drafts.
- Run without RooQi open on the same Mac, or reach RooQi on another device.
- Sync anything to the cloud by itself, or call AI services.