一个基于**模型上下文协议（MCP）**构建的模拟电子商务商店的AI客户支持助手。客户和支持人员登录，用通俗易懂的英语提问，LLM（通过Groq）通过调用MCP工具回答，这些工具读取PostgreSQL的真实记录：订单、发货、工单、退货、退款和政策。

项目的重点是LLM安全使用工具：模型只看到登录用户允许使用的工具，每项操作都会与服务器用户身份核对，直到有人点击确认按钮前不会有任何更改。

所有数据均为合成或匿名化（基于公开的巴西Olist电子商务数据集构建）。退款和支付过程均为模拟;无真钱交易。

---

特色

• 聊天助理（/）：顾客询问订单、配送、工单、退货和退款;工作人员询问分配给他们的案件情况。
• 确认后写入操作：模型只能草拟客户操作（创建工单、回复工单、提交退货）。客户审核后按下确认，然后才写入任何内容。
• 基于角色的工具访问：客户和员工获得不同的工具集。

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.