Grant Hunter MCP

Grant Hunter MCP is a FastAPI-based Model Context Protocol (MCP) service for grant discovery and pitch drafting.

Repository Role

This repository contains the public MCP server layer of the Grant Hunter product. It exposes HTTP endpoints that any MCP-compatible client can call to search for grants, generate pitches, and interact with Google Workspace.

The private product layer—user-facing UI, workflow orchestration, and end-user authentication—lives in a separate private repository. This public repo exists so that external developers and MCP clients can integrate with the server independently.

For a visual overview of how the public MCP server relates to the broader product, see the architecture diagram in TECHNICAL.md.

Non-Goals

The following are not part of this repository:

• User-facing UI or frontend components
• End-to-end product workflows spanning the private product layer
• User account management, billing, or tenancy logic
• Full OAuth2 token lifecycle service
• Kubernetes/Helm deployment templates
• Any private product business logic not directly tied to MCP endpoints

Verified Capabilities

• POST /query_grants
  • Searches Grants.gov by keyword.
  • Uses async httpx call path with retry/backoff.
  • Applies optional focus_area filtering over returned opportunities.
  • Deduplicates by opportunity number.
  • Sorts by close date.
  • Falls back to mock grants if upstream lookup fails, with response metadata (fallback_used, data_source).
• POST /generate_pitch
  • Generates a draft pitch using Gemini (gemini-2.0-flash then gemini-2.0-flash-lite).
  • Falls back to a deterministic template when generation fails or no API key is set.
• POST /manage_google_services
  • Creates a Gmail draft and a Calendar event from request inputs.
  • Returns a typed response contract (GoogleServicesOutput).
  • Supports optional server-side OAuth access token refresh when refresh_token, client_id, and client_secret are provided.
  • Supports oauth_session_id to use persisted server-side OAuth credentials.
• POST /oauth_sessions
  • Persists OAuth credentials server-side and returns a session_id.
• DELETE /oauth_sessions/{session_id}
  • Deletes a persisted OAuth session.
  • Supports DEMO_MODE=TRUE to simulate success.
• GET /health
  • Basic health endpoint.
• Request observability
  • Adds x-request-id correlation header to every response.
  • Emits structured request completion logs and external Grants.gov call timing logs.

Current Limitations

• Partial async migration:
  • Grants lookup is async.
  • Google API SDK calls are sync and currently executed via route-level thread offload.
• Contract drift:
  • focus_area is now applied as a simple substring filter; advanced semantic filtering is not implemented yet.
• OAuth lifecycle:
  • Access-token-only mode is still supported.