# MCP Server: CRM Agent Tools — Working Demo

## What This Does
A minimal, working MCP server (built with the official `mcp` Python SDK, stdio transport)
that gives a Claude agent three tools: look up a CRM contact, log an action taken on that
contact, and audit any prompt for token waste and API cost before it ships. A Streamlit app
sits on top so the exact same tool definitions and functions can be browsed and called
without a Claude Desktop or Claude Code MCP connection.

## How It Works
Claude agent (or this Streamlit form) calls a tool → `mcp_server.py` routes it to the
matching function in `tools.py` → the function hits sample data or a live API if configured
→ a structured JSON result comes back → the caller (agent or UI) verifies it against the
returned fields.

## The Three Tools
- **`lookup_crm_contact(email)`** — data lookup. Returns name, company, deal owner, deal
  stage, and days since last contact. Reads `sample_data/crm_contacts.json` first, falls back
  to a deterministic mock record if the email isn't in the sample file.
- **`log_crm_action(contact_email, action, notes)`** — action tool. Writes a real, timestamped
  entry to `sample_data/action_log.jsonl` (not simulated, this is a genuine disk write standing
  in for a CRM write endpoint).
- **`audit_prompt_cost(prompt_text, model)`** — structured status tool. Estimates token count
  and per-call cost, flags prompts that are long enough or repetitive enough to be worth
  rewriting as code instead of a bigger system prompt. Uses the live Anthropic token-counting
  endpoint if `ANTHROPIC_API_KEY` is set, otherwise a `~4 chars/token` offline estimate.

## Quick Start (Streamlit UI, zero config)
```bash
pip install -r requirements.txt
streamlit run app.py
```
Opens with sample CRM contacts pre-loaded. Click through the three tabs to call each tool
directly, no API keys required.

## Quick Start (real MCP server, connect to Claude)
```bash
pip install -r requirements.txt
python mcp_server.py          # runs over stdio, waits for an MCP client
```
Register it with Claude Code:
```bash
claude mcp add crm-agent-tools -- python /absolute/path/to/mcp_server.py
```
Or add it to `claude_desktop_config.json` under `mcpServers` (see the header comment in
`mcp_server.py` for the exact block).

## Smoke Test (no server, no UI)
```bash
python -c "from tools import lookup_crm_contact, log_crm_action, audit_prompt_cost; \
print(lookup_crm_contact('jordan@northwindtraders.com')); \
print(log_crm_action('jordan@northwindtraders.com', 'called', 'left voicemail')); \
print(audit_prompt_cost('Always remember to never forget to double check.'))"
```

## Configuration
- `ANTHROPIC_API_KEY` (optional) — enables live token counting in `audit_prompt_cost` via
  `anthropic.messages.count_tokens`. Without it, a chars/4 heuristic estimate is used instead.
- `CRM_API_KEY` (optional, not wired to a live CRM in this demo) — if set, `lookup_crm_contact`
  notes that a real integration isn't connected yet rather than silently pretending it is.

## Demo Limitations
- This is an MVP demo — `lookup_crm_contact` reads a local JSON file instead of a live
  HubSpot/Airtable/Sheets API. Swapping in a real API call only touches the one function.
- `log_crm_action` writes to a local JSONL file instead of a live CRM write endpoint, same
  swap-in-one-place design.
- `audit_prompt_cost` uses a fixed per-model pricing table rather than a live pricing API,
  and assumes a flat 300-token output for the cost projection.
- No auth/session management on the MCP server since this is a local stdio demo, not a
  hosted multi-tenant server.