README.md

metadata

title: Meridian Support Chat
emoji: 💬
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.13.0
app_file: meridian.py
pinned: false

Meridian Support Chatbot

Customer support chatbot prototype for Meridian Electronics, built on the company's existing MCP server.

Problem

Meridian's support team handles every customer inquiry by phone and email — including the repetitive ones: stock checks, order status, placing orders, and identifying returning customers. That doesn't scale. Leadership needs evidence that a low-cost LLM can absorb these workflows reliably and cheaply enough to fund a rollout next quarter.

Solution

A Python chatbot using OpenAI's Agents SDK with gpt-4o-mini, connected over Streamable HTTP to the Meridian MCP, surfaced in a Gradio UI with live per-conversation cost tracking — the unit-economics signal the VP needs to make the funding decision.

Architecture

Gradio UI
    ↓
OpenAI Agents SDK   (gpt-4o-mini · streaming · SQLiteSession)
    ↓
MCPServerStreamableHttp   (cached tool list · retries · 15s timeout)
    ↓
Meridian MCP   (Cloud Run · 8 tools across products / customers / orders)

Auth model: verify_customer_pin must succeed before any customer-scoped read or write. Public reads (catalog browsing) need no auth. The agent never trusts a user-asserted customer_id.

Setup

Requires Python ≥3.12 and uv.

uv sync
cp .env.example .env        # add your OPENAI_API_KEY
uv run python -m app.ui     # launches Gradio chat

Phase-0 connectivity proof (one OpenAI call, prints discovered tools):

make smoke

Inspect the upstream MCP

./scripts/inspect_mcp_cli.sh         # pure CLI: tools/list, prompts/list, resources/list
./scripts/inspect_mcp_browser.sh     # launches the MCP Inspector web UI

Testing

make test            # tier 1 — MCP connectivity, no LLM cost
make test-auth       # tier 3 — auth-gate negative test (live)
make test-workflows  # tier 2 — all 4 workflow tests (live)
make help            # full target list

Live tests hit real OpenAI + the real MCP and auto-skip without OPENAI_API_KEY. make test-purchase mutates dev-MCP state (creates a real order each run).

Project layout

app/        agent runtime, MCP client, cost tracking, Gradio UI
tests/      tiered test suite (connectivity → auth gate → workflows)
scripts/    MCP inspection helpers