Zuupee MCP

Monorepo for Zuupee's Model Context Protocol (MCP) tooling and website chatbot stack.

Packages

Package	Status	Description
`mcp-server`	Available	General-purpose MCP server with pluggable modules, stdio and HTTP transports
`mcp-client`	In progress	Multi-server MCP client with namespaced tools
`chat-orchestrator`	Available	Custom ReAct agent loop with OpenAI + MCP tools
`chat-api`	Available	HTTP API + SSE for the website chatbot
`chat-widget`	Available	Embeddable chat UI (Vite → single JS bundle)
`mock-api-server`	Available	Local JSON orders API for dev and tests

Domain plugins live under mcp-server/plugins/ — see the orders plugin for a reference integration.

See docs/chatbot-implementation-plan.md for the full build plan.

Getting started

pnpm install
pnpm build
pnpm test

MCP server

pnpm -C mcp-server dev

MCP client smoke test

pnpm -C mcp-client dev

Mock API server

pnpm dev:mock-api-server

Then run mcp-server with MCP_MODULES=meta,orders and ORDERS_API_BASE_URL=http://127.0.0.1:3999.

Chat orchestrator (terminal demo)

Set OPENAI_API_KEY in .env, then:

# Terminal 1
pnpm dev:mock-api-server

# Terminal 2
MCP_SERVERS_CONFIG=./config/mcp-servers.chat.example.json \
pnpm dev:orchestrator -- "What is the status of order ord_123?"

Chat API

Set OPENAI_API_KEY in .env.local, then:

# Terminal 1
pnpm dev:mock-api-server

# Terminal 2
pnpm dev:chat

Create a session and stream a reply:

SESSION=$(curl -s -X POST http://127.0.0.1:3200/chat/sessions | jq -r .sessionId)
curl -N -X POST "http://127.0.0.1:3200/chat/sessions/$SESSION/messages" \
  -H "Content-Type: application/json" \
  -d '{"content":"What is the status of order ord_123?"}'

Copy .env.example to .env.local at the repo root and set OPENAI_API_KEY for orchestrator demos.

# Terminal 1
pnpm dev:mock-api-server

# Terminal 2
pnpm dev:chat

# Terminal 3
pnpm dev:widget

Open http://localhost:5173 and use the chat button. The widget proxies API calls to chat-api via /api in dev.

Embed on any site:

<script
  src="https://cdn.example.com/chat-widget.js"
  data-api-url="https://chat.example.com"
  data-theme="light"
></script>

Docker Compose demo

Build the widget, then start the stack (reads OPENAI_API_KEY from .env.local):

pnpm -C chat-widget build
pnpm docker:chat

Open http://localhost:8080 for the widget and http://localhost:3200/health for API status.

Production hardening

Redis sessions: set CHAT_REDIS_URL=redis://127.0.0.1:6379 (Docker Compose includes Redis)
OTEL traces: set OTEL_ENABLED=true and point OTEL_EXPORTER_OTLP_ENDPOINT at your collector
Per-environment MCP config: set CHAT_ENV=staging or production (uses config/mcp-servers.<env>.json)
Load test: pnpm load-test:chat (targets p95 < 10s for session create)

See docs/e2e-manual-checklist.md for the full E2E checklist.

Repository layout

.
├── mcp-server/          # @zuupee/mcp-server
├── mcp-client/          # @zuupee/mcp-client
├── chat-orchestrator/   # @zuupee/chat-orchestrator
├── chat-api/            # @zuupee/chat-api
├── chat-widget/         # @zuupee/chat-widget
├── mock-api-server/     # @zuupee/mock-api-server
├── config/              # Shared MCP server config for local dev
└── docs/

License

MIT

@zuupee/mcp-server