# SBIR/STTR Grant Intelligence — MCP Server Protocol

The MCP server exposes the grant intelligence system to AI agents over stdio using
JSON-RPC 2.0. It is **MCP-native-first**: an agent can search, match, and explain
grants without a UI.

Run: `python mcp_server.py`
Transport: stdio (one JSON object per line, newline-delimited).
Protocol version: `2024-11-05`.

Every tool result includes the required Grants.gov attribution string.

---

## Handshake

**initialize**
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
```
Response:
```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",
  "capabilities":{"tools":{}},"serverInfo":{"name":"grants-sbir-mcp","version":"2.0.0"}}}
```

**tools/list** → returns the 11 tools below.
**tools/call** → invoke a tool.
**ping** → `{"jsonrpc":"2.0","id":N,"result":{}}`.

---

## Tools

### `search_grants`
Search/filter the normalized dataset.
Params: `keyword, agency, top_agency, program (ALL|SBIR|STTR|BOTH|OTHER), status,
min_composite, is_sbir, is_sttr, sort, order, limit (1–100), offset`.
Returns `{ total, count, grants:[ {opp_id,title,agency,top_agency,program,status,
days_to_close,composite,link} ], attribution }`.

### `get_grant`
Full detail for one grant by `opp_id` (synopsis, eligibility, contacts, awards).

### `match_grants_to_profile`
Score and rank all grants against a profile.
Params: `profile: {keywords:[], agencies:[], tech_domains:[]}, limit, min_composite`.
Returns top-N with full `score` (component scores + `reasons` + `warnings`).

### `closing_soon`
`within_days` (default 14). Returns grants closing in that window.

### `search_by_agency`
Filter by `top_agency` code (HHS, NSF, DOD, NASA, ...).

### `search_by_topic`
Free-text `topic` matched against title/synopsis.

### `explain_match`
**Transparency tool.** Given `opp_id` (+ optional `profile`), returns the full score
breakdown with human-readable `reasons`. This is how an agent justifies a recommendation.

### `get_recommended_grants`
Top recommended opportunities for a profile (or top by score with no profile).
Each result includes `top_reasons` (first 3 explanation lines) for compact display.

### `get_grant_contacts`
Just the contact block: `contact_name, contact_email, contact_phone, link`.

### `get_grant_requirements`
Eligibility, applicant types, funding instruments, award ceiling/floor, cost sharing.

### `agencies`
Coverage breakdown: count + SBIR/STTR counts per agency.

---

## Example: agent finds matches for an AI/health startup

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"match_grants_to_profile",
   "arguments":{"profile":{"keywords":["AI","diagnostics"],"agencies":["NIH"],"tech_domains":["health"]},"limit":3}}}
```
```json
{"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{
  \"profile\":{\"keywords\":[\"AI\",\"diagnostics\"],\"agencies\":[\"NIH\"],\"tech_domains\":[\"health\"]},
  \"count\":3,
  \"results\":[
    {\"opp_id\":\"359671\",\"title\":\"NIH, CDC and FDA Small Business Innovation Research Grant (Parent SBIR [R43/R44])\",
     \"agency\":\"National Institutes of Health\",\"program\":\"SBIR\",
     \"days_to_close\":null,\"link\":\"https://www.grants.gov/opportunity/359671\",
     \"score\":{\"relevance\":85,\"eligibility\":90,\"urgency\":30,\"agency_fit\":100,\"tech_fit\":90,\"composite\":87,
       \"reasons\":[\"Relevance: matches your keyword(s): AI, diagnostics\",
                   \"Eligibility: SBIR/STTR program — designed for for-profit small businesses.\",
                   \"Agency fit: matches your target ['NIH'] (record agency: National Institutes of Health).\"],
       \"warnings\":[]}}
  ],
  \"attribution\":\"This product uses the Grants.gov API but is not endorsed or certified by the U.S. Department of Health and Human Services.\"}"}]}}
```

---

## Configuration for Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "grants-sbir": {
      "command": "python",
      "args": ["/absolute/path/to/grants_sbir_mcp/mcp_server.py"]
    }
  }
}
```

No environment variables or secrets are required. The server reads the local SQLite
database built by `python -m gsb.pipeline` (or `run.py ingest`).

---

## Design notes
- Responses are compact JSON — no padding, no unnecessary fields — for efficient agent
  parsing and low token cost.
- `explain_match` and `get_recommended_grants.top_reasons` exist specifically so an agent
  can *show its work* rather than asserting a match.
- The MCP and REST layers share the same `gsb` core; behavior is identical across both.