Bill Commons

Bill Commons

Bill Commons is a public, open-source legislative search platform covering the current session/biennium for all 50 U.S. states plus DC. It provides a web search UI, a REST API, an MCP (Model Context Protocol) server, and a public status/coverage page. Public infrastructure first: no paywall on ordinary search or reasonable API use — anonymous callers get a generous daily cap (2,000 requests/day per IP, 5,000/day per /24 subnet); a free API key raises that further, and only high-volume/bulk use is paid. See /docs/bulk for API keys and full-corpus snapshots.

See docs/architecture/ARCHITECTURE.md for the locked architecture and data model.

Production

• Web: https://billcommons.org (search UI + public status/coverage page at https://status.billcommons.org)
• API: https://api.billcommons.org/api/v1 — interactive OpenAPI docs at https://api.billcommons.org/docs
• MCP (Streamable HTTP): https://mcp.billcommons.org/mcp

Hosted on Railway (project billcommons: api, mcp, worker services + managed Postgres) and Vercel (project billcommons-web). See docs/operations/deployment-runbook.md for the full deploy/rollback procedure.

Use with Claude (or any MCP client)

The hosted MCP server gives AI assistants direct access to all 209k+ bills — no API key, no setup beyond one command:

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

Claude Desktop: Settings → Connectors → Add custom connector with URL https://mcp.billcommons.org/mcp. Cursor and other clients: add the same URL as a Streamable HTTP server in mcp.json.

Ten tools including search_legislation, get_bill_record, compare_bill_versions, and trace_legislative_history. Full walkthrough (including REST recipes for agents without MCP): https://billcommons.org/docs/agents

Architecture at a glance

                    ┌─────────────┐

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 models + Alembic) is the single source of truth every other package/app imports from — no service owns its own copy of the data model.

Monorepo layout

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)

Local development setup

Prerequisites

• Python 3.12
• PostgreSQL 16 (with pg_trgm, unaccent, pgcrypto extensions available)
• Node.js 20+ (for apps/web)

Python environment

python3 -m venv .venv

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

This installs packages/schema and packages/shared as editable installs (single source of truth for the data model + shared utils), plus the worker package: .venv/bin/pip install -e workers/ingest. Install the API package too if you're working on it: .venv/bin/pip install -e apps/api.

Database

Set DATABASE_URL in your environment (or in ~/.config/billcommons/.env, which is read as a fallback and is never committed):

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

Requires Postgres 16 with the pg_trgm and unaccent extensions available (created by migration 0001). Run migrations:

cd packages/schema

../../.venv/bin/alembic upgrade head

Seeding data locally

# 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

Running the apps locally

# 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

Tests

.venv/bin/pytest packages/shared/tests

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

Running the stack locally with Docker

cd infra/docker

docker compose up --build

This brings up Postgres, the API, the ingestion worker, and the MCP server. The web app (apps/web) is run separately via npm run dev during local development (see infra/docker/docker-compose.yml for the placeholder service definition).

Documentation

• docs/architecture/ARCHITECTURE.md — locked architecture + data model
• docs/SPEC.md — requirements digest / acceptance gate
• docs/operations/deployment-runbook.md — Railway/Vercel deploy, rollback, smoke checklist
• docs/operations/ingestion-runbook.md — CLI reference, job queue, refresh cadence
• docs/operations/source-failure-runbook.md — stale zips, 401/429, robots blocks
• docs/operations/backup-restore.md — pg_dump/restore, raw-data re-fetch
• docs/operations/add-a-jurisdiction.md — onboarding a new territory/state
• docs/state-coverage/methodology.md — coverage state machine, GREEN criteria
• docs/api/examples.md — curl/Python/JavaScript examples against the live API
• docs/sources/openstates-csv.md — Open States bulk CSV column mapping

License

Apache-2.0. See LICENSE and NOTICE for data attribution (Open States / Plural Policy, public-domain legislative data).

Contributing

See CONTRIBUTING.md. This project follows the Contributor Covenant.

Security

See SECURITY.md for responsible disclosure.