grants-mcp

# Grants MCP Server 一个用于全面政府补助发现和分析的 Model Context Protocol (MCP) 服务器，由 Simpler Grants API 提供支持。 ## 概述 Grants MCP Server 是一个基于 Python 的 MCP 实现，使用 FastMCP，它提供了智能工具来发现、分析和跟踪政府补助机会。它为补助研究的不同方面提供了多个专用工具，从机会发现到资金趋势分析和机构格局映射。 ## 特性 ### 🔍 核心能力 - **Grant Opportunity Discovery**：根据关键词、机构、资助类别和资格标准搜索和筛选补助金 - **Funding Trend Analysis**：分析历史资金模式并识别新兴机会 - **Agency Landscape Mapping**：了解不同政府机构的补助生态系统 - **Intelligent Caching**：内置缓存系统，用于优化 API 调用并提高响应时间 - **Comprehensive Grant Details**：访问详细信息，包括资助金额、截止日期、资格要求和联系信息 ### 🛠️ 技术特性 - 使用 FastMCP 构建，实现强大的 MCP 服务器 - 异步 Python 架构，实现高性能 - **Dual Transport Support**：stdio（本地）和 HTTP（容器化） - **Docker Support**：即用型容器化版本 - 可配置的缓存，具有 TTL 和大小限制 - 用于 API 弹性的重试逻辑和错误处理 - 基于环境的配置管理 - 包含单元测试、集成测试和实时测试的综合测试套件 ## 使用 Docker 快速开始 🐳 ### 前提条件 - 已安装 Docker 和 Docker Compose - Simpler Grants API 密钥（参见[获取 API 密钥](#obtaining-api-key)） ### 1. 克隆存储库 ```bash git clone https://github.com/Tar-ive/grants-mcp.git cd grants-mcp ``` ### 2. 配置 API 密钥 **重要提示**：您必须提供自己的 API 密钥。切勿将 API 密钥提交到版本控制。 选项 A - 使用 .env 文件（推荐）： ```bash # 复制示例文件 cp .env.example .env # 编辑 .env 并添加您的实际 API 密钥 # SIMPLER_GRANTS_API_KEY=your_actual_api_key_here ``` 选项 B - 直接编辑 docker-compose.yml： ```yaml environment: - SIMPLER_GRANTS_API_KEY=your_actual_api_key_here ``` ### 3. 构建并运行 ```bash # 构建 Docker 镜像 docker-compose build # 启动容器 docker-compose up -d # 检查它是否正在运行 docker ps | grep grants-mcp # 查看日志 docker logs grants-mcp-server ``` ### 4. 测试服务器 ```bash # 使用 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： ```bash # For macOS cp claude_desktop_configs/config_local_docker.json \ ~/Library/Application\ Support/Claude/claude_desktop_config.json # For 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 # Main server implementation │ ├── config/ # Configuration management │ │ └── settings.py │ ├── models/ # Data models and schemas │ │ └── grants_schemas.py │ ├── tools/ │ │ ├── discovery/ # Grant discovery tools │ │ │ ├── opportunity_discovery_tool.py │ │ │ ├── agency_landscape_tool.py │ │ │ └── funding_trend_scanner_tool.py │ │ └── utils/ # Utility modules │ │ ├── api_client.py │ │ ├── cache_manager.py │ │ └── cache_utils.py │ └── prompts/ # System prompts ├── scripts/ # Testing and deployment scripts │ ├── test_http_local.py # Test HTTP endpoint │ ├── test_http_no_docker.py # Run HTTP server locally │ └── debug_connection.sh # Debug connectivity ├── claude_desktop_configs/ # Claude Desktop configurations │ ├── config_local_stdio.json # Direct Python execution │ ├── config_local_docker.json # Docker via mcp-remote │ └── config_both.json # Both options ├── docker-compose.yml # Docker Compose configuration ├── Dockerfile # Container definition └── tests/ # Comprehensive test suite ``` ## 部署选项 ### 选项 1：Docker（推荐用于生产环境） Docker 部署提供： - 跨平台的一致环境 - 易于扩展和部署 - 与系统依赖项隔离 - 准备好进行云部署（Google Cloud Run、AWS ECS 等） ```bash # 快速开始 docker-compose up -d # 停止服务器 docker-compose down # 查看日志 docker logs grants-mcp-server --follow # 代码更改后重新构建 docker-compose build && docker-compose up -d ``` ### 选项 2：本地 Python 安装 用于开发和测试： ```bash # 安装依赖项 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](https://api.simpler.grants.gov) 2. 注册一个帐户或登录 3. 导航到您的 API 设置/仪表板 4. 生成或复制您的 API 密钥 5. 确保此密钥安全 - 您将需要它进行配置 ## 配置 ### 环境变量 | Variable | Description | Default | |----------|-------------|---------| | `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`：要分析的最大机构数（默认值：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. 复制配置： ```bash # macOS cp claude_desktop_configs/config_local_docker.json \ ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 4. 重新启动 Claude Desktop ### 对于本地开发 1. 复制 stdio 配置： ```bash # macOS cp claude_desktop_configs/config_local_stdio.json \ ~/Library/Application\ Support/Claude/claude_desktop_config.json ``` 2. 将配置中的路径更新为您的本地安装 3. 重新启动 Claude Desktop ## 测试 ### 测试 Docker 部署 ```bash # 运行测试脚本 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}' ``` ### 运行测试套件 ```bash # 运行所有测试 pytest # 运行并覆盖 pytest --cov=src --cov-report=html # 运行特定测试类别 pytest tests/unit/ pytest tests/integration/ pytest tests/live/ # 需要 API 密钥 ``` ## 故障排除 ### 端口冲突 如果端口 8081 正在使用中： ```bash # 检查什么正在使用该端口 lsof -i :8081 # 编辑 docker-compose.yml 以使用不同的端口 # 将 "8081:8080" 更改为 "8082:8080" ``` ### 容器问题 ```bash # 检查容器状态 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](https://api.simpler.grants.gov) 验证 API 密钥是否有效 ## 云部署 容器化版本已准备好进行云部署： ### Google Cloud Run ```bash # 构建并推送到 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 有关详细的 AWS 部署说明，请参见 `specs/cloud_deployment.md`。 ## 开发 ### 项目结构 - `src/mcp_server/`：核心服务器实现 - `scripts/`：测试和实用程序脚本 - `tests/`：综合测试套件 - `specs/`：技术规范和文档 - `claude_desktop_configs/`：即用型 Claude Desktop 配置 ### 贡献 1. Fork 存储库 2. 创建一个功能分支：`git checkout -b feature/your-feature` 3. 进行更改并添加测试 4. 确保测试通过：`pytest` 5. 构建并测试 Docker 镜像：`docker-compose build && docker-compose up -d` 6. 使用描述性消息提交 7. 推送并创建一个 pull request ## 路线图 - [x] 阶段 1：使用 FastMCP 的 Python 实现 - [x] 阶段 2：增强的发现工具 - [x] 阶段 3：Docker 容器化 - [ ] 阶段 4：智能评分系统 - [ ] 阶段 5：云部署自动化 - [ ] 阶段 6：多机构比较工具 - [ ] 阶段 7：补助申请协助 ## 许可证 MIT 许可证 - 有关详细信息，请参见 LICENSE 文件 ## 致谢 - 使用 [FastMCP](https://github.com/jlowin/fastmcp) 构建 - 由 [Simpler Grants API](https://simpler.grants.gov) 提供支持 - Anthropic 的 Model Context Protocol ## 支持 对于问题、疑问或贡献： - 在 [GitHub](https://github.com/Tar-ive/grants-mcp/issues) 上打开一个 issue - 查看 [部署指南](DEPLOYMENT_GUIDE.md) 以获取详细说明 - 查看 `specs/` 目录以获取技术文档 --- **注意**：这是一个 alpha 版本。API 和功能可能会更改。在生产中使用时请谨慎。# Deployment Test 服务帐户和权限现已正确配置！