🗽 Oath — the citizenship interview coach for Alexa+

Track: Alexa+ (self-hosted MCP server, spec 2025-11-25, Streamable HTTP) · Mini-challenge: Open Source Build, Ship, Shape: Amazon Developer Hackathon 2026

The US naturalization civics test is an oral exam: a USCIS officer asks questions aloud, you answer aloud, and the test stops early the moment you pass — or fail. Since October 20, 2025, two different versions of that exam are running at the same time, and which one you get depends on the date you filed your N-400. Flashcard apps are silent, single-version, and can't tell you if you're ready. A voice agent can literally rehearse the real thing — that's Oath.

Oath is a self-hosted MCP server that gives Alexa+ (or any MCP client) everything it needs to be a patient, honest examiner: both official USCIS question banks, deterministic answer checking against the officially published acceptable answers, spaced repetition, mock interviews with the real stopping rules, and a readiness score computed by simulating your actual upcoming exam 10,000 times.

Why this matters

• The N-400 filing fee is a real bet (~$710–760) and you get one re-examination before denial.

• The 2008 test (filed before Oct 20, 2025): officer asks up to 10 of 100 questions, 6 correct passes, test stops at 6 correct or 5 wrong.

• The 2025 test (filed on/after): up to 20 of 128 questions, 12 to pass, ends at 12 correct or 9 wrong — early stop in both directions (Federal Register 2025-18050).

• Applicants 65+ with 20+ years as permanent residents get a designated 20-question subset (10 asked, 6 to pass) — Oath detects and handles this automatically.

• Some answers change with elections ("Who is the President?"). Oath never scores those — it maintains a watchlist with USCIS's own verify-before-your-interview guidance.

Tell Oath one fact — your filing date — and every drill, mock, and readiness estimate is configured to the exam you will actually sit.

Related MCP server: InterviewDojo

What's real vs simulated (honest up front)

• ✅ Real: the MCP server (spec 2025-11-25, Streamable HTTP, stateful sessions, 8 tools, resources, MCP Apps view), both official question banks transcribed and machine-verified from USCIS PDFs, all exam mechanics, the deterministic matcher (87-case eval, 0 false-accepts), the web client's MCP traffic (official SDK client — watch it live in the "MCP wire" panel).

• 🟡 Simulated: the Alexa+ surface. No hackathon participant can connect to real Alexa+ (the add-on tools are partner-preview only — confirmed in the official hackathon FAQ, which endorses exactly this demo format: "a web page that acts as an actual MCP client … satisfies the requirement"). Voice in/out uses Chrome's Web Speech API and is labeled as a simulation in the UI.

• ❌ No LLM anywhere in scoring or routing. Where the stakes are a federal exam, grading is deterministic against official answers — and the whole server works identically with Claude, MCP Inspector, or Alexa+ the day it opens to developers.

Quick start (judges: ~60 seconds)

git clone https://github.com/nityanand123gupta/oath-alexa-civics-coach.git
cd oath-alexa-civics-coach
npm install
npm run build
npm start          # → http://localhost:3000  (Chrome recommended for voice)

No environment variables. No API keys. No accounts. Everything runs locally.

Try saying (or clicking): "Practice five questions" → answer out loud → "Am I ready?" → "Give me a mock interview."

Prove the MCP server independently

# official inspector CLI against the running server
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http --method tools/list
npx @modelcontextprotocol/inspector --cli http://localhost:3000/mcp --transport http \
  --method tools/call --tool-name start_practice --tool-arg mode=mock_interview

# or the one-command scripted journey (second terminal, server running)
node scripts/e2e-demo.mjs

Full captured transcripts: docs/compliance-evidence.md.

Use it from any MCP client

Oath is assistant-agnostic. For example, from Claude Code:

claude mcp add --transport http oath http://localhost:3000/mcp

…then ask Claude to quiz you. Remote exposure for a real device someday: cloudflared tunnel --url http://localhost:3000.

The 8 tools

Architecture

Browser (Chrome) — "simulated Alexa+" client (React/Vite)
  Web Speech STT/TTS → deterministic intent router → REAL MCP client (official SDK)
  cards UI + live MCP-wire panel + MCP Apps host (AppBridge + sandboxed iframe)
        │  Streamable HTTP · MCP 2025-11-25 · Mcp-Session-Id
Node 24 + Express — self-hosted MCP server (@modelcontextprotocol/sdk 1.32)
  8 zod-validated tools · stateful sessions · ui:// MCP Apps resource · JSON store
        │  pure function calls
@oath/civics-kit — dependency-free TS engine (also a standalone OSS package)
  official banks (100 + 128 Qs) · matcher · SM-2 · exam state machines · Monte Carlo

More: docs/architecture.md · docs/product-brief.md

Engineering receipts

• 53 automated tests (npx vitest run): exam-rule boundary cases (pass-at-6/12, fail-at-5/9, 65/20), matcher adversarial cases, Monte Carlo seed determinism, full MCP integration via the official SDK client, two-session isolation, MCP Apps resource + metadata, mid-mock explain refusal.

• 87-case labeled matcher eval (npm run eval): 100% accuracy, 0 false-accepts including opposite-meaning attacks ("to spread communism" vs "to stop the spread of communism"). Two held-out labels were revised when we adopted the strict-coach policy (stricter than the officer, never looser) — the eval is a regression suite encoding that policy.

• Data provenance: both banks machine-verified against the official USCIS PDFs (answer-count asserted per question, senior/dynamic flags cross-checked against USCIS's 65/20 documents and the Federal Register) — see docs/data-provenance/.

• MCP Apps (SEP-1865): the server ships its own readiness dashboard as a ui:// resource via the official @modelcontextprotocol/ext-apps package; the web client hosts it through the real app bridge, with automatic fallback to native cards.

Open Source mini-challenge

The exam engine is extracted as a standalone MIT package created during the hackathon window: civics-test-kit — official banks + matcher + SRS + exam mechanics + readiness simulation, dependency-free, reusable by any citizenship-prep tool.

Known limitations

Voice needs Chrome + internet (text input always works) · single learner profile per server · en/es/hi explanation templates only · browser-side MCP Apps bridge is verified manually, not in CI · covers the civics portion, not the English reading/writing tests.

Disclaimers

Not affiliated with Amazon or USCIS. Study aid, not legal advice. Civics questions and answers are US-government works (public domain), transcribed verbatim from uscis.gov; dynamic answers must be verified at uscis.gov/citizenship/testupdates.

License

MIT