Grants Search MCP Server

授予MCP服务器

模型上下文协议（MCP）服务器，用于全面的政府拨款发现和分析，由Simpler grants API提供支持。

概述

Grants MCP Server是一个基于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文件（推荐）：

# Copy the example file
cp .env.example .env

# Edit .env and add your actual API key
# SIMPLER_GRANTS_API_KEY=your_actual_api_key_here

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

environment:
  - SIMPLER_GRANTS_API_KEY=your_actual_api_key_here

3.构建和运行

# Build the Docker image
docker-compose build

# Start the container
docker-compose up -d

# Check if it's running
docker ps | grep grants-mcp

# View logs
docker logs grants-mcp-server

4.测试服务器

# Test with 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}'

# Or use the provided test script
python scripts/test_http_local.py

5.配置克劳德桌面

将Docker配置复制到Claude Desktop：

# 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等）

# Quick start
docker-compose up -d

# Stop the server
docker-compose down

# View logs
docker logs grants-mcp-server --follow

# Rebuild after code changes
docker-compose build && docker-compose up -d

选项2：本地Python安装

对于开发和测试：

# Install dependencies
pip install -r requirements.txt

# Run with stdio transport (for direct integration)
SIMPLER_GRANTS_API_KEY=your_key python main.py

# Run with HTTP transport (for testing containerization locally)
MCP_TRANSPORT=http PORT=8080 SIMPLER_GRANTS_API_KEY=your_key python main.py

获取API密钥

Simpler Grants API密钥是此MCP服务器运行所必需的。获取API密钥：

1. 访问 更简单的赠款API
2. 注册帐户或登录
3. 导航到API设置/仪表板
4. 生成或复制API密钥
5. 请确保此密钥的安全——您需要它进行配置

配置

环境变量

Docker配置

这 docker-compose.yml 文件包括：

• 端口映射：8081（主机）→ 8080 （集装箱）
• 资源限制：1个CPU，1GB RAM
• 自动重启策略
• 使用适当的SSE标头进行健康检查

可用工具

1.机会_范围

通过详细分析搜索资助机会。

参数：

• query：搜索关键词（例如“可再生能源”、“气候变化”）
• filters：高级过滤器参数
• max_results：最大结果数（默认值：100）
• page：分页页码
• grants_per_page：每页资助（默认值：3）

2.机构景观

地图机构及其资金重点领域。

参数：

• include_opportunities：包括机会分析（默认值：true）
• focus_agencies：特定机构代码（例如\[“NSF”、“NIH”\]）
• funding_category：按类别筛选
• max_agencies：要分析的最大机构数（默认值：10）

3.资金_资金_扫描仪

分析融资趋势和模式。

参数：

• time_window_days：分析期（默认值：90）
• category_filter：按类别筛选
• agency_filter：按机构筛选
• min_award_amount：最低奖励筛选器
• include_forecasted：包括预测的机会（默认值：true）

Claude桌面集成

用于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

1. 重新启动克劳德桌面

促进地方发展

1. 复制stdio配置：

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

1. 将配置中的路径更新到本地安装
2. 重新启动克劳德桌面

测试

测试Docker部署

# Run test script
python scripts/test_http_local.py

# Debug connection issues
bash scripts/debug_connection.sh

# Manual test with 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}'

运行测试套件

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/live/  # Requires API key

故障排除

端口冲突

如果端口8081正在使用中：

# Check what's using the port
lsof -i :8081

# Edit docker-compose.yml to use a different port
# Change "8081:8080" to "8082:8080"

集装箱问题

# Check container status
docker ps -a | grep grants-mcp

# View detailed logs
docker logs grants-mcp-server --tail 100

# Restart container
docker-compose restart

# Rebuild from scratch
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
• 验证API密钥在 更简单的赠款API

云部署

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

谷歌云运行

# Build and push to Google Container Registry
gcloud builds submit --tag gcr.io/YOUR_PROJECT/grants-mcp

# Deploy to 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桌面配置

贡献

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

路线图

• \[x\] 第一阶段：使用FastMCP实现Python
• \[x\] 第2阶段：增强的发现工具
• \[x\] 第三阶段：Docker容器化
• \[\]第四阶段：智能评分系统
• \[\]第5阶段：云部署自动化
• \[\]第6阶段：多机构比较工具
• \[\]第7阶段：赠款申请援助

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 内置于 FastMCP
• 由...驱动 更简单的赠款API
• 基于Anthropic的模型上下文协议

支持

对于问题、疑问或贡献：

• 打开一个问题
• 检查 部署指导 详细说明
• 审查 specs/ 技术文档目录

______________________________________________________________________

备注：这是一个alpha版本。API和功能可能会发生变化。在生产中谨慎使用。#部署测试

服务帐户和权限现在已正确配置！