Oravan

Oravan

議会へのあなたの窓口 · 議会へのあなたの窓口

Oravan は、無料で党派に偏らない市民向けインフラです。連邦議会の代表者を探し、審議中の法案を平易な言葉（英語とスペイン語）で理解し、30 秒で話せる電話用スクリプトを入手して、5 分以内に電話できます。アカウントは不要です。

MCP サーバー

このリポジトリでは、リモート MCP（Model Context Protocol）サーバーも実装しています。同じデコード済みコーパスと検索機能を、AI アシスタントやエージェント向けに公開します。

• エンドポイント（Streamable HTTP）： https://oravan.org/api/mcp/mcp — キー不要、読み取り専用、レート制限あり。アカウントや認証情報は不要です
• ローカル／stdio： npm ci の後に npx tsx scripts/mcp-stdio.mjs を実行します。stdio 経由で同じ 5 つのツールを利用でき、環境変数やシークレットは一切不要です
• 実装： app/api/mcp/[transport]/route.ts（mcp-handler と @modelcontextprotocol/sdk を基盤として構築）、stdio エントリーポイントと共有するツール定義は lib/core/mcp-tools.ts、純粋なデータレイヤーは lib/core/
• 5 つのツール： lookup_representatives、get_bill、search_bills、whats_moving、get_representative — すべての応答に、英語またはスペイン語の出典情報一式（ソース、データの鮮度基準日、AI 生成コンテンツのラベル、ライセンス）が含まれます
• 公式 MCP レジストリ： org.oravan/mcp として公開されています（リポジトリのルートにある server.json は、CI で scripts/check-server-json.mjs によりスキーマ検証されます）
• ドキュメント： oravan.org/mcp（ツールリファレンス、クライアント設定、プライバシー方針） · docs/mcp-server-readme.md

設計原則

