federal-regulations-mcp-server

---

概述

来自 Federal Register、eCFR 和 Regulations.gov 的美国联邦法规。搜索拟议规则和最终规则，追溯规则从提案、公众意见到编纂文本的全过程，并阅读任意 CFR 条文的现行版本或过去某个日期的版本。

工具

工具	描述
regulations_search_rules	按查询词、类型、机构、日期范围、CFR 部分、案卷编号和 RIN 搜索 Federal Register 中的拟议规则、最终规则、公告和总统文件，或通过页码引文查找对应文件
regulations_get_document	按编号获取一份 Federal Register 文件，其中包含案卷 ID、CFR 部分、引文、意见数量和意见 URL，可据此串联使用其他工具
regulations_browse_cfr	列出 CFR 篇目、某篇目的章节、某部分中的所有条文和附录；也可对编纂后的 CFR 进行全文搜索
regulations_get_cfr_section	阅读某条文、整部分或附录的编纂后 CFR 文本，可获取现行版本或过去某个日期的版本
regulations_get_docket	从 Regulations.gov 获取规则制定案卷及其归档文件（需要密钥）
regulations_find_comments	获取针对某份文件或案卷的公众意见，或获取一条意见的完整正文和附件（需要密钥）
regulations_list_open_comments	列出当前仍开放征求公众意见的文件，并按截止日期从近到远排序

资源

资源	描述
regulations://document/{documentNumber}	一份《联邦公报》文件的元数据和跨来源标识
regulations://cfr/{title}/{part}/{section}	当前 CFR 条文的编纂文本

这两种资源都对应一个工具（regulations_get_document、regulations_get_cfr_section），因此仅支持工具的客户端不会缺少任何功能。

能力参考

regulations_search_rules _工具

• 可选的全文 query，可按 type（PRORULE / RULE / NOTICE / PRESDOCU）、agencies（《联邦公报》的 slug，例如 environmental-protection-agency，而非名称或缩写）、published_after / published_before、cfr_title + cfr_part（单个部分编号或范围，例如 140-143；cfr_part 需要 cfr_title，否则会返回 title_required_for_part）、docket_id（《联邦公报》所列的案卷编号）和 rin 筛选；所有筛选条件会组合使用；per_page 为 2–100（默认 20），page 为 1–50
• citation（"89 FR 49102"）搭配 citation_date（来源注释中标注的日期），会按页面顺序返回该页刊载的文件，适用范围为第 59 卷（1994 年）及之后。引文缺少日期，或与日期范围同时使用时，会返回 citation_incomplete；卷号早于 59 或日期属于其他年份时，会返回 citation_out_of_range。如果没有文件跨越该页，通知会提供当天的页码范围
• 每个结果都包含 documentNumber、citation / startPage / endPage、agencies[].slug、印刷版所列的 docketIds、regulationsGovDocketId 和 regulationsGovDocumentId、commentCount、commentUrl、commentsCloseOn 及 commentPeriodOpen（评论期在截止日期当天美国东部时间晚上 11:59 前开放）、regulationIdNumbers，以及供后续工具使用的 cfrReferences。totalPages 和 nextPage 用于翻页。《联邦公报》最多提供 50 页，因此当结果集超过 50 × per_page（默认值下为 1,000 条，设为 100 时为 5,000 条）时，truncated 会标记结果已截断；请缩小日期范围，而不要继续翻页。totalCount 的上限为 10,000，表示结果至少有这么多条。起始日期晚于结束日期时，会返回 date_range_inverted；invalid_filter 会指出被拒绝的参数

---

regulations_get_document _工具

• document_number 可使用《联邦公报》采用的任何格式：2010 年起的 2024-07773，以及更早的编号和更正编号，例如 98-1572、E9-25990 或 C1-2009-30484；include_full_text 会将纯文本正文作为一个长度不超过 max_chars 的片段返回（默认 64,000，最大 200,000），从 offset 开始；传入其中任一参数都会启用全文
• 返回元数据，以及其他工具所需的标识：Regulations.gov 的 docketId 和 regulationsGovDocumentId、印刷版所列的 docketIds、citation / startPage / endPage、commentCount、commentUrl、commentPeriodOpen 和 cfrReferences。返回文本时，fullTextLength 和 fullTextNextOffset（仍有文本时存在）用于翻阅正文；重要的最终规则正文可能超过一百万个字符

