# Acme Operations Assistant (MCP demo)

A **client-ready** demo: an AI operations assistant for customer support and account managers, built on the [Model Context Protocol](https://modelcontextprotocol.io/).

**Stack:** MCP server → SQLite business data → OpenAI → Streamlit UI

## Why this is a “real” project

- **Business domain** — customers, orders, support tickets (not `hello world` math)
- **Persistent data** — seeded SQLite database you can reset and extend
- **Transparent tool calls** — the UI shows exactly which MCP tools ran and what they returned
- **Portable integration** — the same MCP server works in Cursor, custom apps, or OpenAI Agents SDK

## Quick start (client demo)

```bash
cd /apps/tmp/mcp-servers
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[demo]"

export OPENAI_API_KEY=sk-...
streamlit run demo_app.py
```

Open **http://localhost:8501** and use the sidebar scenario buttons.

Full presenter script: **[DEMO.md](DEMO.md)**

## Project layout

| File | Purpose |
|------|---------|
| `server.py` | MCP server — 7 business tools over stdio |
| `ops_db.py` | SQLite schema + demo seed data |
| `demo_app.py` | Streamlit chat UI for presentations |
| `assistant.py` | OpenAI ↔ MCP bridge (shared by UI and CLI) |
| `client.py` | Smoke test MCP tools (no API key) |
| `openai_chat.py` | CLI assistant |
| `openai_agent.py` | Same flow via OpenAI Agents SDK |

## MCP tools

| Tool | Description |
|------|-------------|
| `search_customers` | Search by name, id, email, industry |
| `get_customer` | Full customer profile |
| `get_order` | Order status + line items |
| `list_customer_orders` | Order history for a customer |
| `list_open_tickets` | Open support tickets |
| `create_support_ticket` | Create ticket (writes to DB) |
| `account_summary` | Executive snapshot for an account |

## Commands

```bash
# UI demo (recommended for clients)
streamlit run demo_app.py

# MCP smoke test — no OpenAI key
python client.py

# CLI assistant
python openai_chat.py "Account summary for CUST-1003"

# Reset demo database
python scripts/reset_demo_data.py
```

## Connect to OpenAI (details)

The MCP server uses **stdio**. Your app must spawn it (as `demo_app.py` and `assistant.py` do).

- **Chat Completions bridge:** `assistant.py` / `openai_chat.py`
- **Agents SDK:** `openai_agent.py` — `pip install -e ".[agents]"`
- **Responses API (remote URL):** deploy server over HTTP; see [OpenAI MCP guide](https://developers.openai.com/api/docs/guides/tools-connectors-mcp)

## Cursor / Claude Desktop

```json
{
  "mcpServers": {
    "acme-operations": {
      "command": "/apps/tmp/mcp-servers/.venv/bin/python",
      "args": ["/apps/tmp/mcp-servers/server.py"]
    }
  }
}
```

## Next steps for production

1. Replace SQLite with CRM/ERP APIs behind the same tool names  
2. Add auth (OAuth) per user and row-level access on tools  
3. Require human approval for `create_support_ticket` in production  
4. Deploy MCP over HTTP + host the Streamlit app behind SSO