# GTM Agent MCP Server

Ask a GTM engineer agent about its own work in plain English, from Claude Code or Claude Desktop: "show Gong's ICP", "what did this week's runs cost?", "rank the prospects".

The agent (research, list building, signals, copy) writes everything to files. Without this server, answering those questions means opening JSON by hand. This server reads the agent's `output/` folder and exposes it as 8 read-only MCP tools, plus one guarded tool that starts a new research run.

```
Claude ──MCP (stdio)──► gtm-mcp ──reads──► agent output/
                                            ├── <client>/profile.json
                                            ├── <prospect>/prospect_brief.json
                                            ├── <client>/signals/, list/
                                            └── runs.jsonl  (every run: status, judge score, cost)
```

## Tools
| Tool | Answers |
|---|---|
| `list_clients` | Which clients have a profile, last profile run |
| `get_profile` | A client's ICP, competitors, signals to watch |
| `list_runs` | Run history: status, judge score, retries, force-approves, cost |
| `run_costs` | Spend grouped by job, company or day |
| `get_prospect_brief` | One prospect's research and fit score |
| `rank_prospects` | Prospects ranked by fit score, tiers A / B / C |
| `get_signals` | Latest buying-signal alerts with source and date |
| `get_list_summary` | Prospect list size and funnel |
| `run_prospect_research` | Starts a prospect research run (spends money, guarded) |

## The action tool
`run_prospect_research(domain, client, confirm)`:
1. Checks the domain and that the client has a profile.
2. Without `confirm`, only previews: what will run, estimated cost (average of past runs), today's usage.
3. Refuses past the daily caps (`GTM_MCP_MAX_RUNS`, default 5; `GTM_MCP_MAX_USD`, default $2).
4. Runs the agent's CLI with a timeout, then reads back the new run log line and brief. A failed run returns the agent's error and is never retried on its own.
5. Logs every call, refusals included, to `calls.jsonl`.

## Design choices
- **Read tools are read-only, and marked so.** They carry `read_only_hint` and never write or call a paid API. Only `run_prospect_research` spends, and only after a preview and an explicit confirm.
- **No contact data.** Names, emails and LinkedIn URLs in the agent's lists are never returned (tested).
- **Answers cite their file.** Every result has a `source`, so Claude can say where a number came from.
- **Missing data is a message, not a crash.** "Signals sweep for 'gong.io' not found" instead of a stack trace.
- **Honest about gaps.** The agent does not record which client a prospect brief was scored for, so `rank_prospects` says it ranks every saved brief.

## Run
```
uv sync
uv run python -m unittest discover -s tests     # 18 tests on fake data; the agent run is faked
claude mcp add gtm-agent -e GTM_AGENT_OUTPUT_DIR=<agent>/output -- uv run --directory <this folder> gtm-mcp
```

## Credits
The GTM engineer agent this server reads from is DFY Automation's open-source GTM Engineer (community edition), MIT licensed: https://github.com/dfyautomation/gtm-engineer-community. This server does not include or modify its code.