---

regulations_browse_cfr _工具

• mode: "structure" 会列出 50 个标题、某个标题的顶层分区，或在提供 title + part 时列出该部分的所有条文和附录，并附上其 subpart 和 subjectGroup；mode: "search" 会对编纂后的 CFR 进行全文搜索，并且必须提供 query。title、part（需要 title）和指定时间点的 date 可限定两种模式的范围；per_page 为 1–50（默认 20），用于翻阅搜索结果和部分清单
• 搜索结果每个条文一行，包含 cfrCite、heading、hierarchyPath 和 excerpt。source（mirror / live）和 sourceScope 会说明所用语料及其覆盖范围；countBasis 会说明 totalCount 统计的是 sections 还是 section_versions；实时搜索仅覆盖 eCFR 的前 10,000 条结果（超过范围后翻页会返回 page_out_of_window）

regulations_get_cfr_section _工具

• 单个章节（title + part + section）、整个部分（省略 section），或一个附录（appendix，原样使用 regulations_browse_cfr 返回的形式，例如 Appendix A-1 to Part 50）。section 也接受人们常用的引文格式（"61"、"§ 141.61"、"141.61(c)"）以及服务返回的 cfrCite（"40 CFR 141.61"、"14 CFR 241 § 25"；若引文指定了其他标题，则会报错 conflicting_title）；part 接受 "Part 141"；date 可读取从 2017-01-01 到该标题最新日期的文本
• 文本以单个 bodyText 窗口返回（max_chars 默认为 64,000，最大 200,000，从 offset 开始），并通过 bodyTextLength 和 bodyTextNextOffset 分页。读取整个部分时，还会返回包含各章节 offset 的 sections[] 索引，并列出附录名称，但不含附录文本；source（mirror / live）指明来源
• 读取整个部分时，还会返回该部分的 heading、authority、sourceNote 和 notes；每个 sections[] 条目都包含其子部分或主题组为该章节注明的 Authority 或 Source
• 上标显示为 ^x，下标显示为 _x（3 × 10^−8、CO_{2}e）；脚注标记为 [n]；变音符号和上划线用组合标记表示（x̄）

---

regulations_get_docket _工具 · 需要密钥

• docket_id，Regulations.gov 的案卷 ID（例如 EPA-HQ-OAR-2025-0194）——可使用搜索结果或开放评论条目中的 regulationsGovDocketId，或 regulations_get_document 返回的 docketId，而非印出的 docketIds 条目；document_types 可筛选 Proposed Rule、Rule、Notice、Supporting & Related Material 或 Other；per_page 为 5–250（默认 25），page 为 1–40
• 返回案卷的元数据、documentCount 和 documents[]。每个文档都包含供 regulations_find_comments 使用的 objectId、可传给 regulations_get_document 的 frDocNum，以及 Regulations.gov 报告的 commentPeriodOpen。文档可通过 totalPages 和 nextPage 分页；Regulations.gov 提供 40 页，因此当案卷超过 40 × per_page（per_page 为 250 时为 10,000）时，truncated 会标记结果被截断

---

regulations_find_comments _工具 · 需要密钥

• docket_id、document_object_id、fr_document_number 或 comment_id 中必须且只能指定一个；列表查询的 per_page 为 5–250（默认 25），page 为 1–40
• document_object_id 可接受对象 ID（0900006485883ec6）或文档 ID（EPA-HQ-OW-2022-0114-0027）。fr_document_number 会解析为带有该确切编号的 Regulations.gov 文档；如果没有匹配项，则返回 not_found
• 列表可通过 search_term 按评论文本缩小范围，每条匹配结果都会包含 highlightedContent，即匹配的段落。posted_after / posted_before 可设置包含边界的发布日期范围。若日期范围前后颠倒，则会报错 date_range_inverted；在 comment_id 模式下传入筛选条件，则会报错 filter_requires_list_mode
• mode 为 list 或 detail。列表返回评论摘要，不含正文。comment_id 会返回正文、提交者、receivedDate、postmarkDate、duplicateComments（大于 1 表示这是群发活动记录）和 attachments；若评论实质内容位于 PDF/DOCX 文件中，则 attachmentOnly: true。列表包含 totalPages 和 nextPage；当结果集超过 Regulations.gov 可提供的 40 页（40 × per_page，per_page 为 250 时为 10,000）时，truncated 会标记结果被截断；发布日期范围每次只获取其中一个片段

