congressgov-mcp-server

---

概述

来自 Congress.gov 和参议院官方投票源的美国国会数据：法案、已颁布法律、议员、委员会、唱名投票、提名、国会研究处（CRS）报告和委员会报告，以及《国会记录》。浏览立法活动，阅读法案和报告正文，并追踪提名的参议院确认进程。

工具

工具	说明
congressgov_bill_lookup	浏览和检索法案：行动、提案人、摘要、正文、相关法案
congressgov_enacted_laws	按届次浏览已颁布的公法和私法
congressgov_member_lookup	按州、选区或届次查找议员，并检索其立法履历
congressgov_committee_lookup	浏览委员会及其立法、报告和提名
congressgov_roll_votes	检索众议院和参议院的唱名投票，以及每位议员的立场
congressgov_senate_nominations	浏览总统提名并追踪参议院确认进程
congressgov_bill_summaries	浏览最近更新的 CRS 法案摘要
congressgov_crs_reports	浏览和检索 CRS 的无党派政策报告
congressgov_committee_reports	浏览和阅读随立法附上的委员会报告
congressgov_daily_record	浏览和阅读每日《国会记录》
congressgov_search_bills	通过本地全文镜像按关键词搜索法案标题和 CRS 摘要（可选启用）

资源

资源	描述
congress://current	当前国会届次、会期日期、议院信息
congress://bill-types	有效法案类型代码的参考表
congress://member/{bioguideId}	按 bioguide ID 查询议员简介
congress://bill/{congress}/{billType}/{billNumber}	按国会届次、类型和编号查询法案详情
congress://committee/{committeeCode}	按委员会代码查询委员会详情

法案、议员和委员会数据也可通过 congressgov_bill_lookup、congressgov_member_lookup 和 congressgov_committee_lookup（操作 get）访问，因为许多 MCP 客户端仅支持工具，不会显示资源。

提示词

提示词	描述
congressgov_bill_analysis	用于分析法案的结构化框架
congressgov_legislative_research	用于研究跨届国会某个政策领域的框架

功能参考

congressgov_bill_lookup _工具

• list 可浏览一个 congress，按 billType 和记录更新日期的 fromDateTime/toDateTime 范围缩小结果；默认按最新优先排序，除非指定 order: 'oldest'；get、actions、amendments、cosponsors、committees、subjects、summaries、text、titles、related 和 content 需要 congress + billType + billNumber
• 法案条目中的 type 和 number 可分别用作 billType 和 billNumber；法案类型代码不区分大小写。每个字段仅传入一个名称，因为同时提供规范键和别名键会被拒绝
• content 会读取 textVersionIndex 指定的文本版本（0 表示最新版本），并在 content.text 中返回一个字符窗口，同时提供 totalCharacters、truncated 和 nextOffset
• summaries 接受可选的 versionCode（00 表示提出版本，49 表示公法版本），并像 congressgov_bill_summaries 一样分页，使用 characterOffset/characterLimit

---

congressgov_enacted_laws _工具

• list 可浏览一个 congress，并可按 lawType（pub 或 priv）筛选；这是 congressgov_bill_lookup 不具备的颁布筛选条件；get 需要 lawType + lawNumber，可从列表条目的 laws[].number（118-90）或其纯编号（90）中获取
• get 返回起源法案记录，法案引文位于其 laws[] 数组中

---

congressgov_member_lookup _工具

• 不支持按姓名搜索：list 可按 stateCode（以及 district；若为单一选区，则为 0，且需要 stateCode）、congress 和 currentMember 筛选
• get 返回指定 bioguideId 的议员简介（例如 P000197）；sponsored 和 cosponsored 返回该议员提出或共同提出的立法

---

congressgov_committee_lookup _工具

• committeeCode 由议院前缀（h/s/j）、字母和 2 位后缀组成（例如 hsju00）；get、bills、reports 和仅限参议院的 nominations 会根据前缀推断 chamber
• 如果 committeeCode 中的委员会名称仅匹配一个委员会，则会解析该名称；否则会返回候选条目并附带提示；list 搭配 filter 时会在范围内匹配所有委员会名称，模糊匹配结果带有 approximate: true
• bills 默认按最新优先排序（order），其条目不包含标题，因此需要为每个条目接续调用 congressgov_bill_lookup 的 get

---

congressgov_roll_votes _工具

• chamber 可设为 house（默认，Congress.gov API）或 senate（参议院的 LIS 数据源）；每次调用都需要 congress + session（1 或 2），而 get/members 还需要 voteNumber；该编号在每个会期重新计数，并且仅适用于一个议院
• list 默认按最新优先排序，除非指定 order: 'oldest'；get 返回问题、结果、票数统计和党派细分，members 返回每位议员的立场
• 参议院投票记录始于第 101 届国会（1989 年）；参议院条目会将数据源中不含年份的 voteDate 与推导出的 voteDateIso 配对

congressgov_senate_nominations _工具

• list 浏览一个 congress；get、actions、committees、hearings 和 nominees 需要 nominationNumber（PN1000 对应 1000），而 nominees 还需要 get 返回的 nominees 数组中的 ordinal
• 多部分提名（例如 PN851）的活动分别记录在分区子项中（851-1、851-2 等）；对未分区的编号调用空子资源时，会返回指向这些子项的提示

