@calltelemetry/ct-ai-mcp

@calltelemetry/ct-ai-mcp

MCP (Model Context Protocol) server for Cisco Collaboration Analytics. Connects AI assistants like Claude Desktop, Cursor, and Windsurf to CallTelemetry's telecom analytics engine.

What It Does

This server exposes 18 AI-powered tools (per schemas/manifest.json, sourced from GET /api/org/:org_id/ai/manifest) that let LLMs query and analyze Cisco Unified Communications data:

Domain	Tools	Examples
Call Records	explain_call, explain_error, explain_routing, search_calls	"Why did the call to 5559876 fail?"
Devices	analyze_device, cube_overview	"Show quality metrics for SEP001122334455"
Policy	investigate_policy, test_rule, review_violations	"Would rule R-100 block calls to 900 numbers?"
Reporting	list_reports, get_report_schema, run_report	"Top 10 phones by call volume this week"
Contacts	resolve_contact	"Who owns extension 4567?"
Activity	summarize_activity	"Summarize today's call activity by site"
Analytics	analyze_trends	"Show call volume trend for last 7 days"
Diagnostics	correlate_root_cause	"Why are calls to this number failing?"
Config Audit	config_audit	"Audit CUCM config drift for this cluster"
Infrastructure	query_syslog	"Search syslog for CUBE registration failures"

Quick Start

1. Build

yarn install
yarn build

2. Configure

Set environment variables for your CallTelemetry instance:

export CT_HOST=https://your-calltelemetry.example.com
export CT_API_KEY=ct_api_your_key_here
export CT_ORG_ID=1                    # Optional, defaults to "1"
export CT_TLS_VERIFY=true             # Optional, defaults to true

3. Connect to Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ct-analytics": {
      "command": "node",
      "args": ["/path/to/ct-analytics-mcp/build/index.js"],
      "env": {
        "CT_HOST": "https://your-calltelemetry.example.com",
        "CT_API_KEY": "ct_api_your_key_here"
      }
    }
  }
}

4. Connect to Cursor / Windsurf

Add to .cursor/mcp.json or equivalent:

{
  "mcpServers": {
    "ct-analytics": {
      "command": "node",
      "args": ["/path/to/ct-analytics-mcp/build/index.js"],
      "env": {
        "CT_HOST": "https://your-calltelemetry.example.com",
        "CT_API_KEY": "ct_api_your_key_here"
      }
    }
  }
}

Development

yarn install          # Install dependencies
yarn fetch-manifest   # Fetch GET /ai/manifest from a backend (needs CT_HOST/CT_API_KEY)
yarn codegen          # Generate tool definitions from schemas/manifest.json
yarn typecheck        # TypeScript type checking
yarn test             # Run all tests (vitest)
yarn build            # Production build (vite)
yarn smoke-test       # Verify built bundle starts
yarn validate         # typecheck + test

Schema Codegen Pipeline

Tool definitions are auto-generated from the Elixir backend's effective capability manifest — not hand-maintained.

cisco-cdr (Elixir)                        ct-ai-mcp (TypeScript)
┌────────────────────────────┐            ┌──────────────────────────┐
│ GET /api/org/:id/ai/manifest│ ─JSON────▶│ schemas/manifest.json     │
│ (API-2398)                  │  fetch-    └──────────┬───────────────┘
└────────────────────────────┘  manifest             │ yarn codegen
                                                        ▼
                                            ┌──────────────────────────┐
                                            │ src/tools/__generated__/  │
                                            │   activity.ts             │
                                            │   analytics.ts            │
                                            │   call-records.ts         │
                                            │   contacts.ts             │
                                            │   devices.ts              │
                                            │   diagnostics.ts          │
                                            │   policy.ts               │
                                            │   reporting.ts            │
                                            │   index.ts (barrel)       │
                                            └──────────────────────────┘

Codegen only builds the offline tool catalog. It is not the security boundary. Every tool execution independently re-checks the live manifest per call — see docs/architecture.md.

See docs/codegen.md for the full workflow.

Documentation: Architecture | Adding Tools | Codegen Pipeline

Architecture

src/
├── index.ts              # MCP server entry point (stdio transport)
├── lib/
│   ├── api-client.ts     # CallTelemetry REST API client
│   └── credentials.ts    # Environment variable credential loading
├── tools/
│   ├── index.ts          # Tool registry + dispatcher
│   ├── __generated__/    # Auto-generated tool definitions (DO NOT EDIT)
│   ├── call-records.ts   # CDR analysis handlers
│   ├── devices.ts        # Device monitoring handlers
│   ├── policy.ts         # Policy investigation handlers
│   ├── reporting.ts      # Report execution handlers
│   ├── activity.ts       # Activity summary handler
│   ├── contacts.ts       # Contact resolution handler
│   ├── analytics.ts      # Trend analysis handler
│   ├── diagnostics.ts    # Root cause analysis handler
│   └── types.ts          # Shared TypeScript types
├── types/
│   └── index.ts          # Response type interfaces
schemas/
│   └── manifest.json     # Fetched GET /ai/manifest artifact (input to codegen)
scripts/
│   ├── fetch-manifest.ts # GET /ai/manifest → schemas/manifest.json
│   ├── codegen.ts        # Manifest → TypeScript codegen
│   └── smoke-test.cjs    # Post-build validation

Tech Stack

• TypeScript + Node.js 18+
• MCP SDK (@modelcontextprotocol/sdk) for protocol compliance
• Vite for bundling
• Vitest for testing
• tsx for codegen script execution

License

MIT