@velaro/mcp-server 0.1.0 → 0.4.0

package/README.md

@@ -1,20 +1,35 @@
 # @velaro/mcp-server
 
-Connect Claude, Claude Code, and other AI agents directly to your Velaro account via the [Model Context Protocol](https://modelcontextprotocol.io).
+**The only customer support platform with a native, self-updating MCP server.**
 
-## Quick Start
+Connect Claude, Claude Code, Claude Desktop, or any MCP-compatible AI agent directly to your Velaro account — knowledge base, workflows, conversation data, and 596 AI skills across 20+ commerce and CRM platforms.
 
 ```bash
 npx @velaro/mcp-server
 ```
 
-Set your MCP key (create one in Velaro Settings > API > MCP Keys):
-
+Set your key and go:
 ```bash
 VELARO_MCP_KEY=vel_live_... npx @velaro/mcp-server
 ```
 
-## Claude Code Setup
+---
+
+## Why Velaro MCP Is Different
+
+Most chat platforms require webhooks, custom API wrappers, or point-to-point integrations to give an AI agent access to customer data. Velaro ships a published npm package that turns Claude into a first-class operator of your entire support infrastructure — no wrapper code, no custom authentication layer, no waiting for an API integration to be built.
+
+- **One command install** — `npx @velaro/mcp-server` pulls the latest version automatically
+- **Hosted HTTP endpoint** — no Node.js required; point Claude Desktop at `https://velaro-admin-staging.azurewebsites.net/mcp` with a Bearer token
+- **Auto-updates** — the package is republished on every production deploy; `npx` always runs the latest
+- **596 AI skills** — Shopify, BigCommerce, WooCommerce, Magento, HubSpot, Salesforce, NetSuite, ServiceNow, Dynamics 365, SAP, Square, QuickBooks, Jobber, and more — all callable from within Claude
+- **25 built-in tools** — conversations, workflows, bots, contacts, agents, teams, routing rules, conversion tracking, and full KB management
+
+---
+
+## Quick Start
+
+### Claude Code
 
 Add to `~/.claude/settings.json`:
 
@@ -32,9 +47,9 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
-## Claude Desktop Setup
+### Claude Desktop
 
-Add to `~/.claude/claude_desktop_config.json`:
+Add to `~/.config/claude/claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
@@ -50,24 +65,223 @@ Add to `~/.claude/claude_desktop_config.json`:
 }
 ```
 
+### Hosted HTTP Endpoint (No Node Required)
+
+If you prefer not to run a local Node process, point directly at Velaro's hosted MCP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "velaro": {
+      "url": "https://api-admin-us-east.velaro.com/mcp",
+      "headers": {
+        "Authorization": "Bearer vel_live_..."
+      }
+    }
+  }
+}
+```
+
+This works with any MCP client that supports HTTP/SSE transport — including Claude Desktop 0.8+.
+
+---
+
 ## Available Tools
 
-| Tool | Description |
+### Knowledge Base
+| Tool | What It Does |
 |------|-------------|
-| `kb_list_topics` | List all KB topics |
-| `kb_search_articles` | Search articles by term, topic, or publish status |
-| `kb_get_article` | Get full article content by ID |
-| `kb_create_article` | Create a new article |
-| `kb_update_article` | Update an existing article |
+| `kb_list_topics` | List all knowledge base topics |
+| `kb_search_articles` | Search articles by keyword, topic, or publish status |
+| `kb_get_article` | Retrieve full article content by ID |
+| `kb_create_article` | Create and optionally publish a new article |
+| `kb_update_article` | Update title, body, tags, or publish status |
 | `kb_delete_article` | Delete an article |
 
-## Auth
+### Conversations
+| Tool | What It Does |
+|------|-------------|
+| `conversation_list` | List recent conversations filtered by channel, status, or agent |
+| `conversation_get` | Get full details for a single conversation |
+| `conversation_search` | Search conversations by phone number or call SID |
+
+### Workflows
+| Tool | What It Does |
+|------|-------------|
+| `workflow_list` | List all workflows with enabled state and trigger type |
+| `workflow_get` | Get full workflow details by ID |
+| `workflow_toggle` | Enable or disable a workflow |
+
+### Bots & AI Configurations
+| Tool | What It Does |
+|------|-------------|
+| `bot_list` | List all bot/AI configurations for this site |
+| `bot_get` | Get full bot config including system prompt |
+| `bot_update_prompt` | Update a bot's system prompt |
+
+### Contacts
+| Tool | What It Does |
+|------|-------------|
+| `contact_search` | Search contacts by name, email, phone, or company |
+| `contact_get` | Get full contact details by ID |
+
+### Team & Routing
+| Tool | What It Does |
+|------|-------------|
+| `agent_list` | List agents with availability status; filter by team |
+| `team_list` | List all teams for this site |
+| `routing_list` | List all routing rules ordered by priority |
+| `routing_get` | Get routing rule details including rule and value JSON |
+
+### Site
+| Tool | What It Does |
+|------|-------------|
+| `site_info` | Get site settings, active channels, subscription features, and resource counts |
+
+### Live Operations
+| Tool | What It Does |
+|------|-------------|
+| `kpi_snapshot` | Real-time ops dashboard — agents online/available/busy, open/queued conversations, bot-active count, resolved today, queue wait times, top agents, channel breakdown, per-team coverage status |
+
+### CSAT
+| Tool | What It Does |
+|------|-------------|
+| `csat_summary` | Customer satisfaction — avg rating, satisfaction rate, star breakdown, recent verbatim comments |
+
+### Bot Diagnostics
+| Tool | What It Does |
+|------|-------------|
+| `bot_analytics_summary` | AI bot health — total skill calls, error count, success rate, top skill, training count |
+| `bot_skill_usage` | Per-skill call counts by integration + error counts — identifies over/underused skills and failing integrations |
+| `bot_recent_errors` | Last N AI skill errors with integration, message, and timestamp — for active troubleshooting |
+
+### Service Level
+| Tool | What It Does |
+|------|-------------|
+| `service_level_report` | SLA compliance per period — % within threshold, avg response time, avg handle time. Granularity: hour/day/week/month |
+
+### Reporting & Analytics
+| Tool | What It Does |
+|------|-------------|
+| `report_roi_summary` | Full ROI report — bot deflections, hours saved, cost savings, AI skill executions, resolution rate, response time, trends vs prior period, monthly breakdown, top skills by call count, channel breakdown |
+| `report_agent_utilization` | Per-agent stats — conversation count, avg handle time, active/away breakdown for any date range |
+| `report_campaign_performance` | Email campaign KPIs — open rate, click rate, delivery rate, complaint rate per campaign + aggregate totals |
+| `report_campaign_deliverability` | Deliverability health check — bounce rate, complaint rate, unsubscribe rate, open rate with traffic-light status and fix recommendations |
+| `report_campaign_monthly` | Month-by-month email volume for the last 12 months |
+| `report_audience_growth` | Total active contacts, net contacts (minus unsubscribes), month-by-month additions |
+
+### Conversion Tracking
+| Tool | What It Does |
+|------|-------------|
+| `conversion_list_goals` | List all conversion goals |
+| `conversion_create_goal` | Create a new conversion goal (URL, Shopify, Square, custom event) |
+| `conversion_get_report` | Get conversion attribution report — revenue, rates, timeline |
+
+More tools are added on every production release. Run `tools/list` to see the current full list from your Claude client.
+
+---
+
+## Getting Your API Key
+
+1. Log in to your Velaro admin at [admin.velaro.com](https://admin.velaro.com)
+2. Go to **Settings → API → MCP Keys**
+3. Click **Create Key** → give it a label (e.g. "Claude Code")
+4. Copy the `vel_live_...` key — it's shown once
 
-- `VELARO_MCP_KEY=vel_live_...` — service key (create in Settings > API > MCP Keys)
-- `VELARO_JWT=<token>` — short-lived JWT from `velaro login` (dev use only)
+Keys are site-isolated: the key is bound to your Velaro account and can only read/write data for that account. You can create multiple keys and revoke them independently.
+
+---
+
+## Auth Options
+
+| Variable | When to Use |
+|----------|-------------|
+| `VELARO_MCP_KEY=vel_live_...` | Production — create in Settings > API > MCP Keys |
+| `VELARO_JWT=<token>` | Development only — short-lived JWT from `velaro login` |
+
+---
 
 ## Staging / Custom API
 
 ```bash
 VELARO_ADMIN_API=https://velaro-admin-staging.azurewebsites.net VELARO_MCP_KEY=vel_live_... npx @velaro/mcp-server
 ```
+
+---
+
+## HTTP Mode (Self-Hosted)
+
+Run as an HTTP/SSE server instead of stdio — useful for shared deployments:
+
+```bash
+VELARO_MCP_MODE=http PORT=3000 VELARO_MCP_KEY=vel_live_... node server.js
+```
+
+Clients connect via `GET /mcp` (SSE stream) and `POST /mcp` (JSON-RPC 2.0).
+
+---
+
+## What You Can Do with Velaro + Claude
+
+Once connected, Claude has direct operator access to your support infrastructure:
+
+**Knowledge Base Management**
+> "Search my KB for any articles about refund policy and update them to reflect the new 30-day window we announced last week."
+
+**Workflow Diagnostics**
+> "List all my disabled workflows and tell me which ones are AI-enhanced so I can decide which to turn back on."
+
+**Bot Prompt Tuning**
+> "Read the current system prompt for bot #3 and rewrite it to be more concise and focus on checkout support."
+
+**Live Operations**
+> "Show me the last 20 open conversations on the SMS channel and tell me which agents have the most active chats right now."
+
+**Contact Lookup**
+> "Search for the contact with email orders@example.com and show me their full profile."
+
+**Routing Audit**
+> "List all routing rules in priority order — I want to review what fires before the 'Default Team' fallback."
+
+**Conversion Tracking**
+> "Create a conversion goal that fires when a customer hits /order-confirmed, with a 24-hour attribution window and $50 default value."
+
+**ROI & Analytics**
+> "Pull the last 30-day ROI report. How many conversations did the bot deflect, how many hours did that save, and which AI skills were called the most?"
+
+**Deliverability Monitoring**
+> "Check our email deliverability health — is our bounce rate or complaint rate in the red? What should we fix?"
+
+**Site Health Check**
+> "Give me a full site overview — active channels, agent count, workflow status, and which subscription features are enabled."
+
+Claude handles these operations natively. No exports, no copy-paste, no waiting for a developer.
+
+---
+
+## How It's Updated
+
+This package is automatically published to npm on every Velaro production deploy. When Velaro ships new tools or improves existing ones, your next `npx` invocation pulls the latest version automatically. You don't need to update a package.json or run `npm install`.
+
+If you want a pinned version for reproducible environments:
+```bash
+npx @velaro/mcp-server@0.1.0
+```
+
+---
+
+## Competitive Context
+
+Intercom, Zendesk, and Freshdesk do not publish MCP servers. Connecting Claude to those platforms requires building a custom MCP wrapper against their REST APIs, handling authentication yourself, and maintaining the integration as their APIs change.
+
+Velaro ships the MCP server, hosts it, auto-updates it, and publishes it to npm. The integration is one `npx` command.
+
+---
+
+## Links
+
+- [Velaro Admin](https://admin.velaro.com)
+- [Documentation](https://help.velaro.com)
+- [npm package](https://www.npmjs.com/package/@velaro/mcp-server)
+- [Source](https://github.com/velaro/velaro-admin/tree/master/mcp)
+- [MCP Specification](https://modelcontextprotocol.io)

package/package.json

@@ -1,32 +1,32 @@
-{
-  "name": "@velaro/mcp-server",
-  "version": "0.1.0",
-  "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro KB and account.",
-  "type": "module",
-  "bin": {
-    "velaro-mcp": "server.js"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
-  },
-  "scripts": {
-    "start": "node server.js"
-  },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/velaro/velaro-admin"
-  },
-  "keywords": ["velaro", "mcp", "knowledge-base", "claude", "ai", "model-context-protocol"],
-  "license": "MIT",
-  "files": [
-    "server.js",
-    "README.md"
-  ]
-}
+{
+  "name": "@velaro/mcp-server",
+  "version": "0.4.0",
+  "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
+  "type": "module",
+  "bin": {
+    "velaro-mcp": "server.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/velaro/velaro-admin"
+  },
+  "keywords": ["velaro", "mcp", "knowledge-base", "claude", "ai", "model-context-protocol", "customer-support", "workflows", "conversations"],
+  "license": "MIT",
+  "files": [
+    "server.js",
+    "README.md"
+  ]
+}

package/server.js

@@ -74,6 +74,30 @@ async function api(method, path, body) {
   return text ? JSON.parse(text) : null;
 }
 
+// Call the hosted MCP gateway (JSON-RPC) for tools that are dispatched server-side.
+async function rpc(toolName, args) {
+  const body = {
+    jsonrpc: '2.0',
+    id: 1,
+    method: 'tools/call',
+    params: { name: toolName, arguments: args ?? {} },
+  };
+  const res = await fetch(`${API_BASE}/mcp`, {
+    method: 'POST',
+    headers: { Authorization: authHeader(), 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Velaro MCP gateway ${toolName} -> ${res.status}: ${text.slice(0, 300)}`);
+  }
+  const data = await res.json();
+  if (data.error) throw new Error(data.error.message || JSON.stringify(data.error));
+  const content = data.result?.content?.[0]?.text;
+  if (content === undefined) throw new Error('Empty response from MCP gateway');
+  return content;
+}
+
 // ── Tool definitions ──────────────────────────────────────────────────────────
 
 const TOOLS = [
@@ -149,6 +173,324 @@ const TOOLS = [
       required: ['id'],
     },
   },
