bill-commons

Bill Commons

Bill Commons は、全米 50 州と DC の現会期／2 年会期を対象とする、公開されたオープンソースの立法検索プラットフォームです。ウェブ検索 UI、REST API、MCP（Model Context Protocol）サーバー、公開ステータス／対応状況ページを提供します。まず公共インフラとしての役割を重視しており、通常の検索や妥当な範囲の API 利用にペイウォールはありません。匿名の呼び出し元には十分な 1 日あたりの上限（IP あたり 1 日 2,000 リクエスト、/24 サブネットあたり 1 日 5,000 リクエスト）が適用され、無料の API キーで上限をさらに引き上げられます。有料となるのは、大量利用／一括利用のみです。API キーと全文書コーパスのスナップショットについては、/docs/bulk をご覧ください。

固定されたアーキテクチャとデータモデルについては、 docs/architecture/ARCHITECTURE.md をご覧ください。

本番環境

• Web：https://billcommons.org（検索 UI ＋ https://status.billcommons.org の公開ステータス／対応状況ページ）
• API：https://api.billcommons.org/api/v1 — 対話型 OpenAPI ドキュメントは https://api.billcommons.org/docs
• MCP（Streamable HTTP）：https://mcp.billcommons.org/mcp

Railway（プロジェクト billcommons：api、mcp、worker サービス＋マネージド Postgres）と Vercel（プロジェクト billcommons-web）でホストされています。デプロイ／ロールバックの手順全体については、 docs/operations/deployment-runbook.md をご覧ください。

Claude（または任意の MCP クライアント）での利用

ホスト型 MCP サーバーを使うと、AI アシスタントが 209k 件以上のすべての法案に直接アクセスできます。API キーは不要で、1 つのコマンド以外のセットアップも不要です。

claude mcp add bill-commons --transport http https://mcp.billcommons.org/mcp

Claude Desktop：Settings → Connectors → Add custom connector で URL https://mcp.billcommons.org/mcp を指定します。Cursor などのクライアントでは、同じ URL を mcp.json に Streamable HTTP サーバーとして追加します。

search_legislation、get_bill_record、compare_bill_versions、trace_legislative_history など、10 個のツールを利用できます。詳細な手順（MCP を利用しないエージェント向けの REST の使用例を含む）： https://billcommons.org/docs/agents

アーキテクチャの概要

                    ┌─────────────┐
   users ─────────▶ │  apps/web   │  Next.js, billcommons.org
                    │ (Vercel)    │  status.billcommons.org (rewrite → /coverage)
                    └──────┬──────┘
                           │ HTTPS (NEXT_PUBLIC_API_BASE)
                           ▼
                    ┌─────────────┐        ┌──────────────┐
                    │  apps/api   │◀──────▶│  apps/mcp    │  Streamable HTTP
                    │  FastAPI    │        │  10 MCP tools│  mcp.billcommons.org
                    │ /api/v1     │        └──────────────┘
                    │ api.billcommons.org
                    └──────┬──────┘
                           │ reads (SQLAlchemy)
                           ▼
                    ┌─────────────────────────────┐
                    │   Postgres 16 (Railway)      │
                    │  jurisdictions, sessions,     │
                    │  bills, actions, sponsorships,│
                    │  votes, ingest_jobs, coverage  │
                    └──────────────▲──────────────┘
                                   │ writes (idempotent upserts)
                    ┌──────────────┴──────────────┐
                    │  workers/ingest (worker svc)  │
                    │  autoboot: seed → bootstrap →│
                    │  schedule-refresh → job loop  │
                    │  sources: Open States bulk CSV│
                    │  (T2 bootstrap) + v3 API (T2  │
                    │  incremental, OPENSTATES_API_ │
                    │  KEY) + full-text fetcher     │
                    └──────────────┬──────────────┘
                                   ▼
                    RawStore (filesystem, RAWSTORE_ROOT
                    volume in prod) — sha256-addressed
                    raw payload archive

packages/schema（SQLAlchemy モデル＋Alembic）は、他のすべてのパッケージ／アプリがインポートする唯一の信頼できる情報源です。どのサービスも独自のデータモデルを持ちません。

モノレポの構成

