政府补助金MCP服务器

由Simpler Grants API驱动的Model Context Protocol (MCP)服务器，用于全面发现和分析政府补助金。

概述

Grants MCP服务器是一个基于Python的MCP实现，使用FastMCP提供智能工具来发现、分析和跟踪政府补助金机会。它提供了多种专门工具，涵盖从机会发现到资金趋势分析以及机构格局映射的不同方面。

特性

🔍 核心功能

• 补助金机会发现：根据关键词、机构、资金类别和资格标准搜索和筛选补助金
• 资金趋势分析：分析历史资金模式并识别新兴机会
• 机构格局映射：了解不同政府机构的补助金生态系统
• 智能缓存：内置缓存系统优化API调用并提高响应时间
• 详细的补助金信息：访问包括资金金额、截止日期、资格要求和联系方式在内的详细信息

🛠️ 技术特性

• 使用FastMCP构建，实现强大的MCP服务器
• 异步Python架构，高性能
• 双传输支持：stdio（本地）和HTTP（容器化）
• Docker支持：准备好部署的容器化版本
• 可配置缓存，具有TTL和大小限制
• API弹性重试逻辑和错误处理
• 基于环境的配置管理
• 包括单元测试、集成测试和实时测试的全面测试套件

使用Docker快速启动 🐳

先决条件

• 安装Docker和Docker Compose
• Simpler Grants API密钥（参见获取API密钥）

1. 克隆仓库

git clone https://github.com/Tar-ive/grants-mcp.git
cd grants-mcp

2. 配置API密钥

重要：您必须提供自己的API密钥。切勿将API密钥提交到版本控制中。

选项A - 使用.env文件（推荐）：

# 复制示例文件
cp .env.example .env

# 编辑.env并添加您的实际API密钥
# SIMPLER_GRANTS_API_KEY=your_actual_api_key_here

选项B - 直接编辑docker-compose.yml：

environment:
  - SIMPLER_GRANTS_API_KEY=your_actual_api_key_here

3. 构建和运行

# 构建Docker镜像
docker-compose build

# 启动容器
docker-compose up -d

# 检查是否正在运行
docker ps | grep grants-mcp

# 查看日志
docker logs grants-mcp-server

4. 测试服务器

# 使用curl进行测试
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# 或使用提供的测试脚本
python scripts/test_http_local.py

5. 配置Claude Desktop

将Docker配置复制到Claude Desktop：

# 对于macOS
cp claude_desktop_configs/config_local_docker.json \
   ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 对于Windows
cp claude_desktop_configs/config_local_docker.json \
   %APPDATA%\Claude\claude_desktop_config.json

然后重启Claude Desktop以连接到您的容器化MCP服务器。

架构

grants-mcp/
├── src/
│   └── mcp_server/
│       ├── server.py              # 主服务器实现
│       ├── config/                # 配置管理
│       │   └── settings.py
│       ├── models/                # 数据模型和模式
│       │   └── grants_schemas.py
│       ├── tools/
│       │   ├── discovery/         # 补助金发现工具
│       │   │   ├── opportunity_discovery_tool.py
│       │   │   ├── agency_landscape_tool.py
│       │   │   └── funding_trend_scanner_tool.py
│       │   └── utils/             # 工具模块
│       │       ├── api_client.py
│       │       ├── cache_manager.py
│       │       └── cache_utils.py
│       └── prompts/               # 系统提示
├── scripts/                       # 测试和部署脚本
│   ├── test_http_local.py       # 测试HTTP端点
│   ├── test_http_no_docker.py   # 在本地运行HTTP服务器
│   └── debug_connection.sh      # 调试连接
├── claude_desktop_configs/        # Claude Desktop配置
│   ├── config_local_stdio.json  # 直接Python执行
│   ├── config_local_docker.json # 通过mcp-remote的Docker
│   └── config_both.json         # 两种选择
├── docker-compose.yml            # Docker Compose配置
├── Dockerfile                    # 容器定义
└── tests/                        # 全面测试套件

部署选项

选项1：Docker（推荐用于生产）

Docker部署提供：

• 跨平台一致的环境
• 易于扩展和部署
• 与系统依赖项隔离
• 准备云部署（如Google Cloud Run，AWS ECS等）

# 快速开始
docker-compose up -d

# 停止服务器
docker-compose down

# 查看日志
docker logs grants-mcp-server --follow

# 代码更改后重建
docker-compose build && docker-compose up -d

选项2：本地Python安装

用于开发和测试：

# 安装依赖
pip install -r requirements.txt

# 使用stdio传输运行（直接集成）
SIMPLER_GRANTS_API_KEY=your_key python main.py

# 使用HTTP传输运行（本地测试容器化）
MCP_TRANSPORT=http PORT=8080 SIMPLER_GRANTS_API_KEY=your_key python main.py

获取API密钥

此MCP服务器需要Simpler Grants API密钥才能正常工作。要获取您的API密钥：

1. 访问Simpler Grants API
2. 注册账户或登录
3. 导航至您的API设置/仪表板
4. 生成或复制您的API密钥
5. 保护好此密钥 - 您将在配置中需要它

