Docket Lens

regintel-mcp

来自 FDA regulations.gov 档案的监管情报：谁提交了意见、他们提出了哪些要求，以及草案与最终指南之间有哪些变化。

Black Swan Causal Labs · blackswancausallabs.com

检索由 MCP 服务负责。判断由技能负责。人在各个检查点把关。

层	组件	状态
数据	regintel-mcp 服务（本仓库，MIT）	第一阶段已完成。 获取、缓存、提取、比对。不做解读。
方法	技能：submitter-taxonomy、comment-theming、draft-final-concordance	已完成
编排	/docket-analysis <docketId>，含 4 个人工检查点	已完成；首次运行使用 FDA-2020-D-2307
输出	Docket Lens 浏览器（读取一个 analysis.json；PolyForm Noncommercial）	FDA-2020-D-2307 已完成

安装

Python 3.11 或更高版本。

git clone https://github.com/Black-Swan-Causal-Labs/regintel-mcp.git
cd regintel-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
cp .env.example .env    # then paste your key into .env

**API 密钥：**前往 https://open.gsa.gov/api/regulationsgov/ 免费获取密钥，并将其填入 .env，格式为 REGULATIONS_GOV_API_KEY=...。.env 已加入 gitignore。密钥只会通过 X-Api-Key 标头发送，不会出现在日志、缓存或任何输出中。单次查询可以使用 DEMO_KEY，但其速率限制太严格，无法拉取完整语料库。个人密钥每小时可发出 1,000 次请求。

在 MCP 客户端中注册。 MCP 是一项开放标准，因此该服务可与任何兼容的助手（Claude、OpenAI Codex 等）配合使用。对于 Claude Code，请在仓库目录中运行：

claude mcp add regintel-mcp -- "$(pwd)/.venv/bin/python" -m regintel_mcp

作为 Claude 插件安装时，.mcp.json 会从插件根目录启动服务。

工具

每个工具都会先读取本地 SQLite 缓存（data/cache.sqlite）。只有缓存未命中或调用时设置了 refresh=true，才会访问网络。

工具	功能
search_dockets(query, agency="FDA", docket_type?, limit=25)	按关键词搜索档案
get_docket(docket_id)	档案元数据和意见总数
list_documents(docket_id)	通知、草案和最终指南、会议材料，以及每个文件的 URL
list_comments(docket_id, include_withdrawn=false)	列出所有意见，内部进行分页。标记 is_stub、duplicate_of 和 agency_duplicate_count（仅标记，不会删除任何内容）
get_comment(comment_id)	正文、提交者字段、附件及提取出的附件文本
build_corpus(docket_id, with_attachments=true)	将所有意见和附件拉取到缓存中。支持断点续传。报告存根、重复项、需要 OCR 的内容和失败项
get_guidance_text(ref)	指南文档（文档 ID 或 URL），按编号拆分为各个章节
diff_guidance(draft_ref, final_ref)	按章节对齐的草案与最终版本差异比较，包括段落变更和段落移动检测
export_corpus(docket_id)	写入 output/<docket>/corpus.jsonl，供技能和子 Agent 使用

在聊天之外执行耗时的拉取任务：.venv/bin/python -m regintel_mcp build-corpus FDA-2020-D-2307。

**差异比较的工作原理：**使用 pdfplumber 提取文本层。移除页眉、草案行号、脚注和目录。根据指南自身的罗马数字、字母和数字标题拆分章节，然后先按标题（优先匹配包含父级标题的标题），再按标题加文本相似度，将草案章节与最终版本章节进行匹配。在每个匹配的章节中对段落进行差异比较，并标记移动到其他章节的段落。整个过程具有确定性：服务不会调用模型。

针对实时服务验证的 API 行为记录在 docs/api-notes.md 中。

Docket Lens（探索器）

Docket Lens（explorer/template.html）是一个单页，可读取一个 analysis.json，并展示三个相互关联的视图：谁发表了意见、他们提出了什么要求（按主题 × 提交者类型划分的热力图，点击可打开原文请求），以及发生了什么变化（按章节对比草案与最终版，并列出每项请求的处理结果）。构建某个 docket 的副本：

.venv/bin/python scripts/build_analysis.py FDA-2020-D-2307
.venv/bin/python scripts/build_explorer.py FDA-2020-D-2307

然后通过任意静态服务器打开 explorer/FDA-2020-D-2307/index.html，例如 python3 -m http.server --directory explorer/FDA-2020-D-2307。该探索器采用单独的 PolyForm Noncommercial 1.0.0 许可证（explorer/LICENSE、explorer/NOTICE）。

托管 Docket Lens 演示版（Cloudflare Pages，受密码保护）

sh scripts/build_site.sh FDA-2020-D-2307
cd site && npx wrangler pages deploy public --project-name docket-lens

site/functions/_middleware.js 会在每个请求前启用 HTTP Basic Auth，包括对 analysis.json 的请求。凭据是 Pages secrets，绝不会存储在文件中：运行 npx wrangler pages secret put DEMO_USER --project-name docket-lens，并对 DEMO_PASS 执行相同操作。只要缺少任意一个 secret，网站就不会提供任何内容（默认拒绝访问）。这是演示版的访问门槛，不是敏感数据的访问控制措施。

状态（2026 年 10 月 3 日）

• 首次完整运行：FDA-2020-D-2307（60 条意见、1,211 项请求、4 个检查点；人工抽查对 55 项处理结果的认同率为 91%）。输出位于 output/FDA-2020-D-2307/，决策记录位于 decisions/。
• 第二个 docket 冒烟测试：FDA-2021-D-0548。检索和草案／最终版对比均顺利通过，无需修改；请参阅 docs/smoke-test-FDA-2021-D-0548.md。

关于一致性的注意事项

此工具衡量的是一致性，而非影响。草案与最终版指南之间的变化也来自 FDA 的内部审查、ICH M14、其他指南以及不断发展的科学。当最终文本朝着评论者所要求的方向变化时，这并不表明该评论导致了这一变化。本项目的每项输出都包含此注意事项。

许可证

服务端：MIT（见 LICENSE）。Explorer 模板采用单独的 PolyForm Noncommercial 1.0.0 许可证。

© 2026 Black Swan Causal Labs · https://blackswancausallabs.com

Official MCP Registry 打包

Docket Lens 检索服务提供用于 Registry 分发的 MCP 包。 请参阅 Registry 安装与发布说明。 该软件包需要 uv、你的 Regulations.gov API 密钥，以及一个可写的工作文件夹。