AI导哈

资助发现与提案生成服务

Grant Hunter MCP是一个基于FastAPI的模型上下文协议（MCP）服务，用于资助发现和提案草稿生成。

  • by vitor-giacomelli
  • Python
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 vitor-giacomelli/mcp-grant-hunter

使用说明

# Grant Hunter MCP

Grant Hunter MCP是一种基于FastAPI的模型上下文协议（MCP）服务，用于授权发现和音调起草。

存储库角色

此存储库包含 公共MCP服务器层 Grant Hunter产品。它公开了HTTP端点，任何兼容MCP的客户端都可以调用这些端点来搜索授权、生成宣传并与Google Workspace交互。

私有产品层——面向用户的UI、工作流编排和最终用户身份验证——位于一个单独的私有存储库中。这个公共仓库的存在是为了让外部开发人员和MCP客户端可以独立地与服务器集成。

有关公共MCP服务器与更广泛产品之间关系的直观概述，请参阅 TECHNICAL.md中的架构图.

非目标

以下是 不 此存储库的一部分：

  • 面向用户的UI或前端组件
  • 跨越私有产品层的端到端产品工作流
  • 用户帐户管理、计费或租赁逻辑
  • 完整的OAuth2令牌生命周期服务
  • Kubernetes/Helm部署模板
  • 任何不直接与MCP端点关联的私有产品业务逻辑

已验证的功能

  • POST /query_grants
    • 按关键字搜索Grants.gov。
    • 使用异步 httpx 带有重试/回退的调用路径。
    • 应用可选 focus_area 过滤返回的机会。
    • 按机会编号进行重复数据删除。
    • 按结束日期排序。
    • 如果上游查找失败，则返回模拟授权，并使用响应元数据(fallback_used, data_source).
  • POST /generate_pitch
    • 使用Gemini生成草稿音高(gemini-2.0-flash 然后 gemini-2.0-flash-lite).
    • 当生成失败或未设置API密钥时，返回到确定性模板。
  • POST /manage_google_services
    • 根据请求输入创建Gmail草稿和日历事件。
    • 返回一个类型化的响应合约(GoogleServicesOutput).
    • 支持可选的服务器端OAuth访问令牌刷新 refresh_token, client_id，以及 client_secret 提供。
    • 支持 oauth_session_id 使用持久的服务器端OAuth凭据。
  • POST /oauth_sessions
    • 在服务器端持久化OAuth凭据并返回 session_id.
  • DELETE /oauth_sessions/{session_id}
    • 删除持久化的OAuth会话。
    • 支持 DEMO_MODE=TRUE 以模拟成功。
  • GET /health
    • 基本健康终点。
  • 请求可观察性
    • 增加 x-request-id 每个响应的相关标头。
    • 发出结构化请求完成日志和外部Grants.gov调用定时日志。

当前限制

  • 部分异步迁移：
    • 赠款查找是异步的。
    • Google API SDK调用是同步的，目前通过路由级线程卸载执行。
  • 合同漂移：
    • focus_area 现在被应用为一个简单的子字符串过滤器；高级语义过滤尚未实现。
  • OAuth生命周期：
    • 仍然支持仅访问令牌模式。
    • 现在，当提供刷新凭据时，每个请求都支持服务器端刷新。
    • 持久会话存储由SQLite支持，旨在用于后端服务。
    • 静态加密和外部秘密管理器集成尚未实现。
  • 日期安全：
    • 截止日期现已生效；可接受的格式是 %B %d, %Y 或 %Y-%m-%d.
  • 交付姿势：
    • 测试套件和CI已计划，但尚未实施。
    • Docker的使用被记录为路线图；此存储库中当前不存在任何Dockerfile。

架构文档

设置（本地）

先决条件

  • Python 3.11+
  • Gemini API AI沥青生成关键

安装

pip install -r requirements.txt

配置

cp .env.example .env

至少设置：

  • GEMINI_API_KEY （实时AI生成所需）

可选：

  • MCP_SERVER_URL
  • LOG_LEVEL
  • DEMO_MODE

跑

uvicorn main:app --reload --host 0.0.0.0 --port 8000

文件：

  • http://localhost:8000/docs

api参考

GET /health

返回服务运行状况。

POST /query_grants

请求：

{
  "keyword": "clean energy",
  "max_results": 20,
  "focus_area": "renewable energy"
}

答复包括：

  • fallback_used: true 当使用回退数据时
  • data_source: grants_gov 或 mock_fallback
  • 如果 focus_area 如果提供，结果将通过赠款标题/描述/类别/机构中的匹配文本进行过滤。

POST /generate_pitch

请求：

{
  "startup_name": "CleanTech Solutions",
  "focus_area": "Renewable Energy",
  "grant_title": "Clean Energy Innovation Grant"
}

POST /manage_google_services

请求：

{
  "grant_title": "Clean Energy Innovation Grant",
  "deadline_date": "December 15, 2025",
  "oauth_token": "oauth_access_token",
  "refresh_token": "optional_refresh_token",
  "client_id": "optional_client_id",
  "client_secret": "optional_client_secret",
  "token_uri": "https://oauth2.googleapis.com/token"
}

或基于会话的请求：

{
  "grant_title": "Clean Energy Innovation Grant",
  "deadline_date": "December 15, 2025",
  "oauth_session_id": "session_id_from_oauth_sessions"
}

错误合同

错误响应标准化为：

{
  "code": "MACHINE_READABLE_CODE",
  "message": "Human readable message",
  "details": { "optional": "context" }
}

问题自动化

存储库包括自动创建TODO问题：

  • 工作流程： .github/workflows/create-todo-issues.yml
  • 脚本： scripts/create_todo_issues.py

通过GitHub操作手动运行 workflow_dispatch 或推到 main TODO/脚本更改时。

安全说明

  • 永不承诺 .env.
  • 避免记录令牌或生成敏感内容。
  • 输入验证是通过Pydantic模型强制执行的。

贡献

看 贡献.md 获取完整的贡献指南，包括预期的PR类型、非目标和代码风格注释。

快速检查表：

  1. 审查 TODO.md 和 ARCHITECTURE_REVIEW.md.
  2. 保持行为和文档同步。
  3. 尽可能添加新行为测试。
  4. 不要泄露秘密。

相关 MCP