@mohammad_noman/saleem-dashboard-mcp 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# Saleem Dashboard MCP Server
+
+This MCP server wraps the Saleem internal dashboard API routes as tools, so Claude can query live data and trigger agents directly from a conversation.
+
+## Team goal
+
+Use this MCP server from Claude Desktop without cloning this repository or using machine-specific paths.
+
+## What it does
+
+Exposes 8 tools to Claude:
+
+| Tool | Description |
+|---|---|
+| `get_pipeline_health` | Deals exceeding SLA thresholds, sorted by days stalled |
+| `get_funnel_data` | Mixpanel consultation funnel conversion rates (last 30 days) |
+| `get_kpi_status` | All team KPIs with on_track / at_risk / behind status |
+| `get_urgent_items` | Unresolved urgent items, filterable by owner / priority |
+| `get_deal_priorities` | Fatima's morning list: new leads, at-risk deals, today's follow-ups |
+| `get_weekly_brief` | Latest compiled weekly brief from all agents |
+| `run_agent` | Trigger a diagnostic agent and return its output |
+| `create_urgent_item` | Create a new urgent item visible on the team dashboard |
+
+## Running locally
+
+```bash
+cd mcp
+npm install
+node saleem-dashboard-mcp.js
+```
+
+You should see:
+```
+[mcp] Saleem Dashboard MCP server running
+```
+
+## Publish once, run anywhere
+
+This package is configured as a public scoped package under your npm username, so teammates can install it through `npx` without private-package billing.
+
+### 1) Rotate and set the service key
+
+1. Generate a new `MCP_SERVICE_KEY`.
+2. Set that key in Vercel project environment variables (Production and Preview).
+3. Share the key only through your team secret manager.
+
+### 2) Publish the MCP package
+
+```bash
+cd mcp
+npm login
+npm publish --access public
+```
+
+If you later decide to move to a private registry, the same package structure still works; only the publish command and teammate auth change.
+
+### 3) Add the server in Claude Desktop (team config)
+
+Open Claude Desktop config:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`
+
+Use this block:
+
+```json
+{
+  "mcpServers": {
+    "saleem-dashboard": {
+      "command": "npx",
+      "args": ["-y", "@mohammad_noman/saleem-dashboard-mcp@1.0.0"],
+      "env": {
+        "DASHBOARD_BASE_URL": "https://analytics-dashboard-five-gamma.vercel.app",
+        "MCP_SERVICE_KEY": "YOUR_ROTATED_KEY"
+      }
+    }
+  }
+}
+```
+
+Notes:
+
+- Pin the package version in `args` for stable behavior.
+- Bump version and update the pinned version when releasing updates.
+
+## Adding to Claude Desktop
+
+Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:
+
+```json
+{
+  "mcpServers": {
+    "saleem-dashboard": {
+      "command": "npx",
+      "args": ["-y", "@mohammad_noman/saleem-dashboard-mcp@1.0.0"],
+      "env": {
+        "DASHBOARD_BASE_URL": "https://analytics-dashboard-five-gamma.vercel.app",
+        "MCP_SERVICE_KEY": "YOUR_ROTATED_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving. You should see "saleem-dashboard" appear in the tools panel.
+
+## Verifying it works
+
+Run the smoke test (reads from the live dashboard):
+
+```bash
+node mcp/test.js
+```
+
+This calls `get_pipeline_health`, `get_kpi_status`, and `get_urgent_items` directly and prints the results.
+
+## Required environment variables
+
+| Variable | Where | Description |
+|---|---|---|
+| `DASHBOARD_BASE_URL` | MCP server env | Base URL of the deployed dashboard |
+| `MCP_SERVICE_KEY` | MCP server env **and** Vercel env | Shared secret — must match on both sides |
+
+Set `MCP_SERVICE_KEY` as a Vercel environment variable (Production + Preview) so the deployed API routes accept requests from the MCP server.
+
+## Release checklist
+
+1. Update code in this folder.
+2. Bump version in `mcp/package.json`.
+3. Run `npm pack --dry-run` from `mcp`.
+4. Publish with `npm publish --access public`.
+5. Share the new pinned version string with the team.
+
+## How authentication works
+
+The MCP server sends `x-mcp-key: <MCP_SERVICE_KEY>` on every request. API routes that normally require a session cookie check for this header first — if it matches, the session check is skipped and the request is treated as a `ceo`-role caller. The key is never exposed to the browser.

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mohammad_noman/saleem-dashboard-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Saleem dashboard tools",
+  "type": "module",
+  "main": "saleem-dashboard-mcp.js",
+  "bin": {
+    "saleem-dashboard-mcp": "saleem-dashboard-mcp.js"
+  },
+  "files": [
+    "saleem-dashboard-mcp.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node saleem-dashboard-mcp.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest"
+  }
+}

package/saleem-dashboard-mcp.js

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+// Saleem Dashboard MCP Server
+// Wraps internal dashboard API routes as MCP tools so Claude can query
+// live data and trigger agents directly from a conversation.
+//
+// Required env vars:
+//   DASHBOARD_BASE_URL  — e.g. https://analytics-dashboard-five-gamma.vercel.app
+//   MCP_SERVICE_KEY     — must match the value set in the dashboard's env
+
+import { Server }            from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js'
+
+const BASE_URL    = (process.env.DASHBOARD_BASE_URL || '').replace(/\/$/, '')
+const SERVICE_KEY = process.env.MCP_SERVICE_KEY || ''
+
+if (!BASE_URL)    console.error('[mcp] WARNING: DASHBOARD_BASE_URL is not set')
+if (!SERVICE_KEY) console.error('[mcp] WARNING: MCP_SERVICE_KEY is not set')
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+async function dashFetch(path, { method = 'GET', body } = {}) {
+  const url = `${BASE_URL}${path}`
+  const opts = {
+    method,
+    headers: {
+      'x-mcp-key': SERVICE_KEY,
+      'Content-Type': 'application/json',
+    },
+  }
+  if (body !== undefined) opts.body = JSON.stringify(body)
+  const res = await fetch(url, opts)
+  return res.json()
+}
+
+// ---------------------------------------------------------------------------
+// SLA config — mirrors agents/pipeline-health.js
+// ---------------------------------------------------------------------------
+
+const PIPELINE_CONFIG = {
+  'Telemedicine':       { won: 'TeleConsult Completed', lost: 'Lost / Inactive' },
+  'Treatment':          { won: 'Treatment Completed',   lost: 'Lost / Inactive' },
+  'Doctor':             { won: 'Live Doctor',            lost: 'Lost Doctor'     },
+  'Hospital or Clinic': { won: 'Live Partner B2B',      lost: 'Lost provider'   },
+  'Corporates':         { won: 'Live',                   lost: 'Lost Corporates' },
+}
+
+const SLA_DAYS = {
+  'New Deal':               2,
+  'Quote Proposed':         3,
+  'Payment Done':           1,
+  'Consultation Scheduled': 2,
+  'Consult Payment':        1,
+  'Treatment Quote':        5,
+  'Treatment Payment':      3,
+  'Treatment Scheduled':    7,
+  'Treatment in Progress': 14,
+  'Discovery':              5,
+  'Outreach':               3,
+  'Interest':               5,
+  'Agreement':              7,
+  'Readiness':              5,
+  'Contract Sent':          7,
+}
+
+// ---------------------------------------------------------------------------
+// Tool implementations
+// ---------------------------------------------------------------------------
+
+async function getPipelineHealth() {
+  const data = await dashFetch('/api/zoho/crm/deals')
+  if (!data.success) throw new Error(data.error || 'Failed to fetch deals')
+
+  const now   = Date.now()
+  const stalled = []
+
+  for (const deal of data.deals) {
+    const cfg = PIPELINE_CONFIG[deal.pipeline]
+    if (!cfg) continue
+    if (deal.stage === cfg.won || deal.stage === cfg.lost) continue
+
+    const sla = SLA_DAYS[deal.stage]
+    if (sla === undefined) continue
+
+    const daysSince = Math.floor((now - new Date(deal.modified).getTime()) / 86_400_000)
+    if (daysSince > sla) {
+      stalled.push({
+        deal_name:    deal.name,
+        pipeline:     deal.pipeline,
+        stage:        deal.stage,
+        days_stalled: daysSince,
+        sla_days:     sla,
+        owner:        deal.contact || 'Unknown',
+      })
+    }
+  }
+
+  stalled.sort((a, b) => b.days_stalled - a.days_stalled)
+  return { stalled_deals: stalled, total_breaches: stalled.length }
+}
+
+async function getFunnelData() {
+  const data = await dashFetch('/api/mixpanel/funnels')
+  if (!data.success) {
+    if (data.error === 'MIXPANEL_NOT_CONFIGURED') {
+      return { error: 'Mixpanel is not configured on this dashboard instance.' }
+    }
+    throw new Error(data.error || 'Failed to fetch funnel data')
+  }
+  return {
+    steps:                  data.steps,
+    overall_conversion:     data.overall_conversion,
+    biggest_drop_off_step:  data.biggest_drop_off_step,
+    period:                 data.period,
+  }
+}
+
+async function getKpiStatus({ person } = {}) {
+  const period = new Date().toISOString().slice(0, 7)
+  const data   = await dashFetch(`/api/kpi/targets?period=${period}`)
+  if (!data.success) throw new Error(data.error || 'Failed to fetch KPI targets')
+
+  let targets = data.targets || []
+  if (person) {
+    targets = targets.filter(t => t.person?.toLowerCase() === person.toLowerCase())
+  }
+
+  const withStatus = targets.map(t => {
+    const pct    = t.target_value > 0 ? (t.current_value / t.target_value) * 100 : 0
+    const status = pct >= 80 ? 'on_track' : pct >= 50 ? 'at_risk' : 'behind'
+    return {
+      person:        t.person,
+      metric:        t.metric,
+      current_value: t.current_value ?? null,
+      target_value:  t.target_value,
+      pct_complete:  +pct.toFixed(1),
+      status,
+      period:        t.period,
+    }
+  })
+
+  const summary = {
+    on_track: withStatus.filter(k => k.status === 'on_track').length,
+    at_risk:  withStatus.filter(k => k.status === 'at_risk').length,
+    behind:   withStatus.filter(k => k.status === 'behind').length,
+  }
+
+  return { kpis: withStatus, summary, period }
+}
+
+async function getUrgentItems({ owner, priority } = {}) {
+  const data = await dashFetch('/api/urgent')
+  if (!data.success) throw new Error(data.error || 'Failed to fetch urgent items')
+
+  let items = data.items || []
+  if (owner)    items = items.filter(i => i.owner?.toLowerCase() === owner.toLowerCase())
+  if (priority) items = items.filter(i => i.priority === priority)
+
+  return { items, total: items.length }
+}
+
+async function getDealPriorities() {
+  const data = await dashFetch('/api/zoho/crm/deals')
+  if (!data.success) throw new Error(data.error || 'Failed to fetch deals')
+
+  const today = new Date().toISOString().slice(0, 10)
+  const now   = Date.now()
+
+  const newLeads = []
+  const atRisk   = []
+  const followUps = []
+
+  for (const deal of data.deals) {
+    const cfg = PIPELINE_CONFIG[deal.pipeline]
+    const isTerminal = cfg && (deal.stage === cfg.won || deal.stage === cfg.lost)
+    if (isTerminal) continue
+
+    if (deal.stage === 'New Deal') {
+      newLeads.push({
+        name:     deal.name,
+        pipeline: deal.pipeline,
+        created:  deal.created,
+        owner:    deal.contact,
+      })
+    }
+
+    const daysSinceMod = Math.floor((now - new Date(deal.modified).getTime()) / 86_400_000)
+    if (daysSinceMod >= 3) {
+      atRisk.push({
+        name:          deal.name,
+        pipeline:      deal.pipeline,
+        stage:         deal.stage,
+        days_inactive: daysSinceMod,
+        owner:         deal.contact,
+      })
+    }
+
+    if (deal.follow_up && deal.follow_up <= today) {
+      followUps.push({
+        name:      deal.name,
+        pipeline:  deal.pipeline,
+        stage:     deal.stage,
+        follow_up: deal.follow_up,
+        owner:     deal.contact,
+      })
+    }
+  }
+
+  newLeads.sort((a, b) => new Date(a.created) - new Date(b.created))
+  atRisk.sort((a, b) => b.days_inactive - a.days_inactive)
+  followUps.sort((a, b) => a.follow_up.localeCompare(b.follow_up))
+
+  return {
+    new_leads:  newLeads,
+    at_risk:    atRisk,
+    follow_ups: followUps,
+    counts: {
+      new_leads:  newLeads.length,
+      at_risk:    atRisk.length,
+      follow_ups: followUps.length,
+    },
+  }
+}
+
+async function getWeeklyBrief() {
+  const data = await dashFetch('/api/agents/brief')
+  if (!data.success) throw new Error(data.error || 'Failed to fetch weekly brief')
+  return { brief: data.brief }
+}
+
+const AGENT_ROUTES = {
+  'pipeline-health':       '/api/agents/pipeline-health/run',
+  'funnel-diagnostic':     '/api/agents/funnel-diagnostic/run',
+  'task-tracker':          '/api/agents/task-tracker/run',
+  'department-bottleneck': '/api/agents/department-bottleneck/run',
+  'follow-up-generator':   '/api/agents/follow-up-generator/run',
+  'lead-source-attribution': '/api/agents/lead-source-attribution/run',
+  'weekly-brief-compiler': '/api/agents/weekly-brief-compiler/run',
+  'provider-list-builder': '/api/agents/provider-list-builder/run',
+  'corporate-list-builder': '/api/agents/corporate-list-builder/run',
+}
+
+async function runAgent({ agent_name }) {
+  const route = AGENT_ROUTES[agent_name]
+  if (!route) {
+    const valid = Object.keys(AGENT_ROUTES).join(', ')
+    throw new Error(`Unknown agent "${agent_name}". Valid agents: ${valid}`)
+  }
+  const data = await dashFetch(route)
+  if (data.error && !data.success) throw new Error(data.error)
+  return data
+}
+
+async function createUrgentItem({ title, description, owner, priority, due_date }) {
+  if (!title?.trim())  throw new Error('title is required')
+  if (!owner?.trim())  throw new Error('owner is required')
+  if (!priority)       throw new Error('priority is required')
+
+  const VALID_PRIORITIES = ['critical', 'high', 'medium', 'low']
+  if (!VALID_PRIORITIES.includes(priority)) {
+    throw new Error(`priority must be one of: ${VALID_PRIORITIES.join(', ')}`)
+  }
+
+  const data = await dashFetch('/api/urgent', {
+    method: 'POST',
+    body: {
+      title:       title.trim(),
+      description: description?.trim() || null,
+      owner:       owner.trim(),
+      priority,
+      due_at:      due_date || null,
+    },
+  })
+
+  if (!data.success) throw new Error(data.error || 'Failed to create urgent item')
+  return { created: true, item: data.item }
+}
+
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: 'get_pipeline_health',
+    description: 'Get all deals currently exceeding SLA thresholds. Returns stalled deals by pipeline with days stalled and owner.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'get_funnel_data',
+    description: 'Get the current Mixpanel consultation funnel conversion rates for the last 30 days.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'get_kpi_status',
+    description: 'Get all team KPI targets and their current values for the current month. Shows who is on track and who is behind.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        person: {
+          type: 'string',
+          description: 'Filter to one person\'s KPIs (optional)',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_urgent_items',
+    description: 'Get all unresolved urgent items across the team. Optionally filter by owner or priority.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        owner: {
+          type: 'string',
+          description: 'Filter to one person (optional)',
+        },
+        priority: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Filter to a specific priority level (optional)',
+        },
+      },
+    },
+  },
+  {
+    name: 'get_deal_priorities',
+    description: "Get Fatima's morning priority list: new unresponded leads, at-risk deals with 3+ days no activity, and follow-ups due today.",
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'get_weekly_brief',
+    description: 'Get the latest compiled weekly brief showing summaries from all agents that ran this week.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+  },
+  {
+    name: 'run_agent',
+    description: 'Trigger a specific diagnostic agent to run now and return its output. Only use when fresh data is needed.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agent_name: {
+          type: 'string',
+          enum: Object.keys(AGENT_ROUTES),
+          description: 'The agent to run',
+        },
+      },
+      required: ['agent_name'],
+    },
+  },
+  {
+    name: 'create_urgent_item',
+    description: 'Create a new urgent item visible on the team dashboard. Use when something needs immediate attention from a specific person.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: {
+          type: 'string',
+          description: 'Short title for the urgent item',
+        },
+        description: {
+          type: 'string',
+          description: 'Longer description (optional)',
+        },
+        owner: {
+          type: 'string',
+          description: 'Team member name who owns this item',
+        },
+        priority: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Urgency level',
+        },
+        due_date: {
+          type: 'string',
+          description: 'ISO date string e.g. 2026-04-25 (optional)',
+        },
+      },
+      required: ['title', 'owner', 'priority'],
+    },
+  },
+]
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+async function dispatch(name, args) {
+  switch (name) {
+    case 'get_pipeline_health': return getPipelineHealth()
+    case 'get_funnel_data':     return getFunnelData()
+    case 'get_kpi_status':      return getKpiStatus(args)
+    case 'get_urgent_items':    return getUrgentItems(args)
+    case 'get_deal_priorities': return getDealPriorities()
+    case 'get_weekly_brief':    return getWeeklyBrief()
+    case 'run_agent':           return runAgent(args)
+    case 'create_urgent_item':  return createUrgentItem(args)
+    default: throw new Error(`Unknown tool: ${name}`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+
+const server = new Server(
+  { name: 'saleem-dashboard', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params
+  try {
+    const result = await dispatch(name, args || {})
+    return {
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    }
+  } catch (err) {
+    return {
+      content: [{ type: 'text', text: `Error: ${err.message}` }],
+      isError: true,
+    }
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
+console.error('[mcp] Saleem Dashboard MCP server running')