# VoxPilot MCP Server

Production-ready remote **Model Context Protocol** (MCP) server for the VoxPilot AI SaaS platform.

| | |
|---|---|
| **Transport** | Streamable HTTP (remote MCP, not stdio) |
| **Auth** | JWT (RS256), tenant-scoped, scope-based permissions |
| **Modules** | 15 tool groups covering restaurant orders, messaging, POS, calendars, customer memory, QA, handoff, and more |
| **Deployment** | Docker → GHCR → Coolify |
| **Runtime** | Node.js 22, Express 5, TypeScript |

## Quick Start

```bash
# Local dev
npm install
cp .env.local.example .env
npm run dev

# Docker
npm run docker:build
npm run docker:run
```

## Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| POST | `/mcp` | JWT | MCP protocol endpoint (Streamable HTTP) |
| GET | `/health` | No | Health check |
| GET | `/ready` | No | Readiness check |
| GET | `/live` | No | Liveness probe |
| GET | `/version` | No | Server version info |
| GET | `/tools` | No | Module diagnostics (not MCP protocol) |
| GET | `/tools/:module` | No | Per-module diagnostics |
| GET | `/metrics` | No | Prometheus metrics (if enabled) |
| GET | `/.well-known/oauth-protected-resource` | No | OAuth metadata |

## MCP Endpoint

The real MCP protocol happens at `/mcp`. The `/tools/:module` URLs are module aliases for diagnostics, documentation, and backend configuration clarity — they do not replace `/mcp`.

### Local Caddy

```
mcp.voxpilot.test {
  tls internal
  reverse_proxy mcp-server:8080
}
```

Add to `/etc/hosts`:
```
127.0.0.1 mcp.voxpilot.test
```

## Auth Model

JWT tokens issued by VoxPilot NestJS backend with these claims:

```json
{
  "iss": "voxpilot-api",
  "aud": "voxpilot-mcp",
  "sub": "user_or_service_id",
  "tenantId": "tenant_uuid",
  "role": "owner | admin | agent | system",
  "scopes": ["mcp:tools:read", "orders:read", "..."],
  "callId": "optional",
  "sessionId": "optional"
}
```

### Dev Bypass

Set `DEV_BYPASS_AUTH=true` in `.env` for local development (blocked in production).

```env
DEV_BYPASS_AUTH=true
DEV_TENANT_ID=dev-tenant
DEV_SUBJECT=dev-user
DEV_ROLE=system
DEV_SCOPES=mcp:tools:read,orders:read,orders:write,messages:send,pos:read,pos:write,customers:read,customers:write,calendar:read,calendar:write,business:read,payments:write,qa:write,handoff:write,analytics:read
```

## Tool Modules (15)

| # | Module | Status |
|---|--------|--------|
| 1 | `system-core` | 3 tools implemented (`ping`, `version`, `listModules`) |
| 2 | `restaurant-order` | 1 mock tool (`validateOrderDraft`) |
| 3 | `messaging-dispatch` | 1 mock tool (`dispatchTest`) |
| 4 | `pos-connector` | 1 mock tool (`testConnection`) |
| 5 | `customer-memory` | Placeholder |
| 6 | `calendar-appointments` | 1 mock tool (`getProviderStatus`) |
| 7 | `business-knowledge` | Placeholder |
| 8 | `payments-deposits` | Placeholder |
| 9 | `call-qa` | Placeholder |
| 10 | `handoff` | Placeholder |
| 11 | `delivery-routing` | Placeholder |
| 12 | `promotions-upsell` | Placeholder |
| 13 | `menu-availability` | Placeholder |
| 14 | `onboarding` | Placeholder |
| 15 | `analytics-insights` | Placeholder |

## Integration

VoxPilot NestJS backend calls the MCP server via POST to `/mcp` with:

```
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json, text/event-stream
```

Example JSON-RPC tool call:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "systemCore.ping",
    "arguments": { "message": "hello" }
  }
}
```

## Spec-Driven Development

Each module is implemented spec-by-spec. See `specs/` for the 16 spec files (000–015).  
No module is implemented without a spec.

## What is intentionally not yet implemented

- Real WhatsApp, Telegram, Slack, SMS, email dispatch
- Real POS connections (TastyIgniter, Odoo)
- Real Google Calendar / Outlook integration
- Real payment processing (Stripe)
- Real call QA analysis
- Real customer memory persistence
- Real analytics queries
- Redis-backed queues or caching
- PostgreSQL audit persistence
- OpenTelemetry export

## Production Deployment

```yaml
# docker-compose.yml (VoxPilot root stack)
mcp-server:
  build:
    context: ./voxpilot-mcp-server
    dockerfile: docker/Dockerfile
  ports:
    - "8080:8080"
  env_file:
    - .env
  networks:
    - voxpilot
```

Image published to `ghcr.io/nehilor/voxpilot-mcp-server` with tags `latest`, `develop`, `sha-<shortsha>`.