---

congressgov_bill_summaries _工具

• congress 和 billType 均为可选（billType 需要同时提供 congress）；fromDateTime/toDateTime 按摘要的更新时间筛选，而非法案的行动日期；两者均省略时，默认涵盖最近 7 天
• 单页在序列化字符数达到 50,000 时停止添加行（始终至少返回一行，且可通过 pagination.nextOffset 继续）；超过 25,000 个字符的摘要会分段返回，并附带 textTotalCharacters、textTruncated 和 textNextOffset
• 若要查看某项法案的摘要，或读完分段摘要，请使用 congressgov_bill_lookup 的 summaries

---

congressgov_crs_reports _工具

• list 浏览目录；get 接受 reportNumber，例如 R40097、RL33612 或 IF12345
• id、reportId 和 report_id 均可作为 reportNumber；仅发送一个标识符键
• get 返回作者、主题、摘要和下载格式

---

congressgov_committee_reports _工具

• list 浏览一个 congress，可按 reportType 筛选（hrpt 为众议院，srpt 为参议院，erpt 为行政部门）；get、text 和 content 需要 reportType + reportNumber
• get 返回引文、标题、委员会和关联法案；text 列出 {type, url} 格式的链接，content 以一个字符窗口读取报告

---

congressgov_daily_record _工具

• 导航流程为 list（卷）→ issues（按 volumeNumber）→ articles（按 volumeNumber + issueNumber）
• content 以一个字符窗口读取 articleIndex（从 0 开始，在期内计数）对应的文章；《国会记录》文章仅提供格式化文本和 PDF，因此 format: 'xml' 会因 format_unavailable 失败

---

congressgov_search_bills _工具

• query 对法案标题和 CRS 摘要中的关键词执行 AND 组合搜索，并可按 congress、billType 和 originChamber 缩小范围；limit 为 1–100，offset 用于分页
• 按 BM25 排序的行包含 billId 以及供 congressgov_bill_lookup 使用的 congress/billType/billNumber，还有 summaryPreview；政策领域和完整法案文本未编入索引
• 仅当 CONGRESS_MIRROR_ENABLED=true 时才会列出；在 bun run mirror:init 建立索引之前，它会返回空结果和提示

---

congress://current _资源

• 当前国会届数、会期日期和两院信息，是其他查询的基准
• 公开缓存 1 小时

---

congress://bill-types _资源