配置

环境变量

变量	描述	默认值
SIMPLER_GRANTS_API_KEY	Grants.gov的API密钥（必需）	-
MCP_TRANSPORT	传输模式：stdio或http	stdio
PORT	HTTP服务器端口（容器模式）	8080
LOG_LEVEL	日志级别	INFO
CACHE_TTL	缓存生存时间（秒）	300
MAX_CACHE_SIZE	最大缓存条目数	1000

Docker配置

docker-compose.yml文件包含：

• 端口映射：8081（主机）→ 8080（容器）
• 资源限制：1个CPU，1GB内存
• 自动重启策略
• 带有适当SSE头的健康检查

可用工具

1. opportunity_discovery

搜索补助金机会并进行详细分析。

参数：

• query：搜索关键词（例如，“可再生能源”，“气候变化”）
• filters：高级过滤参数
• max_results：最大结果数量（默认：100）
• page：分页的页面编号
• grants_per_page：每页补助金数量（默认：3）

2. agency_landscape

映射机构及其资金关注领域。

参数：

• include_opportunities：是否包含机会分析（默认：true）
• focus_agencies：特定机构代码（例如，["NSF", "NIH"]）
• funding_category：按类别过滤
• max_agencies：要分析的最大机构数量（默认：1-10）

3. funding_trend_scanner

分析资金趋势和模式。

参数：

• time_window_days：分析周期（默认：90）
• category_filter：按类别过滤
• agency_filter：按机构过滤
• min_award_amount：最小奖励过滤
• include_forecasted：是否包含预测的机会（默认：true）

Claude Desktop集成

对于Docker部署

1. 确保Docker容器正在运行：docker-compose up -d
2. 如需安装mcp-remote：npm install -g mcp-remote
3. 复制配置：

   # macOS
   cp claude_desktop_configs/config_local_docker.json \
      ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

4. 重启Claude Desktop

对于本地开发

1. 复制stdio配置：

   # macOS
   cp claude_desktop_configs/config_local_stdio.json \
      ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

2. 更新配置中的路径指向您的本地安装
3. 重启Claude Desktop

测试

测试Docker部署

# 运行测试脚本
python scripts/test_http_local.py

# 调试连接问题
bash scripts/debug_connection.sh

# 手动测试使用curl
curl -X POST http://localhost:8081/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

运行测试套件

# 运行所有测试
pytest

# 运行带覆盖率的测试
pytest --cov=src --cov-report=html

# 运行特定测试类别
pytest tests/unit/
pytest tests/integration/
pytest tests/live/  # 需要API密钥

故障排除

端口冲突

如果端口8081已被占用：

# 检查什么在使用该端口
lsof -i :8081

# 编辑docker-compose.yml以使用不同的端口
# 将"8081:8080"更改为"8082:8080"

容器问题

# 检查容器状态
docker ps -a | grep grants-mcp

# 查看详细日志
docker logs grants-mcp-server --tail 100

# 重启容器
docker-compose restart

# 从零开始重建
docker-compose down
docker-compose build --no-cache
docker-compose up -d

API密钥问题

• 确保SIMPLER_GRANTS_API_KEY已在docker-compose.yml中设置
• 检查日志中的身份验证错误：docker logs grants-mcp-server
• 在Simpler Grants API验证API密钥的有效性

云部署

容器化版本已准备好进行云部署：

Google Cloud Run

# 构建并推送到Google Container Registry
gcloud builds submit --tag gcr.io/YOUR_PROJECT/grants-mcp

# 部署到Cloud Run
gcloud run deploy grants-mcp \
  --image gcr.io/YOUR_PROJECT/grants-mcp \
  --platform managed \
  --port 8080 \
  --set-env-vars SIMPLER_GRANTS_API_KEY=your_key

AWS ECS / Fargate

详见specs/cloud_deployment.md中的详细AWS部署说明。

开发

项目结构

• src/mcp_server/：核心服务器实现
• scripts/：测试和实用脚本
• tests/：全面测试套件
• specs/：技术规范和文档
• claude_desktop_configs/：现成的Claude Desktop配置

贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/your-feature
3. 进行更改并添加测试
4. 确保测试通过：pytest
5. 构建并测试Docker镜像：docker-compose build && docker-compose up -d
6. 提交带有描述性消息的更改
7. 推送并创建拉取请求

发展路线图

• 第一阶段：使用FastMCP的Python实现
• 第二阶段：增强发现工具
• 第三阶段：Docker容器化
• 第四阶段：智能评分系统
• 第五阶段：云部署自动化
• 第六阶段：多机构比较工具
• 第七阶段：补助金申请辅助

许可证

MIT许可证 - 详情见LICENSE文件

致谢

• 使用FastMCP构建
• 由Simpler Grants API提供动力
• Model Context Protocol由Anthropic提供

支持

对于问题、疑问或贡献：

• 在GitHub上打开一个issue
• 查看部署指南以获取详细说明
• 查阅specs/目录中的技术文档

---

注意：这是alpha版本。API和功能可能会发生变化。谨慎在生产环境中使用。