1. アカウントは不要です。 郵便番号、関心事、通話履歴は、訪問者のデバイス上の localStorage に保存されます。サーバー側にユーザーデータは存在しないため、侵害、漏えい、召喚状の対象となるものはありません。これはリスクにさらされているユーザーを守るためのプライバシーの基本方針であり、未実装の機能ではありません。
2. 静的コンテンツを優先します。 法案、議員、地区事務所、郵便番号から選挙区への対応表は、data/ 内の静的 JSON であり、約7,500ページの静的生成ページに組み込まれています（2026-09-24 ビルドでは、連邦議会議員全員のページと日次ブリーフを含む7,566ページ）。高速で、ホスティング費用はほぼ無料で、負荷が高い状況にも耐えられます。サーバーエンドポイントは、/api/script（AI による通話スクリプト生成。法案、賛否、言語、コンテンツバージョンごとに共有ストアへキャッシュし、IP アドレス単位でレート制限）、/api/reps（純粋な検索）、/api/district（分割 ZIP コードの住所をステートレスに絞り込み。Census ジオコーダーへのプロキシとなるため、訪問者の IP アドレスが census.gov に届きません。住所は保存も記録もされません）、/api/mcp（以下の MCP サーバー）、/api/brand（パートナーサイト向けの AI テーマ提案。/embeds 設定ツールで使用しますが、埋め込み機能が再開するまで非表示です）、/api/stripe/webhook（パートナープランのプロビジョニング。署名シークレットが設定されるまで503を返します）、/api/tenant/impressions（パートナーが自身の埋め込み表示回数を読み取ります）、および埋め込み用の同一オリジン画像プロキシである /embed/portrait/[bioguide] です。リクエストごとにレンダリングされるページルートは2つあり、/reps（URL から郵便番号を読み取ります）と /nominations/[slug] です。tests/static-rendering.spec.ts には、その理由とともにこれらのルートが記載されています。
3. バイリンガル対応を中核機能とします。 next-intl による EN/ES の完全な UI を提供し、スクリプトはユーザーの言語で生成されます。
4. まず事実を伝え、次の自然な一歩として電話をかけてもらいます。 Oravan は、議会で実際に何が行われているかを、偏りなく平易な言葉で伝えることを重視します。理解は入口であり、課題を押しつけることはありません。通話機能は引き続き差別化要素です（ボイスメールも正当な手段として位置づけ、事務所は直接話した場合と同じように集計します。営業時間外の通話を推奨し、DC に加えて選挙区事務所も掲載します。「話せた」「ボイスメールを残した」「連絡がつかなかった」という結果はデバイス上に記録します）。まだ決定されていない案件について、解説された回答を得るたびに、2回以内の操作で通話スクリプトを完成できます。決定が下された後は（法律の成立、採決での否決など）、ページに結果と所属議員の投票内容を表示します。重要度を下げることはあっても、埋もれさせることはありません。(2026-07-26 改訂。それ以前は「電話をかける瞬間が製品です」。2026-09-28 に、まだ決定されていない案件に限定しました。tests/funnel.spec.ts に記載された3つの不変条件によって適用されます。)
5. AI について誠実であり続けます。 生成されたすべての要約とスクリプトは、初めて表示される時点で AI 生成と明記されます。また、自動チェックをすべて通過しない限り、公開されません。両方の言語が揃っていること、公式記録が添付されていること、すべてのデコードでスキーマチェックに合格することが必要です。必須フィールドが欠けたデコード結果は、未完成のまま保存せず破棄します。scripts/verify-sync.mjs はコーパス全体を再チェックし、何かをコミットする前にナイトリー実行を失敗させます。(2026-08-12 改訂：現在、このファイルのチェックのうち1つだけが残り、コミットの後に実行されます。scripts/check-cursor-age.mjs によるカーソル経過時間の上限チェックです。これはコーパスではなく進捗の指標です。カーソルが停滞していれば遅れが生じているということであり、コミット前にチェックすると、停滞した夜に、すでに費用をかけて完了したデコードまで破棄されてしまいます。ここに記載したコーパスのチェックはすべて変更されておらず、今もコミット前に実行されます。docs/constitution-log.md#cursor-age-2026-08-12 を参照してください。) 非党派的な表現は、法案のデコードではモデルへの草案作成指示であり、Big Questions では強制適用される用語チェック（lib/moments-gate.mjs）です。この2つは同じ保証ではなく、説明文で両者を曖昧にすることはありません。ナイトリーのデコード処理に人間の工程はなく、製品もそれを主張しません。実際に行うと説明している唯一の確認は、発信者がダイヤルする前に通話スクリプトを読み、編集できることです。(2026-08-06 改訂。それ以前は「ラベルが付き、編集可能で、通話前に人間が確認します」でした。docs/constitution-log.md の2026-07-25の改訂を参照してください。この行はその内容に従うべきでしたが、従っていませんでした。) AI コンテンツには最初に触れる時点でラベルが付けられ、通話スクリプトは通話を開始する前に発信者が読み、編集できます。最後の句が通話スクリプトだけを対象としているのは意図的です。デコードと Moment の更新概要は、人による確認を挟まず自動ゲートを通じて公開されるため、ラベルだけが開示のすべてです。ラベルはコンテンツと一緒に、スクロールせずに見える位置に表示します。脚注にはしません。（このファイルが廃止された 2026-09-27 に、DESIGN.md から移動しました。）
6. デフォルトでアクセシブル。 セマンティックなランドマーク、スキップリンク、視認可能なフォーカス、prefers-reduced-motion、44px 以上のタッチターゲット、AA コントラスト。

データソース

ファイル	ソース	更新
data/bills.json + data/bills-es.json	デコード済みの法案コーパス（Congress.gov の法案＋AI による平易な言葉での要約、英語とスペイン語）	毎晩の同期（sync-bills.yml 経由の scripts/sync-bills.mjs）：ステータスは随時更新されます。新しい法案は、公開前にデコードされ、英語とスペイン語の両方の要約が揃ってからコーパスに追加されます。各レコードには、デコードの作成元となったテキストのバージョンも保存されます。また、Congress がテキストを差し替えた法案は、後の夜間処理で新しいテキストから再読込されます。委員会での修正案によって、タイトルやステータスを変えずに文書が変更される場合も対象です。再読込は一晩あたり最大10件です（REDECODE_MAX_PER_NIGHT はコスト上限です。古いレコードのバックログは、緊急性の高い法案を優先しながら、一晩に数件ずつ解消されます）。
data/legislators.json	unitedstates/congress-legislators（パブリックドメイン）＋地区事務所	scripts/process-data.py
data/zip-districts.json	OpenSourceActivismTech/us_zipcodes_congress	同上
data/vacancies.json	取得データではなく、差分から生成されます。scripts/vacancy_diff.py は実行ごとに、現在コミット済みのデータと議席の集合を比較します。そのため、後任がいない退任議員の議席は、古い任期レコードから補完されて消えるのではなく、明示的な空席として（議員ページ、/api/reps、MCP の lookup_representatives に）表示されます。	scripts/process-data.py（legislators.json と同じ実行）
data/special-elections.json	各空席の特別選挙の日程。日付と FEC の選挙種別コードを含み、Federal Election Commission の選挙日 API に記載されたとおりです。確認日も記録されます。行がない場合はリストが空であり、日付を推測して記録することはありません。宣誓前に当選者を特定する公式の機械可読ソースがないため、当選者は記録されません。/reps の空席カードと、議席固有のページに表示されます。	scripts/sync-special-elections.mjs。refresh-legislators.yml 経由で毎週実行され、空席の差分確認の直後に処理されます（api.data.gov の公開 DEMO_KEY を使用し、シークレットは不要です。リクエストに失敗した場合は、最後のエントリと古い確認日を保持します）。
data/redistricting-watch.json	2025～26 年の中間年区割り変更について、係争中または最近変更があった10州を対象に、人が作成した（status／note）データです。rdh_lastmod は、Redistricting Data Hub の州ページサイトマップに対するトリップワイヤーの基準値です。詳しくは docs/solutions/two-clock-district-boundaries.md を参照してください。	scripts/check-redistricting-watch.mjs。refresh-legislators.yml 経由で毎週実行されます。変更があった場合は、常設のピン留め済み redistricting-watch issue 1件にコメントし、その本文を10州のステータス一覧として書き換えます。以前は変更のあった州ごとに issue を作成していましたが、6週間で10件に増え、そのうち8件は RDH サイト全体の再公開1回によるものでした。status／note が自動更新されることはありません。
data/nominations.json	第119議会の民間人向け上院人事指名（PN）。Congress.gov 独自の出典、説明文、最新の措置と、lib/nomination-status.mjs のルールテーブルで措置のテキストから導出したステータスを含みます。このファイルには AI を一切使用しません。Congress.gov の説明文はすでに平易な英語の一文なので、Oravan は指名をデコードしたり書き換えたりしません。そのため、/nominations/[slug] には上院独自の記録がそのまま表示され、その旨もページに記載されます。AI を使用するのは電話用スクリプトだけで、生成された箇所にその旨を表示します。指名が Big Question の対象になることもあります。カード、ページ、電話用スクリプトは常に最新です。以下の既知の v1 の制約に記載したカバレッジのタイトルと同様、/es でも英語のままです。軍の昇進名簿は対象外です（説明文がなく、候補者の名前も特定できません）。現時点で指名を公開する MCP ツールはありません。	scripts/sync-nominations.mjs（毎晩、無料リクエスト1回。scripts/check-nominations.mjs によるチェックを通過した場合に実行）
data/coverage.json	TheNewsAPI 経由で取得した、上位カテゴリの法案に関する実際のニュース記事（AI による関連性フィルタリング、Haiku）	scripts/sync-coverage.mjs（毎晩実行。NEWS_API_KEY が設定されている場合のみ実行）
data/media-bias.json	AllSides による報道機関の政治的傾向の評価。出典を明記し、CC BY-NC のもとで使用	ベンダー提供のスナップショット
肖像画像は、パブリックドメインのunitedstates/imagesプロジェクトから提供されています。

解決済みのパイプライン障害（根本原因と再発防止のための CI ゲート）は、docs/solutions/に記録されています。

「Read」セクション（報道機関のバイアスを示す記事）

各注目法案のページには、その法案に関する実際の第三者記事が掲載され、報道機関の政治的傾向（Left / Center / Right）が表示されます。AllSides の媒体ごとの評価を再利用しており、Oravan 独自の評価は一切作成していません。Oravan は立場を取らず、党派的な文章も執筆しません。AI は裏側でのみ使われます。各法案のニュース検索語（報道向けの名称と主題の検索語）の生成と、簡易な関連性判定（この記事はこの法案についてのものか？）に使われ、画面に表示する文章の執筆には使われません。取り込みは CI で毎晩実行され、結果は JSON に書き込まれるため、サイトから第三者への実行時リクエストは一切ありません。NEWS_API_KEYが設定されていない場合、同期は何もせず、セクションも表示されません。手作業で作成した実際のサンプル（data/coverage.json）が少量あるため、デモとして表示できます。政治的傾向はテキストラベルと配置のみで示し、政党カラーは使いません（厳守ルールです。CLAUDE.mdのルール 3 を参照）。

開発

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 dev

npm run buildは、両方のロケールですべての法案ページを静的に生成します。

v1 で把握している制限事項

• ZIP コードと選挙区の対応付けには ZCTA を使用しています。複数の選挙区にまたがる ZIP コードでは、既定ですべての候補選挙区が表示されます（上院議員には影響しません）。住所の入力は任意で、一度だけ POST で送信され、保存もログへの記録もされません。入力すると、サーバー経由の Census ジオコーダー照会によって実際の選挙区に絞り込まれます。ジオコーダーで判定できない場合は、すべての候補を表示する方法に適切にフォールバックします。ジオコーダーへのリクエストでは「119th Congressional Districts」レイヤーを指定しているため、Census が基準年を第 120 議会に更新した際には、この指定も更新する必要があります。
• スクリプトキャッシュとレート制限は、共有 Upstash ストア（lib/scriptcache.ts、lib/ratelimit.ts）に保存されます。これらのストアが設定されていない場合（ローカル開発、CI、プレビュー）、またはいずれかのストアへのリクエストが失敗した場合、リクエストを失敗させず、どちらもインスタンスごとのメモリを使います。
• 新しい法案の反映は Congress.gov より遅れることがあります。コスト上限により、夜間の同期でデコードできる新規法案は最大MAX_NEW_DECODES件です。そのため、同期機会を逃した後は、コーパスが数晩かけて追いつきます（公開前にデコードし、古いものからバックログを処理します）。
• 「Read」の記事は注目度の高い法案のみが対象です（対象外の法案には何も表示されません）。ES ロケールでは英語の記事が同じまま表示され、周辺の UI テキストのみがローカライズされます。data/media-bias.jsonにない報道機関には、政治的傾向のラベルが表示されません。

ライセンス

• コード：GNU AGPL-3.0。このコードは、改変したバージョンを運用または配布する場合に、同じライセンスの下で公開し続けることを条件に、ネットワークサービスとしての利用も含め、使用、改変、実行できます。Oravan のホスト型ウィジェットをローダー／スクリプトタグ経由でサイトに埋め込んでも、そのサイトに AGPL が適用されることはありません。これはコードの配布ではなく、当社のサービスの利用にあたるためです。
• **ライセンス対象外：**Oravan の名称、ロゴ、ブランド素材（assets/brand/、アプリアイコン）。すべての権利は留保されています。フォークには独自のアイデンティティを使用する必要があります。
• **コンテンツ：**基盤となる立法データは米国政府の著作物（パブリックドメイン）です。AI が生成したデコード結果と要約には CC BY 4.0 ライセンスが適用されます。これは MCP の引用エンベロープおよび引用ページに記載されているとおりです。