• 8 种法案类型代码（hr、s、hjres、sjres、hconres、sconres、hres、`sres），附带说明、所属院和引文示例
• 静态资源，不调用上游；公开缓存 24 小时

---

congress://member/{bioguideId} _资源

• bioguideId 为一个大写字母加 6 位数字（例如 P000197）
• 返回议员档案：姓名、州、党派、任期、领导职务、办公室和立法数量

---

congress://bill/{congress}/{billType}/{billNumber} _资源

• congress 和 billNumber 均为正整数；billType 为 8 种法案类型代码之一
• 返回法案详情：发起人、状态、政策领域、委员会和最新行动

---

congress://committee/{committeeCode} _资源

• committeeCode 由 h/s/j 开头，后接 3–8 个小写字母数字字符（例如 hsju00）；所属院由首字母确定
• 返回委员会详情：名称、所属院、分委员会、历史记录和立法数量

congressgov_bill_analysis _提示词

• 参数：congress、billType 和 billNumber，均为必填项
• 返回一条用户消息，按七个部分构建分析框架，从摘要到展望，并列出每个部分要调用的工具

---

congressgov_legislative_research _提示词

• 必填参数：topic；可选参数：congress，默认为当前届国会
• 启用 CONGRESS_MIRROR_ENABLED 时，计划以 congressgov_search_bills 开头；未启用时，提示词会要求提供一项种子法案、议员、委员会或 CRS 报告 ID，因为没有其他工具接受主题作为参数

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、结构化日志记录以及可选的 OpenTelemetry 追踪。

Congress.gov 专属功能：

• 用于 Congress.gov REST API v3 的类型安全客户端，以及用于支持参议院唱名表决的参议院 LIS XML 源客户端
• Congress.gov API 不支持关键词搜索，因此工具会按国会届次、类型、日期范围、议院、州和选区浏览；列表操作支持分页，limit 为 1–250（默认值为 20），并提供 offset
• 法案文本、委员会报告和《国会记录》文章的 content 可读取 format text（默认值）或 xml，并通过 characterOffset/characterLimit 指定窗口（1–100,000 个字符，默认值为 25,000）；仅从 www.congress.gov 获取内容，大小上限为 25 MB，截止时间为 30s
• 可选的 api.data.gov API 密钥：DEMO_KEY 按 IP 地址每小时允许 30 次请求、每天允许 50 次；注册密钥每小时允许 5,000 次请求
• 可选择启用本地 SQLite FTS5 镜像（CONGRESS_MIRROR_ENABLED），以便按关键词搜索法案标题和 CRS 摘要

便于 Agent 使用的输出：

• 每个列表响应都包含 effectiveQuery 和 totalCount；无匹配结果时会包含 notice
• list 会拒绝仅用于详情查询的标识符（billNumber、voteNumber、nominationNumber、reportNumber、volumeNumber），并返回 incompatible_identity 错误，指出应改用的操作
• content 会返回 offset、truncated 和 nextOffset，因此遍历数 MB 的法案时不会跳过或重复任何字符
• 类型化错误（document_unavailable、format_unavailable、document_fetch_failed、document_too_large、offset_past_end、not_found、rate_limited、invalid_request、upstream_error、upstream_timeout），每种错误都附带恢复提示

开始使用

公共托管实例

可使用公共实例 https://congressgov.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP 传输；各客户端的配置格式各不相同。

适用于 Claude Code：

claude mcp add --transport http congressgov-mcp-server https://congressgov.caseyjhand.com/mcp

适用于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "streamableHttp",
      "url": "https://congressgov.caseyjhand.com/mcp"
    }
  }
}

适用于 Cursor（mcp.json）：

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "url": "https://congressgov.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/congressgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CONGRESS_API_KEY": "your-api-key"
      }
    }
  }
}

也可使用 npx（无需 Bun）：

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/congressgov-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CONGRESS_API_KEY": "your-api-key"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "congressgov-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "CONGRESS_API_KEY=your-api-key",
        "ghcr.io/cyanheads/congressgov-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CONGRESS_API_KEY=your-api-key bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 可选：免费的 api.data.gov key 可将请求限额从演示密钥的每小时 30 次、每个 IP 地址每天 50 次，提高到每小时 5,000 次。

安装

1. 克隆代码库：

git clone https://github.com/cyanheads/congressgov-mcp-server.git

2. 进入目录：

cd congressgov-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set CONGRESS_API_KEY (and the mirror vars, if you want keyword search)

配置

变量	说明	默认值
CONGRESS_API_KEY	来自 api.data.gov 的 API 密钥。	DEMO_KEY
CONGRESS_API_BASE_URL	Congress.gov API 基础 URL。	https://api.congress.gov/v3
CONGRESS_MIRROR_ENABLED	启用本地法案搜索镜像和 congressgov_search_bills 工具。	false
CONGRESS_MIRROR_PATH	SQLite 镜像索引的文件系统路径。	.mirror/bills.sqlite3
CONGRESS_MIRROR_REFRESH_CRON	进程内镜像刷新的 Cron 计划（仅限 HTTP 传输）。未设置时，需自行运行 mirror:refresh。	—
CONGRESS_MIRROR_CONGRESSES	要镜像的国会届次编号，以逗号分隔（例如 118,119）。	当前届次 + 前一届
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto；auto 将解析为 stateful。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
OTEL_ENABLED	启用 OpenTelemetry。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于追踪和指标的 OTLP 基础端点。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	显式指定的 OTLP 日志端点；基础端点不会启用日志导出。	—
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的输入和输出，并按键进行脱敏；自由格式值中的密钥不会脱敏。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每条失败调用输入或输出记录的最大字节数。	16384

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行生产版本：

  bun run rebuild
  bun run start:http   # or start:stdio
  

• 从此检出版本构建法案搜索镜像（设置 CONGRESS_MIRROR_ENABLED=true）：

  bun run mirror:init      # full build
  bun run mirror:refresh   # incremental refresh
  bun run mirror:verify    # readiness and integrity check
  

  镜像 CLI 需要使用此检出版本或 Docker 镜像的路径映射；npm 安装无法运行这些脚本。

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t congressgov-mcp-server .
docker run --rm -e CONGRESS_API_KEY=your-api-key -p 3010:3010 congressgov-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/congressgov-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖。镜像包含镜像脚本，因此 docker exec <container> bun run mirror:init 会在原地构建索引。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具、资源和提示词，初始化服务，并安排镜像刷新。
src/config/	使用 Zod 解析并验证特定于服务的环境变量。
src/mcp-server/tools/	工具定义（definitions/*.tool.ts），以及共享的输入、格式化和摘要窗口辅助工具。
src/mcp-server/resources/definitions/	资源定义（*.resource.ts）。
src/mcp-server/prompts/definitions/	提示词定义（*.prompt.ts）。
src/services/congress-api/	Congress.gov API 客户端：身份验证、分页、速率限制。
src/services/congress-documents/	有界文档文本抓取：主机白名单、字节上限、字符窗口。
src/services/congress-mirror/	本地 SQLite FTS5 法案搜索镜像：导入、规范化、模式。
src/services/senate-lis/	用于参议院唱名表决的 Senate LIS XML 客户端。
src/utils/	HTML/XML 字符引用解码。
scripts/	构建、开发检查和发布工具，以及 mirror:init / mirror:refresh / mirror:verify CLI。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

有关开发指南和架构规则，请参阅 CLAUDE.md。简要来说：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围的日志，使用 ctx.state 存储租户范围的数据
• 所有工具均为只读工具，并带有 readOnlyHint: true 和 idempotentHint: true 注解
• 封装外部 API 调用：校验原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段

参与贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。