+
+  // ── Conversations ─────────────────────────────────────────────────────────
+  {
+    name: 'conversation_list',
+    description: 'List recent conversations. Returns id, status, phoneNumber, assignedUserId, teamId, createdAt.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit:   { type: 'number',  description: 'Max results (default 20, max 50)' },
+        channel: { type: 'string',  description: 'Filter by channel (e.g. web, sms, ivr)' },
+        status:  { type: 'string',  description: 'Filter by status: open or closed' },
+        agentId: { type: 'number',  description: 'Filter by assigned agent ID' },
+      },
+    },
+  },
+  {
+    name: 'conversation_get',
+    description: 'Get details for a single conversation by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Conversation ID' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'conversation_search',
+    description: 'Search conversations by phone number or call SID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        q:     { type: 'string', description: 'Phone number or call SID to search' },
+        limit: { type: 'number', description: 'Max results (default 10, max 50)' },
+      },
+      required: ['q'],
+    },
+  },
+
+  // ── Workflows ─────────────────────────────────────────────────────────────
+  {
+    name: 'workflow_list',
+    description: 'List all workflows. Returns id, name, enabled, triggerType, AIEnhanced, category.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean', description: 'Filter by enabled state (omit for all)' },
+      },
+    },
+  },
+  {
+    name: 'workflow_get',
+    description: 'Get workflow details by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Workflow ID' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'workflow_toggle',
+    description: 'Enable or disable a workflow by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id:      { type: 'number',  description: 'Workflow ID' },
+        enabled: { type: 'boolean', description: 'true to enable, false to disable' },
+      },
+      required: ['id', 'enabled'],
+    },
+  },
+
+  // ── Bots / AI Configurations ──────────────────────────────────────────────
+  {
+    name: 'bot_list',
+    description: 'List all bot/AI configurations for this site.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'bot_get',
+    description: 'Get full bot configuration including system prompt.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Bot configuration ID' } },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'bot_update_prompt',
+    description: 'Update a bot\'s system prompt. Use bot_get first to read the current prompt.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id:     { type: 'number', description: 'Bot configuration ID' },
+        prompt: { type: 'string', description: 'New system prompt text' },
+      },
+      required: ['id', 'prompt'],
+    },
+  },
+
+  // ── Contacts ──────────────────────────────────────────────────────────────
+  {
+    name: 'contact_search',
+    description: 'Search contacts by name, email, phone, or company.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        q:     { type: 'string', description: 'Name, email, phone, or company to search' },
+        limit: { type: 'number', description: 'Max results (default 10, max 50)' },
+      },
+      required: ['q'],
+    },
+  },
+  {
+    name: 'contact_get',
+    description: 'Get full contact details by ID.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Contact ID' } },
+      required: ['id'],
+    },
+  },
+
+  // ── Agents ────────────────────────────────────────────────────────────────
+  {
+    name: 'agent_list',
+    description: 'List agents with their status (Available, Busy, Away, Offline). Optionally filter by team.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        teamId: { type: 'number', description: 'Filter by team ID (omit for all agents)' },
+      },
+    },
+  },
+
+  // ── Teams ─────────────────────────────────────────────────────────────────
+  {
+    name: 'team_list',
+    description: 'List all teams for this site.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+
+  // ── Routing Rules ─────────────────────────────────────────────────────────
+  {
+    name: 'routing_list',
+    description: 'List all routing rules ordered by priority.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'routing_get',
+    description: 'Get routing rule details including rule and value JSON.',
+    inputSchema: {
+      type: 'object',
+      properties: { id: { type: 'number', description: 'Routing rule ID' } },
+      required: ['id'],
+    },
+  },
+
+  // ── Site ──────────────────────────────────────────────────────────────────
+  {
+    name: 'site_info',
+    description: 'Get site settings, active channels, subscription features, and counts of agents, teams, bots, and active workflows.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+
+  // ── Live Operations ───────────────────────────────────────────────────────
+  {
+    name: 'kpi_snapshot',
+    description: 'Real-time operations snapshot: agents online/available/busy, open/queued conversations, bot-active count, resolved today, missed/abandoned today, avg and longest queue wait, avg handle time, top agents by resolved count, channel breakdown, and per-team detail (coverage status, agent availability, unassigned conversations). Perfect for a live ops health check.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+
+  // ── CSAT ──────────────────────────────────────────────────────────────────
+  {
+    name: 'csat_summary',
+    description: 'Customer satisfaction (CSAT) report — avg rating, satisfaction rate (% rated 4-5 stars), breakdown by star rating, and up to 10 recent verbatim comments with channel and date. Use to gauge customer happiness and spot qualitative feedback trends.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Lookback window in days (1–365). Default: 30' },
+      },
+    },
+  },
+
+  // ── Bot Diagnostics ───────────────────────────────────────────────────────
+  {
+    name: 'bot_analytics_summary',
+    description: 'AI bot health summary — total AI skill calls, error count, success rate %, top skill name and call count, training conversations indexed. Quick pulse check on bot reliability.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Lookback window in days (1–365). Default: 30' },
+      },
+    },
+  },
+  {
+    name: 'bot_skill_usage',
+    description: 'Per-skill call counts broken down by integration — shows which AI tools are being used, how often, and error counts per integration. Use to identify overused or underused skills and diagnose high-error integrations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Lookback window in days (1–365). Default: 30' },
+      },
+    },
+  },
+  {
+    name: 'bot_recent_errors',
+    description: 'Recent AI skill errors — returns the last N error log entries with integration name, error message, and timestamp. Use to diagnose why a specific integration or skill is failing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days:  { type: 'number', description: 'Lookback window in days (1–90). Default: 7' },
+        limit: { type: 'number', description: 'Max errors to return (1–100). Default: 20' },
+      },
+    },
+  },
+
+  // ── Service Level ─────────────────────────────────────────────────────────
+  {
+    name: 'service_level_report',
+    description: 'SLA / service level report — per-period rows showing conversation volume, % answered within SLA threshold, avg response time, avg handle time. Granularity: hour, day, week, or month.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        startDate:   { type: 'string', description: 'ISO 8601 start date, e.g. 2026-01-01 (default: 30 days ago)' },
+        endDate:     { type: 'string', description: 'ISO 8601 end date, e.g. 2026-04-19 (default: now)' },
+        granularity: { type: 'string', enum: ['hour', 'day', 'week', 'month'], description: 'Bucketing period. Default: day' },
+      },
+    },
+  },
+
+  // ── Reporting ─────────────────────────────────────────────────────────────
+  {
+    name: 'report_roi_summary',
+    description: 'ROI / Value Report — bot deflections, hours saved, estimated cost savings, AI skill executions, resolution rate, avg first-response time, trends vs prior period, monthly breakdown, top skills, channel breakdown. No PII returned.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days:               { type: 'number', description: 'Lookback window in days (1–365). Default: 30' },
+        agentCostPerHour:   { type: 'number', description: 'Agent hourly cost in USD for savings estimate. Default: 25' },
+        avgHandleMinutes:   { type: 'number', description: 'Average handle time per conversation in minutes. Default: 8' },
+      },
+    },
+  },
+  {
+    name: 'report_agent_utilization',
+    description: 'Agent utilization report — per-agent conversation counts, handle times, and availability breakdown for a date range.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        startDate: { type: 'string', description: 'ISO 8601 start date, e.g. 2026-01-01 (default: 30 days ago)' },
+        endDate:   { type: 'string', description: 'ISO 8601 end date, e.g. 2026-04-19 (default: now)' },
+      },
+    },
+  },
+  {
+    name: 'report_campaign_performance',
+    description: 'Email campaign performance: open rate, click rate, delivery rate, complaint rate per campaign + aggregate KPIs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Lookback window in days. Default: 90' },
+      },
+    },
+  },
+  {
+    name: 'report_campaign_deliverability',
+    description: 'Deliverability health check — bounce rate, complaint rate, unsubscribe rate, open rate. Each metric has a traffic-light status (green/yellow/red) and actionable recommendations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Lookback window in days. Default: 30' },
+      },
+    },
+  },
+  {
+    name: 'report_campaign_monthly',
+    description: 'Monthly email volume trend — last 12 months of sent, opened, clicked counts for charting or analysis.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'report_audience_growth',
+    description: 'Audience growth — total active contacts, unsubscribes, net contacts, and month-by-month contact additions for the last 12 months.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+
+  // ── Conversion tracking tools ─────────────────────────────────────────────
+  {
+    name: 'conversion_list_goals',
+    description: 'List all conversion goals for this site. Returns id, name, triggerType, defaultAmount, attributionWindowHours, isEnabled.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'conversion_create_goal',
+    description: 'Create a new conversion goal. Use triggerType="url" for URL-based, "shopify_order"/"square_payment"/"bc_order"/"woo_order" for integration-native, "custom_event" for JS SDK.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Goal name, e.g. "Purchase Completed"' },
+        triggerType: { type: 'string', enum: ['url', 'shopify_order', 'square_payment', 'bc_order', 'woo_order', 'magento_order', 'custom_event'], description: 'What triggers this conversion' },
+        triggerUrl: { type: 'string', description: 'Conversion URL (for triggerType=url)' },
+        eventName: { type: 'string', description: 'Custom event name (for triggerType=custom_event)' },
+        defaultAmount: { type: 'number', description: 'Default revenue amount in USD (default: 0)' },
+        revenueVariableName: { type: 'string', description: 'JS variable name to read actual order amount from' },
+        allowOnce: { type: 'boolean', description: 'Count each visitor only once (default: false)' },
+        attributionWindowHours: { type: 'number', description: 'Hours after chat to attribute conversion: 1, 24, 168 (7d), 720 (30d). Default: 24' },
+      },
+      required: ['name', 'triggerType'],
+    },
+  },
+  {
+    name: 'conversion_get_report',
+    description: 'Get conversion attribution report: total revenue, attributed revenue, attribution rate, conversions by goal, timeline. Shows how chat drives sales.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days: { type: 'number', description: 'Lookback window in days (7, 30, or 90). Default: 30' },
+      },
+    },
+  },
 ];
 
 // ── Tool handlers ─────────────────────────────────────────────────────────────
