# 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.

```bash
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:

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