@calltelemetry/cucm-emulator-mcp

OpenAPI-driven Model Context Protocol (MCP) server for Cisco Unified Communications Manager (CUCM) Emulator.

Overview

@calltelemetry/cucm-emulator-mcp is an OpenAPI-driven MCP server that connects AI coding assistants and automation agents directly to Cisco CUCM Emulator instances. It parses the emulator's OpenAPI 3.1.0 contract specification to dynamically generate strongly-typed discrete MCP tools across all 6 core telephony domains:

1. Fixtures & Topology: emu_seed_fixtures, emu_reset_store, emu_inspect_fixtures

2. Nodes & Cluster Health: emu_list_nodes, emu_set_node_status (ADR 0120/0122 failover)

3. Phones & Registration: emu_list_phones, emu_set_phone_status, emu_get_phone_web

4. Call Simulation & Legs: emu_simulate_call, emu_call_action, emu_list_active_calls

5. CURRI / ECC Policy Routing: emu_evaluate_curri, emu_get_curri_history

6. CDR / CMR Buffers: emu_generate_cdrs, emu_get_cdr_history

7. Dynamic OpenAPI Operations: 46+ auto-compiled operations (emu_get_summary, emu_get_topology, emu_query_sql, emu_list_inventory, emu_upsert_inventory, etc.)

Related MCP server: packet-tracer-mcp

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    AI Agents / MCP Clients                  │
│                (Claude Code, Cursor, Windsurf)              │
└──────────────────────────────┬──────────────────────────────┘
                               │ JSON-RPC 2.0 (Stdio / SSE)
┌──────────────────────────────▼──────────────────────────────┐
│                  CucmEmulatorMcpServer                      │
│                                                             │
│  ┌───────────────────────┐      ┌────────────────────────┐  │
│  │     Tool Registry     │      │   OpenAPI Spec Parser  │  │
│  │ (15 Domain + Dynamic) │◄─────┤   (Dereferencer/Build) │  │
│  └───────────┬───────────┘      └────────────────────────┘  │
│              │                                              │
│  ┌───────────▼───────────────────────────────────────────┐  │
│  │             ICucmEmulatorClient Abstraction           │  │
│  └───────────┬───────────────────────────┬───────────────┘  │
└──────────────┼───────────────────────────┼──────────────────┘
               │                           │
┌──────────────▼────────────┐ ┌────────────▼──────────────────┐
│      HttpCucmClient       │ │    DirectStoreCucmClient      │
│  Live In-Guest / Container│ │  In-Memory Mock Store State   │
│ (http://127.0.0.1:8443)   │ │  (100% Offline Zero-Config)   │
└───────────────────────────┘ └───────────────────────────────┘

Installation & Quick Start

Global CLI

npm install -g @calltelemetry/cucm-emulator-mcp

Run Stdio Server (for AI Agents / Claude Desktop)

cucm-emulator-mcp --transport stdio

Run SSE Server

cucm-emulator-mcp --transport sse --port 3000 --host 127.0.0.1

Configuration Options

MCP Client Configuration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "cucm-emulator": {
      "command": "cucm-emulator-mcp",
      "args": ["--transport", "stdio", "--mock", "--seed-profile", "lab-small"]
    }
  }
}

SSE Integration

{
  "mcpServers": {
    "cucm-emulator-sse": {
      "url": "http://127.0.0.1:3000/sse"
    }
  }
}

Available Tool Reference

Fixtures & Topology

• emu_seed_fixtures: Seeds deterministic cluster topology, nodes, phones, dial plan partitions, CSS, and CURRI policies.

• emu_reset_store: Resets or wipes emulator state and re-seeds with a specified topology profile.

• emu_inspect_fixtures: Inspects and returns a comprehensive summary of active CUCM cluster state.

Nodes & Failover

• emu_list_nodes: Lists all CUCM cluster nodes (Publisher, Subscribers, TFTP) with roles and RIS return codes.

• emu_set_node_status: Sets node status (Online, Offline, NotFound, SearchLimitExceeded) for ADR 0120/0122 failover testing.

Phones & Registration

• emu_list_phones: Lists configured and registered Cisco IP phone endpoints with directory numbers and MACs.

• emu_set_phone_status: Updates phone registration status (Registered, UnRegistered, Rejected, Unknown).

• emu_get_phone_web: Fetches phone XML, HTML, or JSON serviceability / status web responses.

Call Simulation

• emu_simulate_call: Simulates an end-to-end telephone call through CUCM dial plan routing with RTP media metrics.

• emu_call_action: Executes mid-call actions (answer, hold, resume, drop).

• emu_list_active_calls: Lists active in-progress call sessions in the emulator.

CURRI / ECC Policy Routing

• emu_evaluate_curri: Evaluates external call routing policies via CURRI / ECC, returning permit, deny, or divert verdicts.

• emu_get_curri_history: Retrieves the log of past CURRI routing evaluation decisions.

CDR / CMR Buffers

• emu_generate_cdrs: Generates batches of synthetic CDR records (normal, abandoned, curri-blocked, burst).

• emu_get_cdr_history: Retrieves recent CDR records in structured JSON or raw Cisco CSV export format.

Development & Verification

# Typecheck
npm run typecheck

# Build TypeScript
npm run build

# Run Full Test Suite (155 Tests)
npm test

# Run with Coverage
npm run test:coverage

# Verify Packaging
npm pack --dry-run

License

MIT © Call Telemetry