oravan

Oravan is a free, nonpartisan, bilingual (English/Spanish) U.S. Congress data tool whose goal is to let ordinary users quickly understand what Congress is doing and contact their members. Its core process is completed within 5 minutes: find federal representatives, understand active bills in plain language, get a 30-second call script, and then call. The entire process requires no account.

Main capabilities:

1. Representative lookup: locate federal House members and senators by ZIP code, with a dedicated page for each member.
2. Bill understanding: provide plain-language summaries of active bills (in English and Spanish), with citations to official records.
3. Call support: generate 30-second phone scripts, cached by bill, stance, language, and content version; support calling after hours, with call outcomes (called/voicemail/unable to reach) recorded on the local device.
4. "Read" section: show real third-party articles for important bills, labeled by media political leaning (left/center/right), with leaning ratings reusing AllSides' outlet-level scores.
5. MCP server: expose 5 tools via both remote MCP (Streamable HTTP) and local stdio: lookup_representatives, get_bill, search_bills, whats_moving, get_representative. Each response carries a citation envelope (source, timeliness, AI content label, license), and supports English or Spanish.

How to use:

• Website access: use via oravan.org, no account required.
• MCP remote endpoint:https://oravan.org/api/mcp/mcp，无密钥、只读、限速，无需账户或凭证。
• MCP local/stdio: first run npm ci, then run npx tsx scripts/mcp-stdio.mjs, providing the same 5 tools, with no environment variables or keys required.
• Implementation location: app/api/mcp/[transport]/route.ts, based on mcp-handler + @modelcontextprotocol/sdk, with tool definitions shared with the stdio entry point via lib/core/mcp-tools.ts, and the pure data layer in lib/core/.
• MCP Registry: already published as org.oravan/mcp, with server.json in the repository root, validated in CI by scripts/check-server-json.mjs.
• Documentation: oravan.org/mcp and docs/mcp-server-readme.md.

Design principles:

• Zero accounts: ZIP code, interests, and call history exist only in the visitor's device localStorage, with no user data on the server side.
• Static-first: bills, members, district offices, and ZIP-to-district mappings are all static JSON under data/, generating about 7,500 static pages at build time (the 2026-09-24 build produced 7,566 pages, including a page for each member of Congress and daily briefings). Server endpoints include /api/script (AI call script generation, cached by bill + stance + language + content version, IP rate-limited), /api/reps (pure query), /api/district (stateless split ZIP address refinement, proxying the Census geocoder, visitor IPs do not reach census.gov, addresses are not stored or logged), /api/mcp (MCP server), /api/brand, /api/stripe/webhook, /api/tenant/impressions, /embed/portrait/[bioguide].
• Bilingual-first: full English-Spanish UI via next-intl, with scripts generated in the user's language.
• Truth-first: present what Congress is actually doing in unbiased, plain language; understanding is the entry point, not task assignment.
• AI transparency: every generated summary and script is labeled on first contact, and before publication passes automated gates (bilingual completeness,Includes official records, each decode passes schema validation), the script is read by the caller before dialing and can be edited.
• Accessibility defaults: semantic landmarks, skip links, visible focus, prefers-reduced-motion, 44px+ touch targets, AA contrast.
• Member portraits come from the public-domain unitedstates/images project.

Use cases:

• Ordinary citizens who want to quickly understand active U.S. Congress bills and contact their representatives.
• Users who need bilingual (English/Spanish) congressional information.
• Privacy-sensitive users who do not want to create an account.
• AI assistant/agent developers who can access congressional data query tools via MCP.

Limitations and known issues:

• ZIP-to-district mapping is based on ZCTA; for split ZIPs, all candidate districts are shown by default (senators are unaffected); a street address can be entered (optional, sent once via POST, not stored or logged) to narrow to the actual district through the server-proxied Census geocoder.
• Geocoding requests are fixed to the "119th Congressional Districts" layer and will need to be upgraded when the Census updates to the 120th.
• Script caching and rate limiting are in shared Upstash storage; if not configured or if requests fail, it falls back to per-instance memory.
• New bills may lag behind Congress.gov: each night, up to MAX_NEW_DECODES new bills are decoded (cost cap), and the backlog is processed oldest-first.
• "Read" coverage is limited to top bills; the long tail is not shown; the Spanish interface shows the same English articles, with only the interface localized; outlets not in data/media-bias.json do not show a bias label.

License:

• Code: GNU AGPL-3.0, free to use, modify, and run (including as a network service), but modified versions that are operated or distributed must remain open source under the same license. Embedding Oravan-hosted components via a loader/script tag does not subject your website to the AGPL.
• Branding: the Oravan name, logo, and brand assets (assets/brand/, app icons) are not licensed, all rights reserved, and forks must use their own identity.
• Content: the underlying legislative data is a U.S. government work (public domain). AI-generated decodes and summaries are licensed under CC BY 4.0, consistent with the MCP citation envelope and citation pages.