@@ -237,6 +579,329 @@ async function handleTool(name, args) {
       return `Article ${args.id} deleted.`;
     }
 
+    // ── Conversations ──────────────────────────────────────────────────────
+    case 'conversation_list':
+      return await rpc('conversation_list', args);
+
+    case 'conversation_get':
+      return await rpc('conversation_get', args);
+
+    case 'conversation_search':
+      return await rpc('conversation_search', args);
+
+    // ── Workflows ──────────────────────────────────────────────────────────
+    case 'workflow_list':
+      return await rpc('workflow_list', args);
+
+    case 'workflow_get':
+      return await rpc('workflow_get', args);
+
+    case 'workflow_toggle':
+      return await rpc('workflow_toggle', args);
+
+    // ── Bots / AI Configurations ───────────────────────────────────────────
+    case 'bot_list':
+      return await rpc('bot_list', args);
+
+    case 'bot_get':
+      return await rpc('bot_get', args);
+
+    case 'bot_update_prompt':
+      return await rpc('bot_update_prompt', args);
+
+    // ── Contacts ───────────────────────────────────────────────────────────
+    case 'contact_search':
+      return await rpc('contact_search', args);
+
+    case 'contact_get':
+      return await rpc('contact_get', args);
+
+    // ── Agents ─────────────────────────────────────────────────────────────
+    case 'agent_list':
+      return await rpc('agent_list', args);
+
+    // ── Teams ──────────────────────────────────────────────────────────────
+    case 'team_list':
+      return await rpc('team_list', args);
+
+    // ── Routing Rules ──────────────────────────────────────────────────────
+    case 'routing_list':
+      return await rpc('routing_list', args);
+
+    case 'routing_get':
+      return await rpc('routing_get', args);
+
+    // ── Site ───────────────────────────────────────────────────────────────
+    case 'site_info':
+      return await rpc('site_info', args);
+
+    case 'conversion_list_goals': {
+      const goals = await api('GET', '/Conversions/goals');
+      if (!Array.isArray(goals) || !goals.length) return 'No conversion goals configured.';
+      return goals.map(g =>
+        `[${g.id}] "${g.name}" | type: ${g.triggerType} | window: ${g.attributionWindowHours}h | default: $${g.defaultAmount} | ${g.isEnabled ? 'enabled' : 'paused'}`
+      ).join('\n');
+    }
+
+    case 'conversion_create_goal': {
+      const res = await api('POST', '/Conversions/goals', {
+        name:                  args.name,
+        triggerType:           args.triggerType,
+        triggerUrl:            args.triggerUrl || null,
+        eventName:             args.eventName || null,
+        defaultAmount:         args.defaultAmount ?? 0,
+        revenueVariableName:   args.revenueVariableName || null,
+        allowOnce:             args.allowOnce ?? false,
+        attributionWindowHours: args.attributionWindowHours ?? 24,
+        isEnabled:             true,
+      });
+      return `Created conversion goal "${args.name}" with ID ${res.id}.`;
+    }
+
+    case 'conversion_get_report': {
+      const days = args.days ?? 30;
+      const r = await api('GET', `/Conversions/report?days=${days}`);
+      if (!r.hasData) {
+        return `No conversion data in the last ${days} days. ${r.goalCount} goal(s) configured — events will appear once the widget fires.`;
+      }
+      const s = r.summary;
+      const lines = [
+        `=== Conversion Attribution (last ${days} days) ===`,
+        `Attributed Revenue: $${s.attributedRevenue.toFixed(2)} of $${s.totalRevenue.toFixed(2)} total`,
+        `Attribution Rate: ${(s.attributionRate * 100).toFixed(1)}% (${s.attributedConversions} of ${s.totalConversions} conversions had a recent chat)`,
+        `Avg Order Value: $${s.avgOrderValue.toFixed(2)}`,
+        '',
+        '--- By Goal ---',
+        ...r.byGoal.map(g =>
+          `  ${g.goalName}: ${g.conversions} conversions, $${g.revenue.toFixed(2)} revenue, ${(g.attributionRate * 100).toFixed(1)}% attributed`
+        ),
+      ];
+      return lines.join('\n');
+    }
+
+    // ── Live Operations ───────────────────────────────────────────────────
+    case 'kpi_snapshot': {
+      const r = await api('GET', '/LiveDashboard/snapshot');
+      const k = r.kpis ?? {};
+      const lines = [
+        '=== Live Operations Snapshot ===',
+        `Agents: ${k.agentsAvailable} available, ${k.agentsBusy} busy, ${k.agentsOnline} online`,
+        `Conversations: ${k.openConversations} open | ${k.queuedConversations} queued | ${k.botActive} bot-active`,
+        `Today: ${k.resolvedToday} resolved | ${k.missedAbandonedToday} missed/abandoned`,
+        `Queue Wait: avg ${k.avgWaitMinutes}m | longest ${k.longestWaitMinutes}m`,
+        `Avg Handle Time: ${k.avgHandleTimeMinutes}m | Avg First Response: ${k.avgFirstResponseMinutes}m`,
+        '',
+        '--- Top Agents (resolved today) ---',
+        ...(r.topAgents?.length
+          ? r.topAgents.map(a => `  ${a.name}: ${a.resolved} resolved, ${a.active} active`)
+          : ['  (no data yet today)']),
+        '',
+        '--- By Channel ---',
+        ...(r.channelBreakdown?.length
+          ? r.channelBreakdown.map(c => `  ${c.channel}: ${c.count} open, ${c.queued} queued`)
+          : ['  (no data)']),
+        '',
+        '--- By Team ---',
+        ...(r.teams?.length
+          ? r.teams.map(t =>
+              `  ${t.teamName}: ${t.agentsAvailable}/${t.agentsOnline} available | ${t.openConversations} open | ${t.unassignedConversations} unassigned | wait avg ${t.avgWaitMinutes}m | ${t.coverageStatus}`
+            )
+          : ['  (no teams)']),
+      ];
+      return lines.join('\n');
+    }
+
+    // ── CSAT ──────────────────────────────────────────────────────────────
+    case 'csat_summary': {
+      const days = args.days ?? 30;
+      const r = await api('GET', `/api/admin/Csat/Summary?days=${days}`);
+      if (!r.totalResponses) return `No CSAT responses in the last ${days} days.`;
+      const lines = [
+        `=== CSAT Summary (last ${days} days) ===`,
+        `Responses: ${r.totalResponses}  |  Avg Rating: ${r.averageRating}/5  |  Satisfaction Rate: ${r.satisfactionRate}%`,
+        '',
+        '--- Rating Breakdown ---',
+        ...(r.breakdown?.map(b => `  ${b.rating}★: ${b.count}`) ?? []),
+        '',
+        '--- Recent Comments ---',
+        ...(r.recentComments?.length
+          ? r.recentComments.map(c => `  [${c.Rating}★] ${c.Channel ?? 'web'} — "${c.Comment}"`)
+          : ['  (no comments)']),
+      ];
+      return lines.join('\n');
+    }
+
+    // ── Bot Diagnostics ───────────────────────────────────────────────────
+    case 'bot_analytics_summary': {
+      const days = args.days ?? 30;
+      const r = await api('GET', `/BotAnalytics/Summary?days=${days}`);
+      return [
+        `=== Bot Analytics (last ${days} days) ===`,
+        `AI Skill Calls: ${r.totalSkillCalls}  |  Errors: ${r.errorCount}  |  Success Rate: ${r.successRate}%`,
+        `Top Skill: ${r.topSkill} (${r.topSkillCount} calls)`,
+        `Conversations Trained: ${r.conversationsTrainedCount}`,
+      ].join('\n');
+    }
+
+    case 'bot_skill_usage': {
+      const days = args.days ?? 30;
+      const r = await api('GET', `/BotAnalytics/SkillUsage?days=${days}`);
+      const lines = [
+        `=== Bot Skill Usage (last ${days} days) ===`,
+        `Total Successful Calls: ${r.totalSuccessfulCalls}  |  Total Errors: ${r.totalErrors}`,
+        '',
+        '--- Skill Calls ---',
+        ...(r.skillUsage?.length
+          ? r.skillUsage.slice(0, 30).map(s => `  [${s.integration}] ${s.toolName}: ${s.count}`)
+          : ['  (no data)']),
+        '',
+        '--- Errors by Integration ---',
+        ...(r.errorsByIntegration?.length
+          ? r.errorsByIntegration.map(e => `  ${e.integration}: ${e.errorCount} errors`)
+          : ['  (none)']),
+      ];
+      return lines.join('\n');
+    }
+
+    case 'bot_recent_errors': {
+      const days = args.days ?? 7;
+      const limit = args.limit ?? 20;
+      const errors = await api('GET', `/BotAnalytics/RecentErrors?days=${days}&limit=${limit}`);
+      if (!Array.isArray(errors) || !errors.length) return `No AI skill errors in the last ${days} days.`;
+      const lines = [
+        `=== Recent Bot Errors (last ${days} days, up to ${limit}) ===`,
+        ...errors.map(e => `  [${e.integration ?? 'unknown'}] ${new Date(e.createdAt).toISOString().slice(0, 16)} — ${e.message ?? e.errorMessage ?? JSON.stringify(e)}`),
+      ];
+      return lines.join('\n');
+    }
+
+    // ── Service Level ─────────────────────────────────────────────────────
+    case 'service_level_report': {
+      const qs = [
+        args.startDate   ? `startDate=${args.startDate}`     : '',
+        args.endDate     ? `endDate=${args.endDate}`         : '',
+        args.granularity ? `granularity=${args.granularity}` : '',
+      ].filter(Boolean).join('&');
+      const r = await api('GET', `/ServiceLevel${qs ? '?' + qs : ''}`);
+      const rows = r.rows ?? r;
+      if (!Array.isArray(rows) || !rows.length) return 'No service level data for this period.';
+      const lines = [
+        `=== Service Level Report ===`,
+        ...rows.map(row =>
+          `  ${row.period ?? row.label ?? row.date}: ${row.totalConversations ?? row.total ?? 0} convos | SLA ${row.slaPercent ?? row.withinSla ?? 0}% | avg response ${row.avgResponseSecs ?? row.avgFirstResponseSecs ?? 0}s | avg handle ${row.avgHandleTimeSecs ?? row.avgHandleSecs ?? 0}s`
+        ),
+      ];
+      return lines.join('\n');
+    }
+
+    // ── Reporting ─────────────────────────────────────────────────────────
+    case 'report_roi_summary': {
+      const days = args.days ?? 30;
+      const cost = args.agentCostPerHour ?? 25;
+      const handle = args.avgHandleMinutes ?? 8;
+      const r = await api('GET', `/RoiReport/Summary?days=${days}&agentCostPerHour=${cost}&avgHandleMinutes=${handle}`);
+      const h = r.headline;
+      const t = r.trends;
+      const lines = [
+        `=== ROI Summary (last ${days} days) ===`,
+        `Total Conversations: ${h.totalConversations}  (${t.conversationVolumeChange > 0 ? '+' : ''}${t.conversationVolumeChange}% vs prior period)`,
+        `Bot Deflections: ${h.botDeflections} (${h.deflectionRate}%  ${t.deflectionRateChange > 0 ? '▲' : '▼'}${Math.abs(t.deflectionRateChange)}% vs prior)`,
+        `Human-Handled: ${h.humanHandledConversations}`,
+        `Hours Saved: ${h.hoursSaved}  |  Estimated Savings: $${h.estimatedSavings}`,
+        `AI Skill Executions: ${h.aiSkillExecutions}`,
+        `Resolution Rate: ${h.resolutionRate}%  (${t.resolutionRateChange > 0 ? '+' : ''}${t.resolutionRateChange}% vs prior)`,
+        `Avg First Response: ${Math.round(h.avgFirstResponseSecs)}s`,
+        '',
+        '--- Top AI Skills ---',
+        ...(r.topSkills?.length ? r.topSkills.map(s => `  ${s.skill}: ${s.calls} calls`) : ['  (no data)']),
+        '',
+        '--- By Channel ---',
+        ...(r.channelBreakdown?.length ? r.channelBreakdown.map(c => `  ${c.channel}: ${c.conversations} convos, ${c.deflectionPct}% bot-deflected`) : ['  (no data)']),
+        '',
+        '--- Monthly Trend (last 6 months) ---',
+        ...(r.monthlyBreakdown?.length ? r.monthlyBreakdown.map(m =>
+          `  ${m.label}: ${m.total} total, ${m.botHandled} bot-handled (${m.deflectionRate}%), ${m.resolved} resolved, avg response ${m.avgResponseSecs}s`
+        ) : ['  (no data)']),
+      ];
+      return lines.join('\n');
+    }
+
+    case 'report_agent_utilization': {
+      const qs = [
+        args.startDate ? `startDate=${args.startDate}` : '',
+        args.endDate   ? `endDate=${args.endDate}`     : '',
+      ].filter(Boolean).join('&');
+      const rows = await api('GET', `/Reports/AgentUtilization${qs ? '?' + qs : ''}`);
+      if (!Array.isArray(rows) || !rows.length) return 'No agent utilization data for this period.';
+      const lines = [
+        `=== Agent Utilization (${rows.length} agents) ===`,
+        ...rows.map(a =>
+          `  ${a.agentName} — ${a.totalConversations} convos | avg handle: ${a.avgHandleTimeSecs}s | active: ${a.activePercent}% | away: ${a.awayPercent}%`
+        ),
+      ];
+      return lines.join('\n');
+    }
+
+    case 'report_campaign_performance': {
+      const days = args.days ?? 90;
+      const r = await api('GET', `/CampaignReports/Performance?days=${days}`);
+      const s = r.summary ?? {};
+      const lines = [
+        `=== Campaign Performance (last ${days} days, ${s.campaignCount ?? 0} campaigns) ===`,
+        `Total Sent: ${s.totalSent ?? 0}  |  Opens: ${s.totalOpened ?? 0} (${s.avgOpenRate ?? 0}%)  |  Clicks: ${s.totalClicked ?? 0} (${s.avgClickRate ?? 0}%)`,
+        '',
+        '--- Per Campaign ---',
+        ...(Array.isArray(r.campaigns) && r.campaigns.length
+          ? r.campaigns.map(c =>
+              `  [${c.Id}] "${c.Name}" (${c.Channel}) ${c.SentAt?.slice(0, 10)} — sent ${c.SentCount}, open ${c.openRate}%, click ${c.clickRate}%, bounce ${c.bounceRate ?? 0}%`
+            )
+          : ['  (no campaigns sent in this window)']),
+      ];
+      return lines.join('\n');
+    }
+
+    case 'report_campaign_deliverability': {
+      const days = args.days ?? 30;
+      const r = await api('GET', `/CampaignReports/Deliverability?days=${days}`);
+      const lines = [
+        `=== Deliverability Health (${r.period}) ===`,
+        `Total Sent: ${r.totalSent}`,
+        `Delivery Rate: ${r.deliveryRate}% [${r.deliveryStatus?.toUpperCase()}]`,
+        `Bounce Rate: ${r.bounceRate}% [${r.bounceStatus?.toUpperCase()}]  (hard: ${r.totalHardBounce}, soft: ${r.totalSoftBounce})`,
+        `Complaint Rate: ${r.complaintRate}% [${r.complaintStatus?.toUpperCase()}]`,
+        `Unsubscribe Rate: ${r.unsubRate}% [${r.unsubStatus?.toUpperCase()}]  (${r.unsubCount} unsubs)`,
+        `Open Rate: ${r.openRate}% [${r.openStatus?.toUpperCase()}]`,
+        '',
+        '--- Recommendations ---',
+        ...(r.recommendations?.length ? r.recommendations.map(rec => `  • ${rec}`) : ['  All metrics healthy.']),
+      ];
+      return lines.join('\n');
+    }
+
+    case 'report_campaign_monthly': {
+      const rows = await api('GET', '/CampaignReports/Monthly');
+      if (!Array.isArray(rows) || !rows.length) return 'No monthly campaign data (no sent campaigns in the last 12 months).';
+      const lines = [
+        '=== Monthly Email Volume (last 12 months) ===',
+        ...rows.map(m => `  ${m.month}: sent ${m.sent}, opened ${m.opened}, clicked ${m.clicked}`),
+      ];
+      return lines.join('\n');
+    }
+
+    case 'report_audience_growth': {
+      const r = await api('GET', '/CampaignReports/AudienceGrowth');
+      const lines = [
+        `=== Audience Growth ===`,
+        `Total Active Contacts: ${r.totalContacts}  |  Unsubscribed: ${r.unsubTotal}  |  Net: ${r.netContacts}`,
+        '',
+        '--- Monthly Additions (last 12 months) ---',
+        ...(r.monthly?.length
+          ? r.monthly.map(m => `  ${m.month}: +${m.added} contacts`)
+          : ['  (no data)']),
+      ];
+      return lines.join('\n');
+    }
+
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
@@ -245,7 +910,7 @@ async function handleTool(name, args) {
 // ── Server setup ──────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'velaro', version: '0.1.0' },
+  { name: 'velaro', version: '0.4.0' },
   { capabilities: { tools: {} } }
 );