Jocasta MCP (The Archivist)

Jocasta is the local-first data gateway for the haus. Rather than scraping cloud APIs or driving a headless browser — both notoriously brittle — sanctum-jocasta-mcp reads the SQLite databases sitting on disk on the Mac Mini host. It exposes 23 tools, shared across the Jedi Council.

Because every database it queries (Messages, Apple Notes, Photos) lives offline under ~/Library, egress cost and network latency are zero. Nothing leaves the box to answer a question about what’s already on the box.

Source: github.com/Ogilthorp3/jocasta-mcp (private) — ~/Projects/jocasta-mcp/

The Architectural Design

The MCP operates through two unified streams:

1. The MCP Server (index.ts): For autonomous LLM agents speaking standard .stdio RPC.
2. The Terminal CLI (cli.ts): For SSH automation and bare Bash scripting (pnpm sanctum-jocasta <command>).

SanctumBridge (Port 4078)

As of April 2026, Jocasta’s read connectors for iMessage, WhatsApp, Contacts, and Calendar route queries through SanctumBridge — a lightweight HTTP proxy running on the host with Full Disk Access. This means jocasta-mcp itself no longer needs FDA granted. One less thing that can silently break after a macOS update.

The bridge accepts POST /bridge/query with a body of {"db": "imessage|whatsapp|contacts|calendar", "sql": "...", "params": []} and returns {"rows": [...], "count": N}. Every refactored connector attempts the bridge first. If the bridge is unreachable (crashed, not started, port blocked), the connector falls back to direct SQLite access — which still works if the node process has FDA. Graceful degradation, not graceful surrender.

The bridge listens on 127.0.0.1:4078 and is overridable via the SANCTUM_BRIDGE_URL env var; both ends resolve the port from ~/.sanctum/instance.yaml (services.sanctum_bridge.port) so changing it is one YAML edit. See SanctumBridge for the full architecture, API, and the story of why it’s a .app bundle instead of a script.

Note

Write operations — sending iMessages, creating Notes, scheduling Calendar events — still use the AppleScript/osascript pipeline directly. The bridge is read-only. If you need to send a PagerDuty text at 3 AM, that still goes through osascript, not HTTP.

Health Check

The jocasta_health tool reports server status and bridge connectivity in one call. It tells you whether queries are routing through the bridge or falling back to direct DB access, which is the first thing you want to know when something returns empty results.

Complete Unified Capabilities (23 Tools)

Apple Mail

Reads the Envelope Index under ~/Library/Mail/V*/MailData to map sender aliases and subjects. Timestamps are Unix epoch seconds here, not Apple’s 2001 epoch — a one-line off-by-31-years bug if you forget.

Messages & Protocols

Parses chat.db for iMessage and SMS, reads Telegram straight from its postbox/db/db.sqlite, and reaches WhatsApp through its own store. iMessage and WhatsApp route through SanctumBridge (:4078) by default, with direct DB fallback. Signal is the holdout: it decodes the config.json master key and opens its SQLCipher sql/db.sqlite directly, because the bridge doesn’t speak encrypted databases.

Electron Bundles

Slack and Discord data is heavily blocked due to Electron’s use of LevelDB packet chunks (Local Storage/leveldb). Those tools respond with graceful failures for now.

Apple Core Data

Jocasta pulls Apple Notes previews from the ZSNIPPET column of NoteStore.sqlite (the full bodies live in compressed ZDATA packets, untouched for now), reads Calendar events through the EventKit Swift helper at ~/.sanctum/bin/jocasta-eventkit (the on-disk Calendar Cache is stale by design on modern macOS, so it’s only the fallback), and parses AddressBook-v22.abcddb for CRM correlation of cell numbers to names. Calendar and Contacts route through SanctumBridge by default; Notes stays on direct SQLite — the bridge doesn’t serve it yet.

Offline Knowledge

jocasta_search_kiwix pings a local kiwix-serve on :8080 and confirms the offline .zim archive is reachable. Article extraction isn’t wired yet — the tool returns “reached, here’s how to parse me,” not the article. An honest stub beats a pretty lie.

GPS & Media

Queries Photos.sqlite for the timestamp and GPS metadata on each item, then hits OpenStreetMap’s Nominatim to turn those raw lat/long pairs into a place name you can actually read.

Active Operations

Reads go through sqlite3.OPEN_READONLY (or the bridge, for the four bridged databases). Writes never touch those files — they run through osascript, letting the host apps own the mutation so we never risk corrupting a Core Data store we don’t fully understand:

• jocasta_write_note: creates a note in the default iCloud Apple Notes account.
• jocasta_write_calendar: takes ISO datetimes and tells Calendar.app to schedule the event.
• jocasta_send_imessage: hands the message to the Messages daemon to send as iMessage/SMS.
  • Primary use case: Mon Mothma runs this as a pager. When a service drops, she texts the alert to your own phone — the one channel that lights up the lock screen whether or not you’re at the terminal.

Web Browsing (Agent-Browser)

Rather than embed a Playwright container in the Node runtime, Jocasta shells out to the user’s global agent-browser (Chrome via CDP).

• Tool: jocasta_agent_browser
• It passes the command string straight through (e.g. open https://github.com && snapshot -i), so DOM inspection and ref-based file downloads work exactly as they do from the CLI.
• Security Check: the connector sets AGENT_BROWSER_ALLOWED_DOMAINS to a fixed allowlist (currently github.com) before launching. Navigation off the list is blocked by agent-browser itself, which is the cheap way to keep a prompt-injected page from steering the browser somewhere it shouldn’t go.

Caution

The Keychain Risk: jocasta_read_keychain shells out to security find-generic-password / find-internet-password, so the first read on a given item throws the macOS Keychain access dialog — the “Allow / Always Allow” prompt for whatever process (here, node) is asking. Handing an LLM a plaintext password is inherently dangerous. Where possible, use the agent-browser auth login vault pattern instead, so the secret never reaches the model’s context.

Document Parsing and Telemetry (Anti-Sith Army)

For systems failure tracking and massive unstructured document ingest:

1. Jocasta Sysmon (jocasta_read_syslog & jocasta_read_process_list): Exposes macOS Unified Logs (log show --predicate) and raw process state (ps -ax -r, sorted hot-CPU-first). To protect the LLM context window, both are hard-truncated — syslog to the last 500 log lines, the process list to the top 50 processes. Fifty hot processes tells you what’s pinning the box; line 51 onward is just the idle tail.
2. Universal Files (jocasta_read_file): Equipped with pdf-parse and mammoth, Jocasta can slice through generic .docx, .pdf, .md, and .csv items downloaded into iCloud.

Package Manager

Jocasta runs on pnpm (10.33.0). The packageManager field is set in package.json, and the native module builds (@journeyapps/sqlcipher, sqlite3, esbuild) are explicitly allowlisted via pnpm.onlyBuiltDependencies. Run npm install instead of pnpm install and you’ll have a bad time: npm ignores pnpm.onlyBuiltDependencies, so those native modules never compile their bindings and the server falls over at first DB open. Use the package manager the lockfile was written for.

pnpm install
pnpm build

Testing and E2E

Like the .mlx components, Jocasta proves itself with test_e2e_jocasta.sh. It builds the TypeScript via pnpm, runs each CLI command and asserts on the stdout/stderr it gets back, exercises the telemetry tools, and feeds in bad paths to check the error handling. The point worth keeping: connectors that hit a missing or stale database (the on-disk Calendar Cache on manoir.local, for instance) return a readable error the suite validates as an expected failure — a tool that fails loudly is doing its job; one that fails silently is the bug.