bill-commons

Bill Commons

Bill Commons 是一个公开的开源立法搜索平台，覆盖美国全部 50 个州及 DC 当前届期／两年会期的立法信息。平台提供网页搜索界面、REST API、MCP（Model Context Protocol）服务，以及公开的状态／覆盖范围页面。优先建设公共基础设施：普通搜索和合理的 API 使用不设付费墙——匿名调用者享有宽松的每日限额（每个 IP 每天 2,000 次请求，每个 /24 子网每天 5,000 次）；免费 API 密钥可进一步提高限额，只有高频／批量使用才收费。有关 API 密钥和完整语料快照，请参阅 /docs/bulk。

有关已确定的架构和数据模型，请参阅 docs/architecture/ARCHITECTURE.md。

生产环境

• Web：https://billcommons.org（搜索界面 + 公开状态／覆盖范围页面：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 密钥，也无需额外设置，只需运行一条命令：

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 和其他客户端：在 mcp.json 中将相同 URL 添加为 Streamable HTTP 服务。

提供 10 个工具，包括 search_legislation、get_bill_record、 compare_bill_versions 和 trace_legislative_history。完整操作指南（包括适用于不使用 MCP 的 Agent 的 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 作为可编辑安装包安装（分别作为数据模型和共享实用工具的唯一真实数据源），并安装 worker 软件包：.venv/bin/pip install -e workers/ingest。如果你要开发 API，也请安装 API 软件包：.venv/bin/pip install -e apps/api。

数据库

在环境中设置 DATABASE_URL（或设置在 ~/.config/billcommons/.env 中，该文件会作为备用配置读取，且绝不会提交到版本控制）：

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、数据摄取 worker 和 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 — 命令行参考、作业队列、刷新周期
• 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，了解负责任的漏洞披露方式。