Jocasta MCP (The Archivist)

Jocasta is the ultimate local-first AI data gateway. Rather than relying on cloud API scraping or headless browser hacks (which are notoriously brittle), sanctum-jocasta-mcp connects directly to the underlying SQLite databases running silently on the Mac Mini host. It exposes 23 discrete tool sets that are shared centrally among the Jedi Council.

Because all the databases queried (Messages, iOS Notes, Health) live entirely offline under ~/Library, data egress costs and latency are basically zero.

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 ~/Library/Mail/V* and queries the primary Envelope Index. It maps sender aliases and email subjects instantaneously.

Messages & Protocols

Parses chat.db for natively synced iMessage and SMS, and hooks into Catalyst bundles for WhatsApp and Telegram. iMessage and WhatsApp now route through SanctumBridge (:4078) by default, with direct DB fallback. Signal still decodes the config.json master key to decrypt its local SQLCipher db.sqlite directly — the bridge doesn’t handle 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 queries NoteStore.sqlite for uncompressed Apple Notes brainstorming, extracts Calendar schedules out of Calendar Cache, 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

Provides access to Wikipedia and encyclopedias by proxying requests securely to a local .zim unzipper (kiwix-serve).

GPS & Media

Queries the master Photos.sqlite for exact timestamp and location metadata of media. Integrates with OpenStreetMap to reverse-geocode those latitudes/longitudes seamlessly.

Active Operations (The Native executioner’s blade)

Because Jocasta operates via secure sqlite3.OPEN_READONLY connections for reads (or SanctumBridge for the four bridged databases), she utilizes a separate isolated AppleScript pipeline (osascript) to enact destructive actions securely. This avoids Core Data corruption natively:

• jocasta_write_note: Scaffolds an organized document in your default iCloud Apple Notes directory natively.
• jocasta_write_calendar: Ingests ISO datetimes to programmatically schedule meetings and events directly in the Calendar app without manual scraping.
• jocasta_send_imessage: Invokes the Mac’s background Messages daemon to dispatch iMessages/SMS seamlessly.
  • Primary Use Case: Mon Mothma utilizes this tool as a PagerDuty pipeline. If a service drops, she can dispatch a text message directly to your own phone number, guaranteeing the alert hits your lock screen.

Web Browsing (Agent-Browser)

Rather than embedding a bloated Playwright container inside the Node runtime, Jocasta natively proxies automation requests down to the user’s global agent-browser (Chrome via CDP).

• Tool: jocasta_agent_browser
• By passing strings directly (like open https://github.com && snapshot -i), Jocasta handles DOM inspection and downloading files via refs magically.
• Security Check: This process explicitly launches heavily bounded via the AGENT_BROWSER_ALLOWED_DOMAINS env var. She cannot explore arbitrary websites, thereby locking out heavy prompt-injection risks!

Caution

The Keychain Risk: Jocasta can execute security find-internet-password. This throws a native Touch ID/macOS access pop-up the first try. It is inherently dangerous to give an AI plaintext passwords! Where possible, users should utilize the agent-browser auth login vault pattern instead to abstract secrets away from the LLM 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 raw memory profiling (unix ps) and macOS Unified Logs (log show --predicate). To protect the LLM context window, these outputs are hard-truncated precisely to 500 records.
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 native module builds (sqlcipher, sqlite3, esbuild) are explicitly allowlisted via pnpm.onlyBuiltDependencies. If you run npm install instead of pnpm install, you will have a bad time — Manoir’s global npm config has omit=dev, which silently skips TypeScript.

pnpm install
pnpm build

Testing and E2E

Like .mlx components, Jocasta asserts viability with an explicitly built test_e2e_jocasta.sh. The test builds the TypeScript outputs cleanly via pnpm, calls all Core CLI functions checking for intact stdout/stderr structures, tests telemetry, and gracefully evaluates unknown paths for exception management. Connectors that hit missing databases (Calendar Cache on Manoir, for instance) return readable errors that the test suite validates as expected failures — not silent crashes.