---

regulations_list_open_comments _工具

• 可选参数 query、type（PRORULE、RULE、NOTICE；默认值为 ["PRORULE", "RULE"]）、agencies（Federal Register 标识符）和 closing_before；per_page 范围为 1–100（默认值为 20）
• 条目按截止日期排序，最早的排在前面，并包含 commentsCloseOn、daysRemaining、documentNumber、印刷版 docketIds、regulationsGovDocketId 和 regulationsGovDocumentId、commentCount 及 commentUrl。asOf 是美国东部时间的当天日期，因此文件在截止当天仍会列出。totalPages 和 nextPage 用于翻阅此时间范围；truncated 表示已达到 Federal Register 的 10,000 个文件上限
• 无需密钥。keyed 表示是否已设置 REGULATIONS_GOV_API_KEY，调用 regulations_get_docket 和 regulations_find_comments 跟进某个条目时需要此密钥

---

regulations://document/{documentNumber} _资源

• documentNumber 可采用任意 Federal Register 格式（2024-07773、98-1572、E9-25990）；返回内容与 regulations_get_document 相同，但不含正文
• docketId、regulationsGovDocumentId、印刷版 docketIds、cfrReferences、citation、commentCount 和 commentUrl 可串联搜索、评论和 CFR 工具

---

regulations://cfr/{title}/{part}/{section} _资源

• 仅限条文；使用当前日期和工具默认的 64,000 字符窗口；part 和 section 字段按工具的解析方式解析（"Part 141"；"61"、"§ 141.61"、"40 CFR 141.61"）
• source（mirror / live）表示数据来源。bodyTextNextOffset 标记超出窗口的条文；可通过带有 offset 的 regulations_get_cfr_section 读取剩余内容

功能特性

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

Federal Register / eCFR / Regulations.gov 专属功能：

• 通过三个官方数据源实现统一工作流：Agent 调用监管领域的动词（search_rules、get_cfr_section、find_comments），而不是使用三个 API 客户端
• 跨数据源关联：每份 Federal Register 文件都会提供其 docket ID 和 CFR 部分句柄，用于串联提案 → 评论 → 最终规则 → 编纂文本的追踪流程
• 核心功能无需密钥：五个 Federal Register 和 eCFR 工具无需密钥。regulations_get_docket 和 regulations_find_comments 需要 REGULATIONS_GOV_API_KEY（可在 api.data.gov/signup 免费获取，每小时 1,000 次请求）；如果缺少密钥或密钥遭拒，会返回 auth_required，并指出变量名和注册 URL
• 本地镜像的编纂版 CFR：eCFR 会同步到内嵌 SQLite + FTS5，以支持精确引文读取和全文搜索；对于历史日期、完整部分、附录、镜像之外的篇章，以及 eCFR 自上次镜像同步后重新发布过的篇章，则会回退到实时 API
• 每个请求的预算为 45 秒，由所有上游调用、重试和退避共享；如果数据源停滞，会在客户端超时前返回 upstream_unavailable

面向 Agent 的输出：

• 来源信息：每次 CFR 读取都会包含 source: "mirror" | "live"，搜索结果还会附带一行 sourceScope，说明语料库覆盖范围
• 如实分页：totalPages 和 nextPage 会说明列表可翻阅到哪里；超出末页时，响应会指出最后一页，而不是显示为“无匹配结果”；超过 Federal Register 的 50 页或 Regulations.gov 的 40 页的匹配项会通过 truncated 和 notice 提示，绝不会静默丢弃条目
• 考虑附件的评论：attachmentOnly 会标记内容实质为文件的评论，并提供下载 URL

入门指南

公共托管实例

公共实例可通过 https://federal-regulations.caseyjhand.com/mcp 访问，无需安装。该实例使用 Streamable HTTP；各客户端的配置格式各不相同。

对于 Claude Code：

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

对于 Cline（cline_mcp_settings.json）：

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

对于 Cursor（mcp.json）：

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

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

自托管 / 本地部署

