Oravan's server provides read-only, keyless access to U.S. federal legislative and representative data, with bilingual (EN/ES) support and citation envelopes on every response.
lookup_representatives: Find a constituent's U.S. House member and two Senators by 5-digit ZIP code — returns names, party, phone numbers, official websites, portrait URLs, and district office contact info. Handles split-ZIP situations and explicitly surfaces vacant seats.
get_bill: Retrieve a full plain-language decode of any federal bill by slug (e.g. hr-2701-119) or citation (e.g. H.R. 2701). Includes summary, what/who/why/cost breakdown, official status, urgency band, sponsor, key dates, and links to Congress.gov.
search_bills: Search the bilingual federal bill corpus using free-text queries, issue topic filters (e.g. health, immigration, housing), status filters, and an active-only flag. Results are returned most urgent first.
whats_moving: Discover recently active bills that have cleared Oravan's "act now" urgency threshold within a configurable lookback window (default 7 days, up to 90), optionally filtered by topic. Honestly returns an empty list with a quiet_week flag when nothing qualifies — never pads results.
get_representative: Get comprehensive details on a specific member of Congress by Bioguide ID, including their 5 most recently active sponsored bills. Strictly factual — no scorecards or vote grades.
All tools require no API key and include a citation envelope detailing source, data freshness, AI-content label, and license.
Your line to Congress · Tu línea con el Congreso
Oravan is free, nonpartisan civic infrastructure: find your federal representatives, understand active bills in plain language (English and Spanish), get a 30-second call script, and make the call — in under 5 minutes, with no account.
The name is the Oravan: the platform in the Roman Forum where citizens stood to address the public and the powerful — the original place a voice met power. Latin roots are the shared ancestry of English and Spanish alike.
This repository also implements a remote MCP (Model Context Protocol) server — the same decoded corpus and lookups, exposed for AI assistants and agents:
Endpoint (Streamable HTTP): https://oravan.org/api/mcp/mcp — keyless, read-only, rate-limited; no account or credentials required
Local/stdio: npm ci then npx tsx scripts/mcp-stdio.mjs — the same 5 tools over stdio, zero env vars/secrets required
Implementation: app/api/mcp/[transport]/route.ts (built on mcp-handler + @modelcontextprotocol/sdk), tool definitions shared with the stdio entry via lib/core/mcp-tools.ts, pure data layer in lib/core/
Five tools: lookup_representatives, get_bill, search_bills, whats_moving, get_representative — every response carries a citation envelope (source, as-of freshness, AI-content label, license) in English or Spanish
Official MCP Registry: published as org.oravan/mcp (server.json at the repo root, schema-validated in CI by scripts/check-server-json.mjs)
Docs: oravan.org/mcp (tool reference, client config, privacy posture) · docs/mcp-server-readme.md
Related MCP server: CongressMCP-full
Zero accounts. ZIP code, interests, and call history live in localStorage on the visitor's device. No server-side user data exists — nothing to breach, leak, or subpoena. This is the core privacy posture for at-risk users, not a missing feature.
Static-first. Bills, legislators, district offices, and ZIP→district mappings are static JSON in data/, baked into ~1,000 statically generated pages. Fast, nearly free to host, resilient under load. The only dynamic endpoints are /api/script (AI script generation, cached per bill+stance+language, IP rate-limited), /api/reps (pure lookup), /api/district (stateless split-ZIP address refinement: proxies the Census geocoder so the visitor's IP never reaches census.gov; the address is never stored or logged), and /api/feedback (beta feedback relayed to a private GitHub issue — only what the visitor volunteered, no identifiers).
Bilingual as a first-class feature. Full EN/ES UI via next-intl; scripts are generated in the user's language.
Truth first; the call is the natural next step. Oravan leads as an unbiased, plain-words account of what Congress is actually doing — understanding is the front door, never an assignment. The call apparatus stays the differentiator (voicemail legitimized, offices tally it identically; after-hours calling encouraged; district offices listed alongside DC; outcomes — spoke / voicemail / couldn't reach — logged locally on the device), and every decoded answer keeps a completed call script within two interactions. Demoted, never buried. (Amended 2026-07-26; previously "The call moment is the product." Enforced by the three named invariants in tests/funnel.spec.ts — see DESIGN.md structural constraint 2.)
Honest about AI. Every generated summary and script is labeled at first contact, and nothing publishes unless the automated gates pass: both languages present, the official record attached, and a schema check on every decode — a decode that comes back missing a required field is discarded rather than stored half-written, and scripts/verify-sync.mjs re-checks the whole corpus and fails the nightly run before it is allowed to commit anything. (Amended 2026-08-12: one check left that file and now runs AFTER the commit — the cursor-age ceiling in scripts/check-cursor-age.mjs. It is a progress signal, not a corpus one: a stalled cursor means we are behind, and failing it before the commit made a stalled night throw away a night of already-paid decodes. Every corpus check named here is unchanged and still runs before anything is committed. See CLAUDE.md's amendment of the same date.) Nonpartisan wording is a drafting instruction to the model on bill decodes and an enforced vocabulary lint on Big Questions (lib/moments-gate.mjs) — the two are not the same guarantee, and the copy never blurs them. The nightly decode path has no human step and the product never claims one; the one review it does claim is real: a caller reads, and can edit, the call script before dialing. (Amended 2026-08-06; previously "labeled, editable, and reviewed by the human before any call." See CLAUDE.md's 2026-07-25 amendment, which this line should have followed and did not.)
Accessible by default. Semantic landmarks, skip link, visible focus, prefers-reduced-motion, 44px+ touch targets, AA contrast.
File | Source | Refresh |
| Decoded bill corpus (Congress.gov bills + AI plain-language summaries, English and Spanish) | Nightly sync ( |
| unitedstates/congress-legislators (public domain) + district offices |
|
| same | |
| Derived, not fetched: |
|
| Human-authored ( |
|
| Civilian Senate nominations (PNs) of the 119th Congress — Congress.gov's own citation, description sentence, and latest action, plus a status derived from that action text by |
|
| Real news articles about top-band bills via TheNewsAPI, AI-relevance-filtered (Haiku) |
|
| Outlet political-lean ratings by AllSides, used under CC BY-NC with attribution | Vendored snapshot |
Portraits are served from the public-domain unitedstates/images project.
Solved pipeline incidents (root cause + the CI gates that prevent recurrence) are documented in docs/solutions/.
Each top bill's page shows real third-party articles about it, labeled by the outlet's political lean (Left / Center / Right) — reusing AllSides' publication-level ratings, never a Oravan-invented one. Oravan takes no stance and authors no partisan text: AI is used only behind the scenes — generating each bill's news-search terms (press-style names and a subject query) and a cheap relevance gate (is this article about this bill?) — and authors nothing displayed. The ingestion runs nightly in CI and bakes results to JSON, so the site still makes zero runtime third-party calls. Without NEWS_API_KEY the sync is a no-op and the section renders nothing; a small hand-built real sample (data/coverage.json) keeps it demoable. Lean is shown by text label + position only — never party colors (a hard rule; see DESIGN.md).
npm install
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env.local # script generation + decode/relevance
echo "NEWS_API_KEY=..." >> .env.local # optional; enables the "Read" coverage sync
npm run devnpm run build statically generates every bill page in both locales.
ZIP→district mapping is ZCTA-based; a split ZIP shows all candidate districts by default (senators are unaffected). Entering a street address — optional, sent once by POST, never stored or logged — narrows it to the actual district via a server-proxied Census-geocoder lookup; the all-candidates view remains the graceful fallback whenever the geocoder can't help. The geocoder request pins the "119th Congressional Districts" layer, which needs a bump when the Census rolls the vintage to the 120th.
Script cache and rate limits are in-memory per serverless instance — fine at demo scale, should move to a shared store before heavy traffic.
New bills can lag behind Congress.gov: the nightly sync decodes at most MAX_NEW_DECODES new bills per run (cost ceiling), so after a missed window the corpus catches up over several nights (decode-before-publish; the backlog drains oldest-first).
"Read" coverage exists only for top-band bills (the long tail shows nothing); the ES locale shows the same English articles with localized chrome; outlets absent from data/media-bias.json appear without a lean chip.
Code: GNU AGPL-3.0. You may use, modify, and run this code — including as a network service — provided modified versions you operate or distribute remain open under the same license. Embedding Oravan's hosted widgets on your site via the loader/script tag does not subject your site to the AGPL; that's use of our service, not distribution of this code.
Not licensed: the Oravan name, logo, and brand assets (assets/brand/, app icons). All rights reserved — forks must use their own identity.
Content: underlying legislative data is U.S. government work (public domain). AI-generated decodes and summaries are licensed CC BY 4.0, exactly as declared in the MCP citation envelope and on the citations page.
Get the full plain-language decode of a federal bill by slug (e.g. "hr-2701-119") or citation (e.g. "H.R. 2701" - resolves to the most recent Congress on a match). Returns the AI-generated summary (headline, tl;dr, what/who/why/cost - automatically checked before publish and clearly labeled when present), the official status in plain language, an urgency band, sponsor, key dates, the official Congress.gov page, and an act_url to Oravan's on-site call flow. This tool never drafts a phone script - script generation happens only on-site, where the caller reads and can edit the script before dialing; that is not available over this API.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | No | Bill slug, e.g. "hr-2701-119". Takes priority over citation when both are given. | |
| locale | No | Response language: "en" (default) or "es". | |
| citation | No | Bill citation, e.g. "H.R. 2701" or "S.J.Res. 99". Used only when slug is omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: true and openWorldHint: false, and the description adds valuable context: AI summaries are auto-checked before publishing, citation resolution defaults to the most recent Congress, and script generation is not available through the API. This goes beyond the base annotations, though it could mention error behavior or data freshness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense sentence but is structured logically, starting with the core action and then detailing the return payload and a key limitation. It is verbose yet every phrase contributes meaningful detail, with no fluff. Breaking it into two sentences could improve readability without adding bulk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main aspects: purpose, input methods, output fields (summary, status, urgency, sponsor, dates, URLs), and a critical limitation. Given the tool's moderate complexity and absence of an output schema, this is largely complete. Minor gaps include no mention of error conditions, rate limits, or handling of invalid slugs/citations, which could be inferred from typical API behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema provides basic parameter descriptions, the tool description enriches understanding by explaining that slug takes priority over citation, how citations are resolved, and gives realistic examples. The explicit mention of the precedence rule and the 'most recent Congress' behavior adds semantic value that the schema alone does not convey. This helps the agent use parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: getting a full plain-language decode of a federal bill using either a slug or citation. It distinguishes itself from sibling tools by focusing on bill-specific data and explicitly noting it never drafts a phone script, setting it apart from the on-site call flow and other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to invoke the tool (by slug or citation) and the priority of slug over citation, which helps in usage. It also clarifies a limitation (no script drafting). However, it does not explicitly compare this tool to siblings like search_bills or what to do when a bill ID is unknown. A direct 'when to use this instead of search_bills' would be an improvement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full details for one member of Congress by bioguide ID (e.g. "W000797"), plus their 5 most recently active sponsored bills. Facts only: no scorecards, ratings, or vote grades.
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | Response language: "en" (default) or "es". | |
| bioguide | Yes | Bioguide ID, e.g. "W000797". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true, confirming no side effects. The description adds behavioral traits: returns exactly 5 most recently active sponsored bills and limits to factual data. It does not contradict annotations and provides useful context about what is included and excluded.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose. Every sentence adds value: first sentence defines the tool, second sentence clarifies constraints. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides a good sense of the response: 'full details' plus 5 bills. It covers the key constraints (by bioguide, facts only) and is sufficient for agent decision. Minor lack of exact field names, but overall complete for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains both parameters (bioguide ID example, locale options). The description reinforces the bioguide example but does not add new meaning beyond what is in the schema. Thus baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'full details for one member of Congress', and the method 'by bioguide ID'. It also specifies additional included data (5 most recently active sponsored bills). This distinguishes it from sibling tools like lookup_representatives (search) and get_bill (bill-focused).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'Facts only: no scorecards, ratings, or vote grades,' which informs the agent when not to use this tool (i.e., when opinionated data is needed). It implicitly suggests using this when you have a bioguide ID and require comprehensive details plus recent bills, though alternatives are not explicitly named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up a person's U.S. House member and two Senators by 5-digit ZIP code. Returns each member's name, party, phone, official website, portrait URL, and district office phone numbers - the number a constituent should actually call. Some ZIP codes span more than one congressional district (needs_address: true, all candidate districts returned); this tool does not perform address-level refinement itself in this release - point the person to the response's reps_url, where a stateless, unlogged Census-geocoder proxy narrows it to a single district from a street address that Oravan never stores. When a House seat currently has no member, vacancies lists the empty seat(s) (state + district) explicitly - the departed member is never returned as if still serving, and no election timeline is implied.
| Name | Required | Description | Default |
|---|---|---|---|
| zip | Yes | 5-digit U.S. ZIP code. | |
| locale | No | Response language: "en" (default) or "es". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds rich context beyond annotations: details on multi-district behavior, vacancy handling, and the reps_url proxy, ensuring agents understand exactly what the tool does and its limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is thorough but slightly verbose; however, every sentence adds value and it is well-structured with front-loaded purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers major edge cases (multi-district, vacancies) and return fields, but lacks explicit output schema; still complete enough for a lookup tool given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description confirms usage of zip and locale but does not add significant parameter-specific details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it looks up U.S. House member and two Senators by 5-digit ZIP code, listing returned fields and handling of multi-district ZIPs and vacancies, distinguishing it from sibling tools like get_representative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains when to use (by ZIP), limitations (multi-district ZIPs require address refinement), and how vacancies are handled, providing clear guidance on when not to use this tool alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Oravan's bilingual federal bill corpus by free-text query, issue topic, status, or active-only. Returns short teasers (headline, status, urgency) for matching bills, most urgent first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 20, max 50). | |
| query | No | Free-text search over the bill title and plain-language summary. | |
| topic | No | One of the 12 issue categories. | |
| locale | No | Response language: "en" (default) or "es". | |
| status | No | Bill status to filter to. | |
| active_only | No | Exclude signed/vetoed (terminal) bills when true. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, so the description doesn't need to reiterate. It adds no further behavioral traits like rate limits or authorization needs, and the output description is about result format, not behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and scope, no wasted words. Efficient and clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the output format (teasers with headline, status, urgency) and ordering (most urgent first), which is important since there is no output schema. It covers the main search dimensions but lacks differentiation from sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives a high-level summary of parameter usage (free-text, topic, status, active-only) but adds no meaning beyond the schema. Schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Oravan's bilingual federal bill corpus by multiple criteria (free-text, topic, status, active-only) and returns teasers. It distinguishes from siblings like get_bill by being a search function over a corpus.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for finding bills via criteria but does not explicitly contrast with sibling tools such as get_bill, get_representative, or whats_moving. However, the context of search vs. single-bill retrieval is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What's moving in Congress recently: active, plain-language-decoded bills that cleared Oravan's 'act now' urgency bar within the last N days (default 7), optionally filtered by topic. Returns an honest empty list with quiet_week: true when nothing has cleared the bar - this tool never pads the list to look busier than Congress actually is this week. If the list is empty because Oravan's own data sync looks stale rather than Congress being quiet, data_stale is set instead so that distinction is never lost.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Lookback window in days (default 7). | |
| limit | No | Max results (default 10, max 50). | |
| topic | No | One of the 12 issue categories. | |
| locale | No | Response language: "en" (default) or "es". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true. The description adds valuable behavioral context: it returns an honest empty list, never pads results, and distinguishes between quiet_week and data_stale. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the core purpose, then adding edge-case details. It is efficient, but slightly longer than necessary; a shorter version could preserve all key points.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by explaining the return behavior (quiet_week, data_stale). It covers the filtering criteria and output shape adequately for the tool's complexity. However, it could mention the fields of the returned bills.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description restates defaults (7 days, limit 10) already in the schema, but adds no new semantic detail beyond what the schema provides. Thus, it does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource as 'active, plain-language-decoded bills' that cleared an urgency bar, with optional topic filtering. It distinguishes from siblings like search_bills (broader search) and get_bill (single bill), making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (to find urgent bills) and details edge cases like quiet_week and data_stale, which guide appropriate usage. However, it does not explicitly state when to avoid this tool in favor of siblings like search_bills.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_billget_representativelookup_representativessearch_billswhats_movingEach tool targets a distinct operation—ZIP lookup, individual bill lookup, individual representative lookup, bill search, and recent urgent activity—so there is little real overlap. The only mild ambiguity is between lookup_representatives and get_representative, since both are compound person lookups, but their inputs and results are clearly different enough.
Four tools follow a clean verb_noun pattern: lookup_representatives, get_bill, get_representative, and search_bills. The outlier is whats_moving, which uses a question-style phrase rather than a verb_noun convention, creating a minor but noticeable inconsistency.
Five tools is a well-scoped set for a civic-information server: coverage for people, bills, search, and timely activity. Each tool earns its place and no tool feels redundant or extraneous.
The tool surface covers the core workflows: finding a representative address, checking bill details, searching the bill corpus, and surfacing urgent action items. Minor gaps exist—such as not allowing address-level district refinement and avoiding phone script generation over the API—but those are explicitly described as intentional design boundaries rather than broken workflows.
Access U.S. congressional data - bills, votes, members, committees - via MCP.
GovTrack MCP — federal US Congress data (free, no auth)
Congress MCP — US Congress data via GovTrack API (free, no auth required)
An MCP server that provides congressional transcripts
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cm2489/oravan'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
