SupportOps

An AI customer-support assistant for a simulated e-commerce store, built on the Model Context Protocol (MCP). Customers and support staff sign in, ask questions in plain English, and an LLM (via Groq) answers by calling MCP tools that read real records from PostgreSQL: orders, shipments, tickets, returns, refunds and policies.

The point of the project is safe tool use by an LLM: the model only sees the tools the signed-in user is allowed to use, every action is checked against the user’s identity on the server, and nothing is changed until a person clicks a confirmation button.

All data is synthetic or anonymized (built from the public Olist Brazilian e-commerce dataset). Refunds and payments are simulated; no real money moves.

---

Features

• Chat assistant (/): customers ask about their orders, deliveries, tickets, returns and refunds; staff ask about cases assigned to them.
• Confirm-before-write actions: the model can only draft a customer action (create a ticket, reply to a ticket, submit a return). The customer reviews it and presses Confirm before anything is written.
• Role-based tool access: customers and staff get different tool sets. A customer can only see their own orders and tickets; an agent only sees assigned cases; supervisors have wider scope.
• MCP activity panel: every chat answer shows which tools ran, with what arguments, how long they took, and exactly what data was sent to the model.
• Staff workflows (MCP tools): return review, item receipt, refund proposal, supervisor approval (a different person must approve), simulated refund execution, and ticket resolution checks.
• Editor integration: the same MCP server works from VS Code (Copilot agent mode) or Cursor, with its own login and read-only tools.
• Developer console (/console): call any read tool, resource or prompt directly to compare with the chat’s answers.

How it works

Browser (chat.html)
   │  HttpOnly session cookie + CSRF token
   ▼
Web host (Starlette, web_host.py) ──── Groq API (LLM, function calling)
   │  starts an isolated MCP process per request,
   │  passing only the session token
   ▼
MCP server (mcp_server.py, stdio)
   │  resolves the session → customer / agent / supervisor
   ▼
Service layer (read / write / refund / staff / resolution)
   ▼
PostgreSQL (25 domain tables + 2 auth tables, Alembic migrations)

1. The host discovers the MCP tools allowed for the current session and passes their descriptions and JSON schemas to Groq as function definitions.
2. When the model requests a tool, the host checks it against the allowlist and validates the arguments against the schema, then calls it through MCP.
3. The MCP server re-checks the session on every call, so a forged or out-of-scope request is refused even if the model tries it.