apps/web        Next.js 15 (App Router, TS) — search UI + status page
apps/api        FastAPI — REST API (/api/v1)
apps/mcp        MCP server (Streamable HTTP, mounted at /mcp)
workers/ingest  Ingestion workers, job queue, per-source adapters
packages/schema SQLAlchemy models + Alembic migrations (single source of truth)
packages/shared Shared Python utils: bill-number normalization, rawstore, http client
packages/source-registry  Per-jurisdiction source registry (data + loader)
packages/search Search SQL builders / query parsing
infra/docker    Dockerfiles + docker-compose.yml (local stack)
infra/deployment Railway/Vercel configs, DNS runbook
docs/           Architecture, API, sources, operations, state-coverage docs
data/registry   Machine-readable registry (sessions, sources)

ローカル開発環境のセットアップ

前提条件

• Python 3.12
• PostgreSQL 16（pg_trgm、unaccent、pgcrypto 拡張機能が利用可能であること）
• Node.js 20 以降（apps/web 用）

Python 環境

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

これにより、packages/schema と packages/shared が編集可能なインストールとしてインストールされます（データモデルと共有ユーティリティの唯一の信頼できる情報源）。さらに、ワーカーパッケージもインストールされます：.venv/bin/pip install -e workers/ingest。API に取り組む場合は、API パッケージもインストールしてください：.venv/bin/pip install -e apps/api。

データベース

環境変数（またはフォールバックとして読み込まれる ~/.config/billcommons/.env。このファイルはコミットされません）に DATABASE_URL を設定します。

DATABASE_URL=postgresql://user:password@host:port/dbname

pg_trgm と unaccent 拡張機能が利用可能な Postgres 16 が必要です（マイグレーション 0001 によって作成されます）。マイグレーションを実行します。

cd packages/schema
../../.venv/bin/alembic upgrade head

ローカルでのデータのシード

# Seed all 51 jurisdictions/sessions/coverage rows from the registry:
.venv/bin/python -m billcommons_ingest seed-registry

# Download a state's Open States bulk-CSV zip and ingest it (see
# docs/operations/ingestion-runbook.md for the full command reference):
python3 workers/ingest/download_bulk.py --only NC
.venv/bin/python -m billcommons_ingest bootstrap --state NC --zip data/bulkzips/NC_2025.zip
.venv/bin/python -m billcommons_ingest recompute-coverage

アプリのローカル実行

# API (FastAPI, http://localhost:8000, docs at /docs)
.venv/bin/uvicorn main:app --app-dir apps/api --reload --port 8000

# MCP server (Streamable HTTP, http://localhost:8400/mcp by default)
.venv/bin/python apps/mcp/server.py

# Ingestion worker (long-running queue loop; runs schedule-refresh
# periodically inside the same process)
.venv/bin/python -m billcommons_ingest worker

# Web app (Next.js — separate from the Python stack)
cd apps/web
npm install
NEXT_PUBLIC_API_BASE=http://localhost:8000 npm run dev

テスト

.venv/bin/pytest packages/shared/tests
.venv/bin/pytest workers/ingest/tests
.venv/bin/pytest apps/api/tests

Docker を使ったローカルでのスタック実行

cd infra/docker
docker compose up --build

これにより、Postgres、API、取り込みワーカー、MCP サーバーが起動します。Web アプリ（apps/web）は、ローカル開発中に npm run dev で別途実行します（プレースホルダーのサービス定義については infra/docker/docker-compose.yml をご覧ください）。

ドキュメント

• docs/architecture/ARCHITECTURE.md — 確定済みのアーキテクチャとデータモデル
• docs/SPEC.md — 要件の概要／受け入れ基準
• docs/operations/deployment-runbook.md — Railway/Vercel のデプロイ、ロールバック、スモークテストのチェックリスト
• docs/operations/ingestion-runbook.md — CLI リファレンス、ジョブキュー、更新頻度
• docs/operations/source-failure-runbook.md — 古い ZIP、401/429、robots によるブロック
• docs/operations/backup-restore.md — pg_dump／復元、未加工データの再取得
• docs/operations/add-a-jurisdiction.md — 新しい地域／州のオンボーディング
• docs/state-coverage/methodology.md — カバレッジの状態遷移、GREEN の基準
• docs/api/examples.md — 稼働中の API を使った curl／Python／JavaScript の例
• docs/sources/openstates-csv.md — Open States の一括 CSV の列マッピング

ライセンス

Apache-2.0。LICENSE および NOTICE を参照してください。データの帰属情報 （Open States / Plural Policy、パブリックドメインの立法データ）。

コントリビューション

CONTRIBUTING.md を参照してください。このプロジェクトは Contributor Covenant に準拠しています。

セキュリティ

責任ある脆弱性開示については SECURITY.md を参照してください。