@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 16 AI-powered tools 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?" |

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 codegen          # Generate tool definitions from backend schemas
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 — not hand-maintained.

cisco-cdr (Elixir)              ct-analytics-mcp (TypeScript)
┌─────────────────┐             ┌──────────────────────────┐
│ mix ai.gen_schemas │ ─JSON──▶ │ schemas/capability_schemas.json │
└─────────────────┘             └──────────┬───────────────┘
                                           │ 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)       │
                                └──────────────────────────┘

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/
│   └── capability_schemas.json  # Backend-generated tool schemas
scripts/
│   ├── codegen.ts        # Schema → 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