# Developer overview

> What the RooQi MCP server and command-line bridge can do, where they run and what they can’t do.

- Source: https://rooqi.cn/docs/developers/overview/
- Platforms: Mac only (macOS 14 or later)
- Version: RooQi for Mac 1.0 test build · bridge protocol v1 · MCP server “RooQi” 0.1.0
- Status: Preview — included in Mac test builds; not yet publicly released
- Last verified: 2026-10-26 against the RooQi Mac source (RooQiBridge/Main.swift, RooQiIPCShared/Wire.swift, ExternalConnection.swift)
- Known limitations: Mac only — iPhone and iPad have no external connection. There is no public HTTP/REST API. Names and limits may change before release.

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

```text
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.

## Next

- [Install and connect](/docs/developers/connect/)
- [MCP tool reference](/docs/developers/mcp-reference/)
- [CLI reference](/docs/developers/cli-reference/)