elentra-local-connector

A private, local, read-only MCP connector that lets Claude Desktop search your own uOttawa Elentra data — by borrowing your existing authenticated Chrome session rather than storing any credential.

Spec: PRD-FINAL.md is authoritative. Status: read-only. write_enabled = false is a build-time constant.

What "live" means here

Reasonably current while the connector is active — never a push guarantee. Elentra exposes no webhooks, no WebSocket, and no SSE, so this polls. The auth token lasts 60 minutes, so stale is the normal case; every tool response carries fetched_at, is_stale, and staleness_seconds so Claude says "as of 3 hours ago" instead of implying live truth.

Architecture

Chrome MV3 extension   has the session · owns the allowlist · GET only
        │              no chrome.cookies · no chrome.scripting
        ▼  native messaging
relay                  thin, stateless, ~100 LOC
        │  unix socket (0600)
        ▼
daemon (launchd)       sole DB writer · parsers · ICS poller · audit
        │  direct SQLite read-only (WAL)
        ▼
mcp-server (stdio)     read-only tools → Claude Desktop

Four processes, deliberately. Chrome spawns a native-messaging host as a child process, so a daemon that is that host would die with Chrome — killing unattended ICS polling — and be re-spawned on every service-worker restart, producing two writers against a WAL database that permits one. The relay costs ~100 stateless lines and removes both problems.

Setup

The build is automated; the wiring is not. See docs/HANDOFF.md — about 10 minutes of Chrome and macOS steps that cannot be scripted.

pnpm install
pnpm bootstrap  # build, keys, index, daemon, health — idempotent, re-runnable

pnpm bootstrap does everything scriptable and reports what is left. The individual steps, if you would rather run them yourself:

pnpm verify     # typecheck + lint + test + secret scan — the gate
pnpm build      # four bundles: mcp, daemon, relay, extension
pnpm build:mcpb # the Claude Desktop .mcpb — separate from pnpm build
pnpm health     # live diagnostics, after handoff

pnpm install && pnpm verify runs fully offline: fixtures are synthetic, and tests/no-network.setup.ts replaces fetch with a thrower, so any test that reaches for the network fails rather than silently succeeding.

Guarantees

• Never stores your password; no password code path exists.

• Never exports browser cookies.

• Never automates login, MFA, or SSO renewal — on expiry it stops and tells you.

• Never exposes a generic request(method, url) tool to the model.

• Repo contains code only; fixtures are 100% synthetic.

See SECURITY.md for the invariants and PRIVACY.md for what reaches Anthropic.

License

MIT — see LICENSE.