[vitofico]

Summary

Adds a remote, read-only MCP endpoint at /mcp for the authenticated user's synced highlights. list_highlights, search_highlights and get_highlight return quotations with book attribution, using the existing Basic or native Bearer credentials. A matching REST API lives at /agent/v1/highlights.

One shared query service enforces user scope, active-only results, literal search, identity filters and UUID pagination. List/search responses use SQL-projected previews with explicit truncation flags; exact retrieval retains the full saved quotation and locator. This change includes both interfaces and their protocol/privacy tests so the shared access contract can be reviewed together.

The official MCP SDK uses stateless Streamable HTTP JSON responses. Authentication is checked on every request; cookie-only authentication is rejected. Host/Origin validation, request-size limits, sanitized errors and existing shutdown hooks are retained. SDK tracing is disabled.

Deployment and compatibility

• Full/sync-only mode; absent in AI-only mode. No new database migration or Android changes.
• Configure QUIRE_SERVER_MCP_PUBLIC_URL with the public HTTPS origin and forward /mcp and /agent/* to Quire Server. Reference Caddy routes and setup documentation are included.
• Clients must support an explicit existing Authorization header. OAuth discovery and browser-cookie MCP login are not part of this integration.
• No annotation writes, AI-provider calls, embeddings, new identity provider or telemetry exporter.

Validation

• Full PostgreSQL server suite: 1,069 passed; 32 query/API cases and 21 MCP-focused cases passed during development. Two affected native-auth fixture checks reran successfully after secret-scanner annotations.
• Full Ruff check/format passed; Caddy parser confirmed the new routes.
• Independent runtime, API, documentation and proxy review passed with no material findings.
• Repository hooks passed on all 19 files. Full GitHub server CI passed in full/sync-only/AI-only modes on 2d4bf62, together with Python and Java/Kotlin CodeQL. Image publication/scan are correctly skipped for the PR.
• Android implementation and dependencies are unchanged from the verified post-merge v2026.10.30.312 source.

Context

Follows #166. #143 was closed with the three merged PRs and its documented horizontal-reflowable jump limitation; this PR implements the separate Agent/MCP follow-up.