FedDocMCP
    
一种模型上下文协议（MCP）服务器，为最终用户提供从Congress.gov、《联邦公报》法规和GovInfo.gov文档集合直接访问国会法案数据的权限。
概述
FedDocMCP使最终用户能够通过任何兼容MCP的客户端实时搜索、检索和分析美国国会法案、《联邦公报》规定、法院意见、国会听证会和39+其他政府文件集。该服务器基于模型上下文协议构建，提供了一个标准化的接口，用于访问官方政府API，包括Congress.gov、FederalRegister.gov和GovInfo.gov。
什么是MCP？
模型上下文协议（MCP）是一个开放标准，使AI应用程序能够安全地连接到外部数据源和工具。MCP服务器展示了AI助手可以用来扩展其训练数据之外的功能的能力。
关键概念：
- 服务器：提供工具和资源（本项目）
- 客户端：使用服务器的MCP兼容应用程序（例如，桌面客户端、IDE、AI助手）
- 运输：通信层（stdio供本地使用）
- 工具：客户端可以调用的功能（搜索账单、获取账单文本等）
了解更多： 模型上下文协议规范
特性
国会法案（Congress.gov）
- 搜索账单：按关键字、国会会议或法案类型查找立法
- 获取账单文本：检索多种格式的账单全文
- 跟踪账单状态：跟踪法案在立法过程中的进展
《联邦公报》条例
- 搜索规则：查找规则、拟议规则、通知和总统文件
- 获取法规详细信息：检索带有CFR参考的《联邦公报》文件的全部详细信息
- 公众检查：已提交但尚未公布的访问文件
政府文件（GovInfo.gov）
- 列出收藏：浏览39多个可用文档集
- 搜索收藏：在国会记录、听证会、法院意见、预算文件等中查找文件
- 获取包裹详细信息：检索任何政府文件的完整元数据和下载链接
核心能力
- 实时数据：直接访问官方政府API
- 隐私第一：没有数据存储，所有查询都是实时发生的
- 类型安全：使用Pydantic构建，用于强大的数据验证
- 日期筛选：按会计年度或自定义日期范围筛选
- 自由：所有使用的API都是免费的（Congress.gov和GovInfo需要免费的API密钥，Federal Register不需要）
快速开始
先决条件
- Python 3.10或更高版本
- Congress.gov API密钥(在这里免费拿一个)-必填
- GovInfo.gov API密钥(在这里免费拿一个)-可选，适用于GovInfo工具
- 与MCP兼容的客户端应用程序
安装
- 克隆仓库
git clone https://github.com/n8daniels/FedDocMCP.git
cd FedDocMCP- 设置Python环境
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt- 配置API密钥
cp .env.example .env
# Edit .env and add your Congress.gov API key- 测试服务器
python src/server.pyMCP客户端配置
要将FedDocMCP与MCP兼容的客户端一起使用，请将其添加到客户端的配置文件中。
配置示例 （根据您的特定MCP客户进行调整）：
{
"mcpServers": {
"feddocmcp": {
"command": "python",
"args": ["/absolute/path/to/FedDocMCP/src/server.py"],
"env": {
"CONGRESS_API_KEY": "your-api-key-here"
}
}
}
}笔记：
- 替换
/absolute/path/to/FedDocMCP/src/server.py使用系统上的实际路径 - 将您的Congress.gov API密钥添加到
CONGRESS_API_KEY领域 - 更新配置后重新启动MCP客户端
- 看
examples/mcp_client_config.json供参考
可用工具
1.搜索_账单
按关键字、国会会议或类型搜索国会法案。
参数：
query（必填）：搜索关键字或短语congress：国会编号（例如，118代表第118届国会）bill_type：账单类型（hr、s、hjres、sjres等）limit：最大结果（1-100，默认值：20）
例子：
Search for bills about "climate change" in the 118th Congress2.get_bill_text
检索特定账单的全文。
参数：
congress（必填）：国会编号bill_type（必填）：票据类型bill_number（必填）：账单编号format：文本格式（json、xml、pdf）
例子：
Get the text of H.R. 1 from the 118th Congress3.获取账单状态
跟踪法案在立法过程中的进展。
参数：
congress（必填）：国会编号bill_type（必填）：票据类型bill_number（必填）：账单编号
例子：
What's the status of S. 234 from the 118th Congress?4.搜索规则
在《联邦公报》上搜索法规、规则、通知和总统文件。
参数：
query（必填）：搜索关键字或短语document_type：文档类型（规则、规则、通知、预文档）agency：按机构筛选（例如“EPA”、“FDA”）limit：最大结果（1-100，默认值：20）fiscal_year：按会计年度筛选start_date/end_date：按自定义日期范围筛选
例子：
Search for EPA environmental regulations from fiscal year 20245.获取_法规_详细信息
检索特定《联邦公报》文件的完整详细信息。
参数：
document_number（必填）：联邦公报文件编号（例如“2024-12345”）
例子：
Get details for Federal Register document 2024-123456.获取公共检查文件
已向《联邦公报》提交但尚未公布的访问文件。
参数：
agency：按机构筛选（可选）special_filing：仅显示特殊文件（可选）
例子：
Show me EPA documents on public inspection7.列表_绵羊_收藏
列出所有可用的GovInfo.gov文档集合。
参数：
- 无需
例子：
What collections are available on GovInfo?
Show me all government document types退货：
- 39多个集合的列表，包括国会法案、联邦公报、CFR、法院意见、国会记录、预算文件等
8.搜索_收藏
按日期范围搜索特定GovInfo集合中的文档。
参数：
collection_code（必填）：收款代码（例如“BILLS”、“FR”、“CHRG”、“CREC”）start_date：ISO格式的开始日期（YYYY-MM-DD）end_date：ISO格式的结束日期（YYYY-MM-DD）limit：最大结果（1-100，默认值：20）
例子：
Search Congressional Record for documents from January 2024
Find all Congressional hearings from last month
Get Public Laws from fiscal year 20249.获取_绵羊_包装
获取特定GovInfo文档包的详细信息。
参数：
package_id（必填）：包装标识符（例如“BILLS-118hr1”、“FR-2024-12345”）
例子：
Get details for package BILLS-118hr1
Show me Congressional hearing CHRG-118shrg5236710.获取服务器健康
监控服务器性能和运行状况指标。
参数：
- 无需
例子：
Check server health
Show me performance metrics退货：
- 总体健康状况(✅ 健康，⚠️ 警告，或❌ 错误）
- 缓存命中率和统计数据
- 平均响应时间
- API的API调用统计
- 工具使用明细
- 错误计数和错误率
API密钥设置
Congress.gov API（票据工具要求）
- 访问 国会.gov API注册
- 用你的电子邮件填写表格
- 查看您的电子邮件以获取API密钥
- 将其添加到您的
.env文件或MCP客户端配置
费率限制：
- 每个API密钥每小时5000个请求
- FedDocMCP包括自动速率限制和重试逻辑
联邦公报API（无需密钥）
《联邦公报》的工具确实 非 需要API密钥-它们开箱即用！
GovInfo.gov API（GovInfo工具可选）
- 访问 api.data.gov注册
- 输入您的电子邮件地址
- 查看您的电子邮件以获取API密钥
- 添加
GOVINFO_API_KEY你的.env文件或MCP客户端配置
费率限制：
- 每小时1000个请求（默认免费级别）
- FedDocMCP包括自动速率限制和重试逻辑
注： 没有API密钥，GovInfo工具将无法工作。如果您不需要访问国会记录、听证会、法院意见或其他GovInfo集合，可以跳过此步骤。
看 docs/API_KEYS.md文件 详细说明。
使用示例
示例1：研究最新立法
“搜索第118届国会提出的关于人工智能的法案”
示例2：阅读具体法案
“给我看第118届国会H.R.1的全文”
示例3：跟踪进度
“《基础设施投资和就业法案》的现状如何？”
示例4：按会计年度搜索
“查找2024财年引入的所有气候变化法案”
联邦财政年度为10月1日至9月30日。2024财年=2023年10月1日至2024年9月30日。
示例5：使用日期范围搜索
“搜索2023年1月1日至2023年6月30日期间推出的基础设施法案”
示例6：比较账单
“搜索所有关于学生贷款的账单，并总结它们的主要区别”
示例7：搜索联邦法规
“查找2024财年美国环保署关于清洁水的规定”
示例8：跟踪拟议规则
“向我展示美国食品药品监督管理局提出的规则”
示例9：监督公众检查
“交通部目前正在公开检查哪些文件？”
发展
看 docs/DEVELOPMENT.md 用于开发设置和指南。
运行测试
# Install dev dependencies
pip install -r requirements-dev.txt
# Run tests
pytest
# Run with coverage
pytest --cov=src --cov-report=html代码质量
# Format code
black src/ tests/
# Lint
flake8 src/ tests/
# Type check
mypy src/日志记录配置
FedDocMCP包括用于调试和监控的结构化JSON日志。
环境变量：
LOG_LEVEL：设置日志详细程度（调试、信息、警告、错误、关键）-默认值：信息LOG_FORMAT：选择输出格式（json、text）-默认：jsonLOG_FILE：日志输出的可选文件路径-默认值：仅stderr
示例：
# Debug mode with text formatting
LOG_LEVEL=DEBUG LOG_FORMAT=text python src/server.py
# Production logging to file
LOG_LEVEL=INFO LOG_FILE=/var/log/feddocmcp.log python src/server.pyJSON日志格式：
{
"timestamp": "2024-01-15T10:30:45.123456Z",
"level": "INFO",
"logger": "src.tools.bills",
"message": "Tool call completed: search_bills",
"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"tool": "search_bills",
"duration_ms": 234.5,
"status": "success",
"cached": "miss",
"source": {
"file": "/path/to/monitoring.py",
"line": 245,
"function": "wrapper"
}
}特征：
- 请求ID跟踪：每个工具调用都会获得一个唯一的请求ID，用于跨日志进行关联
- 结构化字段：一致的JSON格式，便于解析和分析
- 性能指标：所有工具调用的自动持续时间跟踪
- 错误上下文：带有堆栈跟踪的详细异常信息
- 自定义上下文：使用
extra参数
看 src/utils/logging.py 了解实现细节和高级用法。
项目结构
FedDocMCP/
├── src/
│ ├── __init__.py
│ ├── server.py # Main MCP server
│ ├── config.py # Configuration management
│ ├── monitoring.py # Performance monitoring
│ ├── tools/ # Tool implementations
│ │ ├── __init__.py
│ │ ├── bills.py # Congressional bill tools
│ │ ├── federal_register.py # Federal Register tools
│ │ └── system.py # System health tools
│ ├── clients/ # API clients
│ │ ├── __init__.py
│ │ ├── congress_api.py # Congress.gov API client
│ │ └── federal_register_api.py # Federal Register API client
│ └── utils/ # Shared utilities
│ ├── __init__.py
│ ├── cache.py # Enhanced cache with metadata
│ ├── dates.py # Date parsing and validation
│ ├── logging.py # Structured JSON logging
│ └── validation.py # Input validation with hints
├── tests/ # Test suite (216 tests, 82% coverage)
├── docs/ # Documentation
├── examples/ # Usage examples
├── requirements.txt # Dependencies
└── pyproject.toml # Project metadata建筑
FedDocMCP是一个无状态MCP服务器，它：
- 接收请求 通过stdio传输从MCP客户端
- 验证输入 使用Pydantic模式
- 致电国会.gov API 具有适当的身份验证和速率限制
- 格式化响应 结构化JSON
- 返回结果 给客户
没有数据存储在本地-所有信息都直接来自Congress.gov。
看 docs/ARCHITECTURE.md 了解技术细节。
贡献
欢迎投稿！请阅读 贡献.md 作为指导方针。
贡献方式
- 报告错误和问题
- 建议新功能或工具
- 改进文档
- 提交拉取请求
- 分享您如何使用FedDocMCP
路线图
v0.1.0（当前）
- \[x\] 基本账单搜索
- \[x\] 票据文本检索
- \[x\] 账单状态跟踪
- \[x\] Congress.gov API集成
v0.2.0（计划中）
- \[\]会员信息工具
- \[\]委员会数据
- \[\]投票记录
- \[\]修正跟踪
v0.3.0（未来）
- \[\]国会记录搜索
- \[\]听力信息
- \[\]条约数据
- \[\]提名跟踪
v1.0.0（视觉）
- \[\]国会.gov API全面覆盖
- \[\]高级缓存
- \[\]WebSocket支持
- \[\]多源数据（GovInfo等）
使用FedDocMCP的项目
您在项目中使用FedDocMCP吗？让我们知道！在此处打开问题或PR以添加您的项目。
故障排除
看 docs/TROUBLESHOOTING.md 常见问题和解决方案。
常见问题：
- API密钥不工作：验证是否已正确设置
.env或配置 - 服务器未启动：检查Python版本（3.10+）和依赖关系
- MCP客户端中未显示任何工具：配置更改后重新启动MCP客户端
- 速率限制错误：等待一个小时或使用其他API密钥
许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
致谢
- 建立在 模型上下文协议
- 数据由 国会.gov API
- MCP Python SDK Anthropic
支持
- 问题：
- 讨论：
- MCP文件： 模型上下文协议.io
安全
请向报告安全漏洞security@example.com（不要公开问题）。
看 安全.md 我们的安全政策。
______________________________________________________________________
由...制作❤️ 实现透明、无障碍的民主