citation-mcp

Remote MCP server exposing the CounselStack citation engine as nine legal research tools. This is a thin consumer of citation-api — it owns no data and no extraction logic; it speaks HTTP to the API and packages the proven citator tool layer (schemas, orchestration, honesty guards) in MCP form so any MCP client — Claude first — can drive the engine.

Claude (web/desktop/mobile) ──MCP (Streamable HTTP)──▶  citation-mcp  ──HTTP──▶  citation-api  ──▶  mirror-db

The nine tools

Tool	What it does	citation-api endpoints
citation_lookup	Resolve one cite or bare case name → canonical authority + precedent footprint	/resolve (+ /mentions)
find_statutes	Topic → governing statute/reg sections (multi-phrasing FTS, merged + reranked)	/search-statutes
citation_mentions	The opinions citing ONE authority, with treatment snippets; the workhorse	/resolve + /mentions
find_case_text	Full-text boolean keyword search over opinion bodies	/search-cases
find_cases	Parenthetical proposition search (slim index, fallback)	/search-parentheticals
grep_opinion	Search/verify text INSIDE one authority: quotes, pin cites, keywords	/quote
read_subsection	One pinpoint provision of a statute/reg + breadcrumb	/subsection
citation_read	Full text of one authority (every opinion in a cluster, labeled)	/resolve + /read
citation_check	Scan a draft, resolve every distinct authority, report found/not-found	/scan + /resolve

All nine are read-only over immutable reference data and are annotated as such (readOnlyHint), with titles, for connector-directory readiness. Research methodology (tool order, the statutes→mentions front door, treatment honesty rules) ships in the server's instructions field.

Run it

npm install
cp .env.example .env        # point CITATION_API_BASE_URL at a running citation-api
npm run dev                 # tsx watch, listens on :3300

# in another terminal:
npm run smoke               # connect, list tools, verify all nine
SMOKE_LIVE=1 npm run smoke  # also exercise citation_lookup against the live API

npm run build && npm start for production (compiles to dist/). The server is stateless (fresh MCP server + transport per request, no sessions), so it deploys as a plain web service and scales horizontally with no sticky routing. GET /healthz for health checks.

Connecting it to Claude

Deploy behind HTTPS, then in Claude: Settings → Connectors → Add custom connector, URL https://<your-host>/mcp. Authless V1 needs no credentials. Requests from allowed browser origins (MCP_ALLOWED_ORIGINS, default claude.ai + claude.com) and server-to-server requests (no Origin header) are accepted; anything else is rejected 403.

Auth: authless now, OAuth-shaped already (Path C)

V1 runs authless (AUTH_MODE=none): no token required, and — by design — no user identity, so no per-user metering. The OAuth 2.1 resource-server shape is already in place so flipping auth on later is additive:

• Every /mcp request crosses authMiddleware (src/auth/auth.ts) — the single boundary. Authless mode threads a null auth context into tool registration.
• AUTH_MODE=oauth activates the RFC 9728 discovery handshake: 401 + WWW-Authenticate: Bearer resource_metadata=... and the /.well-known/oauth-protected-resource document (404 while authless).
• verifyBearerToken is a stub that always rejects — real validation (signature/expiry against the issuer, audience = this server per RFC 8707, subject + scopes extraction) lands when an authorization server exists. Do not enable oauth mode in production until then.
• Outbound, every citation-api call carries CITATION_API_TOKEN as a Bearer when set — a no-op today, this server's API key when the API's key layer ships.

Layout

src/
  index.ts            Express app: origin validation, /healthz, well-known, stateless /mcp
  config.ts           env parsing (AUTH_MODE switch, cache knobs, origins)
  http.ts             HTTP client: result cache, 60s timeouts, __httpError sentinel
  instructions.ts     research methodology → MCP instructions field
  api/client.ts       one function per citation-api endpoint
  orchestration/      the composites: lookup, mentions, read, check, grep, subsection, search
  tools/index.ts      the nine registrations (zod schemas, descriptions, annotations, handlers)
  tools/format.ts     result → model-facing text, incl. the honesty language
  auth/auth.ts        Path C skeleton: middleware, RFC 9728 metadata, stubbed verifier
scripts/smoke.ts      MCP client: list tools, optional live call

Design notes worth knowing:

• Error honesty is a contract. Upstream failures surface as __httpError sentinels and reach the model as "the engine failed — nothing was learned; treat as unverified, not as not-found." A failed scan chunk is counted and the check report says INCOMPLETE. A mentions filter that misses says "not in the top page", never "no case discusses this."
• Result cache (10 min TTL / 500 entries, env-tunable): every endpoint is an idempotent read over immutable law, so identical calls skip the network. Per-instance; correct under horizontal scaling, just less shared.
• CFR mentions works here. The original agent integration had a gap where CFR cites silently returned no mentions; the mapping in orchestration/mentions.ts includes the CFR branch.

Future work (deliberately out of scope for V1)

• CFR topic search tool — the API's /cfr-search exists but has no tool yet (an agent can topic-search statutes, not regulations).
• OAuth authorization server + real token validation + per-user metering.
• Structured (structuredContent) outputs alongside the text blocks.