将以下内容添加到 MCP 客户端配置文件中。REGULATIONS_GOV_API_KEY 用于启用 docket 和 comment 工具；省略该项即可仅运行无需密钥的 Federal Register 和 eCFR 工具。

{
  "mcpServers": {
    "federal-regulations-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/federal-regulations-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "REGULATIONS_GOV_API_KEY": "your-key-here"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "federal-regulations-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/federal-regulations-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "REGULATIONS_GOV_API_KEY": "your-key-here"
      }
    }
  }
}

或者使用 Docker：

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

对于 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 可选：用于 Regulations.gov 工具的免费 api.data.gov 密钥。

安装

1. 克隆代码库：

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

2. 进入目录：

cd federal-regulations-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# optionally set REGULATIONS_GOV_API_KEY

配置

变量	说明	默认值
REGULATIONS_GOV_API_KEY	用于 regulations_get_docket 和 regulations_find_comments 的 api.data.gov 密钥。	none
FEDERAL_REGISTER_BASE_URL	Federal Register API v1 基础 URL。	https://www.federalregister.gov/api/v1
ECFR_BASE_URL	eCFR API 基础 URL。	https://www.ecfr.gov/api
REGULATIONS_GOV_BASE_URL	Regulations.gov API v4 基础 URL。	https://api.regulations.gov/v4
ECFR_MIRROR_PATH	eCFR SQLite 镜像数据库的路径。	./data/ecfr-mirror.sqlite
ECFR_MIRROR_REFRESH_CRON	进程内镜像刷新的 Cron 表达式（仅限 HTTP 传输），例如 0 4 * * 0。每次运行都会重新完整采集所有已配置的标题。	none（无任务）
ECFR_MIRROR_TITLES	要镜像的 CFR 标题，以逗号分隔（例如 21,40）。对集合以外内容的读取和搜索，以及所有标题搜索，都会调用实时 eCFR API。	全部 50 个标题
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false

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

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 构建或刷新 eCFR 镜像（在进程外执行且可幂等；首次构建完成前，CFR 工具会使用实时 eCFR API）：

  bun run mirror:init      # full build, resumable (scope with ECFR_MIRROR_TITLES)
  bun run mirror:refresh   # re-harvest every configured title against the latest eCFR issues
  bun run mirror:verify    # report row counts and the last-synced issue date
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security, changelog sync
  bun run test       # Vitest test suite
  

Docker

docker build -t federal-regulations-mcp-server .
docker run --rm -e REGULATIONS_GOV_API_KEY=your-key -p 3010:3010 federal-regulations-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/federal-regulations-mcp-server。在运行中的容器内使用 docker exec <container> bun run mirror:init 构建镜像，并在 /usr/src/app/data 上挂载卷，以便容器重建后保留数据。默认会安装 OpenTelemetry 对等依赖；构建时添加 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具和资源，初始化三项服务，并在设置了 ECFR_MIRROR_REFRESH_CRON 时安排镜像刷新。
src/config	使用 Zod 解析并验证服务器专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts），包含七个 regulations_* 工具。
src/mcp-server/resources	资源定义（*.resource.ts），包含文档和 CFR 条款资源。
src/services/federal-register	Federal Register API v1 客户端（无需密钥）。
src/services/ecfr	eCFR API 客户端（无需密钥）：版本管理、结构、搜索、条款 XML 解析和引文解析。
src/services/ecfr-mirror	eCFR 编纂文本镜像（SQLite + FTS5）及可选的刷新任务。
src/services/regulations-gov	Regulations.gov v4 客户端（X-Api-Key）：案卷和评论。
src/services	共享请求预算、文本分段、字符引用解码和上游故障处理。
scripts/ecfr-mirror-*.ts	带外镜像生命周期管理：init、refresh、verify。
tests/	与 src/ 对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要概述：

• 处理程序抛出异常，框架捕获异常——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• 通过 src/mcp-server/*/definitions/index.ts 中的汇总导出注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失的上游字段

数据免责声明

根据 Office of the Federal Register 的说法，eCFR 内容“具有权威性，但并非官方版本”，并非《联邦法规汇编》的官方法律版本；法律研究请对照 govinfo.gov 核实。本服务与 Office of the Federal Register、Government Publishing Office 或 General Services Administration 均无关联，也未获得其认可。

贡献

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

bun run devcheck
bun run test

许可证

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