Grant Hunter MCP

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。

架构文档

• 技术.md：当前架构和组件行为。
• ARCHITECTURE_REVIEW.md：结构化架构审查、风险矩阵和补救积压。
• TODO.md：优先路线图和与问题相关的积压工作。

设置（本地）

先决条件

• 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. 不要泄露秘密。