# Mini CRM MCP

A complete, end-to-end **Model Context Protocol** server over `crm/leads.db` (40 sales leads). An
MCP client or LLM can ask "give me the funnel by stage", "what's in Priya's pipeline", or "what's
our weighted forecast" and get structured answers without ever writing SQL.

This is a *practical* server (like the sibling `Mcp_venki` is a *teaching* one). It replaced an
earlier StudentAnalytics prototype — same architecture, pointed at real CRM data.

Pipeline stages: **New → Contacted → Qualified → Proposal → Won / Lost**.

## What it exposes

### Tools (model-callable)
| Tool | Purpose |
|------|---------|
| `pipeline_summary()` | The funnel: count + total value per stage |
| `list_owners()` | Every rep with lead count and total pipeline value |
| `list_leads(status?, owner?, source?, min_value?, limit=25)` | Filtered lead list (all filters ANDed) |
| `search_leads(query, limit=25)` | Free-text search across name / company / email |
| `get_lead(lead_id)` | One full lead record + close probability |
| `owner_leaderboard()` | Per-rep won / open / weighted-forecast value |
| `forecast()` | Weighted revenue forecast; streams progress via `ctx` |

### Resources (loadable read-only data)
- `crm://schema` — the table schema + stage order
- `crm://lead/{lead_id}` — a single lead as a readable card (URI template)

### Prompt
- `pipeline_review(owner?)` — template that asks the model to write a pipeline review

### The weighted forecast
Each stage has a close probability (New 10%, Contacted 25%, Qualified 50%, Proposal 70%, Won 100%,
Lost 0%). `forecast()` and `owner_leaderboard()` multiply each lead's value by its stage probability
and sum — a standard sales-forecasting method. On the current data this yields ≈ **$396,755**
weighted against a **$942,310** raw pipeline.

## Safety

The SQLite connection is opened with `mode=ro`, so the server **physically cannot write** to the
DB — the engine rejects any mutation. Every query is a parameterized `SELECT`; tool arguments are
bound, never string-formatted, so they can't inject SQL. A test asserts the read-only guarantee.

## Run it

Use any Python (3.10+) that has the `mcp` SDK installed:

```
pip install -r requirements.txt

# 1. Drive it end-to-end with a hand-written client (no Claude, no config):
python client_demo.py

# 2. Run the protocol tests (launch the real server over stdio):
python -m pytest test_server.py -q
```

A demo database ships in `data/leads.db`, so the server runs out of the box.
`CRM_DB` (env var) overrides the database path to point at your own leads table.

## Registered in Claude

Added to the project `.mcp.json` as **`MiniCRM`**, pointing at the hermes-venv Python and the repo's
`crm/leads.db`. Restart the app / reconnect MCP servers to pick it up, then the tools appear as
`mcp__MiniCRM__*` and the prompt as `/mcp__MiniCRM__pipeline_review`.

## Files

- `server.py` — the MCP server (7 tools, 2 resources, 1 prompt)
- `client_demo.py` — hand-written stdio client that exercises every primitive
- `test_server.py` — 8 protocol-level tests (all passing)
- `data/leads.db` — bundled demo database (40 synthetic leads)
- `requirements.txt` / `pytest.ini`
- `docs/` — the illustrated deep-dive PDF and its HTML source

## Gotchas (carried over from building the sibling servers)

1. **FastMCP returns a `list` as one content-block per item**, and puts the whole value in
   `result.structuredContent` (list/scalar wrapped as `{"result": ...}`, dict returns as-is).
   Read `structuredContent`, not `content[0].text`, or you only see the first element.
2. **`session.read_resource(uri)` returns a result with `.contents`**, not a 2-tuple.
3. **Don't hold the MCP session in a `pytest_asyncio` async-generator fixture** — anyio's cancel
   scope is finalized in a different task and every test errors in teardown. Use `async with`
   inside the test body (see `test_server.py`).