Ryan Malloy
8b3da9d729
Read-only MCP server for Cisco Unified CM 15 AXL — built for LLM-driven
cluster auditing, with a particular focus on the Route Plan Report:
partitions, calling search spaces, route patterns, translation patterns,
called/calling party transformations, and digit-discard instructions.
Pairs intentionally with the sibling mcp-cisco-docs server (live
cluster state + vendor docs in one LLM context).
Architecture:
- zeep SOAP client to CUCM AXL
- WSDL bootstrap from Cisco's axlsqltoolkit.zip (auto-extract on
first launch; zip is gitignored, vendor-licensed)
- SQLite response cache at ~/.cache/mcp-cucm-axl/responses/
- Schema-grounded prompts that pull chunks from the sibling
cisco-docs index (docs_loader.py)
Read-only by structural guarantee — never registers AXL write methods
(no executeSQLUpdate, no add*/update*/remove*/apply*/reset*/restart*
tools). SQL queries also client-side validated (sql_validator.py) to
begin with SELECT or WITH.
Tools exposed:
Foundational: axl_version, axl_sql, axl_list_tables,
axl_describe_table, cache_stats, cache_clear
Route plan: route_partitions, route_calling_search_spaces,
route_patterns, route_inspect_pattern,
route_lists_and_groups, route_translation_chain,
route_digit_discard_instructions
Prompts (schema-grounded):
route_plan_overview, investigate_pattern, audit_routing,
cucm_sql_help
Tests cover cache, docs_loader, normalize, sql_validator, wildcard.
131 lines
4.7 KiB
Markdown
131 lines
4.7 KiB
Markdown
# mcp-cucm-axl
|
|
|
|
Read-only MCP server for **Cisco Unified CM 15** AXL — built for LLM-driven
|
|
cluster auditing, with a particular focus on the **Route Plan Report**:
|
|
partitions, calling search spaces, route patterns, translation patterns,
|
|
called/calling party transformations, and digit-discard instructions.
|
|
|
|
## Why this exists
|
|
|
|
CUCM's admin UI is great for one-config-at-a-time work but painful for
|
|
audit/discovery questions like:
|
|
|
|
- "Which translation patterns rewrite the calling party number, and why?"
|
|
- "Which CSSs include the `Internal_PT` partition, in what order?"
|
|
- "Show me every route pattern targeting the SIP trunk to the carrier."
|
|
- "Are there partitions defined but unreachable from any CSS?"
|
|
|
|
This server gives an LLM SQL access to CUCM's Informix data dictionary,
|
|
plus focused tools that bake in the right joins for routing-audit work.
|
|
Pair it with the sibling [`mcp-cisco-docs`](../docs/) server and the LLM
|
|
gets vendor documentation alongside live cluster state — answering
|
|
"is our config consistent with Cisco's recommended baseline?" in a single
|
|
conversation.
|
|
|
|
## Read-only by structural guarantee
|
|
|
|
The server **never registers** AXL write methods. There is no
|
|
`executeSQLUpdate`, no `add*`/`update*`/`remove*`/`apply*`/`reset*`/
|
|
`restart*` tool. Read-only is enforced by *absence* of write operations,
|
|
not by runtime sanitization. Defense-in-depth: SQL queries are also
|
|
client-side validated to begin with `SELECT` or `WITH`.
|
|
|
|
## Setup
|
|
|
|
### 1. Configure environment
|
|
|
|
Edit `.env` (already gitignored):
|
|
|
|
```env
|
|
AXL_URL=https://cucm-pub:8443/axl
|
|
AXL_USER=AxlUser
|
|
AXL_PASS=...
|
|
AXL_VERIFY_TLS=false # CUCM ships self-signed certs; default off
|
|
AXL_CACHE_TTL=3600 # 1 hour; 0 disables caching
|
|
AXL_WSDL_PATH= # optional explicit WSDL location
|
|
CISCO_DOCS_INDEX_PATH= # optional override for prompt enrichment
|
|
```
|
|
|
|
### 2. Bootstrap the AXL WSDL
|
|
|
|
Download the **Cisco AXL Toolkit** from your CUCM admin UI:
|
|
|
|
> Application → Plugins → Find → "Cisco AXL Toolkit" → Download
|
|
|
|
Drop the resulting `axlsqltoolkit.zip` into the project directory. On first
|
|
launch, the server auto-extracts `schema/15.0/` into `~/.cache/mcp-cucm-axl/wsdl/15.0/`.
|
|
The zip is gitignored (Cisco-licensed; not redistributable).
|
|
|
|
Alternatives (in resolution order):
|
|
|
|
```bash
|
|
# A: explicit zip elsewhere
|
|
export AXL_WSDL_ZIP=/path/to/axlsqltoolkit.zip
|
|
|
|
# B: explicit WSDL file
|
|
export AXL_WSDL_PATH=/path/to/schema/15.0/AXLAPI.wsdl
|
|
|
|
# C: pre-populated cache directory
|
|
mkdir -p ~/.cache/mcp-cucm-axl/wsdl/15.0/
|
|
cp /path/to/schema/15.0/* ~/.cache/mcp-cucm-axl/wsdl/15.0/
|
|
```
|
|
|
|
### 3. Install + run
|
|
|
|
```bash
|
|
uv sync
|
|
uv run mcp-cucm-axl
|
|
```
|
|
|
|
Or via the bundled `.mcp.json`, automatically registered when Claude Code
|
|
opens this directory.
|
|
|
|
## Tool surface
|
|
|
|
### Foundational
|
|
|
|
| Tool | Purpose |
|
|
|---|---|
|
|
| `axl_version()` | Cluster version sanity check |
|
|
| `axl_sql(query)` | Execute a SELECT against Informix data dictionary |
|
|
| `axl_list_tables(pattern=None)` | Discover Informix tables |
|
|
| `axl_describe_table(name)` | Column metadata for one table |
|
|
| `cache_stats()`, `cache_clear(pattern=None)` | Cache plumbing |
|
|
|
|
### Route plan
|
|
|
|
| Tool | Purpose |
|
|
|---|---|
|
|
| `route_partitions()` | All partitions with member counts |
|
|
| `route_calling_search_spaces(name=None)` | CSS list with ordered partitions |
|
|
| `route_patterns(kind=None, partition=None, filter=None)` | Route Plan Report |
|
|
| `route_inspect_pattern(pattern, partition=None)` | One-pattern deep dive + reverse CSS lookup |
|
|
| `route_lists_and_groups(name=None)` | Route list → route group → device chain |
|
|
| `route_translation_chain(number, css_name=None)` | "What patterns might match this number?" (literal/prefix only) |
|
|
| `route_digit_discard_instructions()` | DDI catalog |
|
|
|
|
## Prompts
|
|
|
|
Schema-grounded conversation seeds. They pull relevant chunks from the
|
|
sibling `cisco-docs` index and embed them inline:
|
|
|
|
- `route_plan_overview` — fresh audit conversation seed
|
|
- `investigate_pattern(pattern, partition=None)` — deep-dive a specific pattern
|
|
- `audit_routing(focus="full")` — comprehensive audit walkthrough
|
|
- `cucm_sql_help(question)` — catch-all for arbitrary SQL questions
|
|
|
|
## Cache
|
|
|
|
Responses are cached in SQLite at `~/.cache/mcp-cucm-axl/responses/axl_responses.sqlite`.
|
|
Cache survives restarts. Clear with `cache_clear()` after a known config change.
|
|
|
|
## Notes
|
|
|
|
- `route_translation_chain` does literal/prefix matching only. CUCM's actual
|
|
matcher evaluates wildcards (`X`, `!`, `[0-9]`, etc.) and selects the
|
|
longest match. Treat results as "patterns to investigate" rather than
|
|
"definitive route."
|
|
- Pattern type codes (`tkpatternusage`) used by `route_patterns(kind=...)` are
|
|
stable across CUCM versions but enumerated against the `typepatternusage`
|
|
table at query time, so any cluster-specific custom types still work.
|