Two ideas borrowed from cisco-cucm-mcp (calltelemetry/cisco-cucm-mcp,
MIT licensed): real-time device registration via RisPort70, and
exponential-backoff retry on transient HTTP 5xx errors. Both are
purpose-built for the audit use case rather than general-purpose
ports — RisPort tools exist to inform audit findings, not as a
standalone "look at my devices" interface.
Rate limit / 503 backoff (~30 lines + 3 tests):
AxlClient now mounts an HTTPAdapter with a urllib3 Retry policy
(3 retries, exponential backoff, status_forcelist=[502,503,504]).
Configurable via AXL_RATE_LIMIT_RETRIES (default 3, 0 disables).
Surfaces in connection_status() so operators can see the policy.
Closes a real reliability gap: CUCM SOAP rate-limits under load
during change windows or with multiple concurrent admins; pre-fix
any 503 was a hard failure.
RisPort70 (new src/risport.py + 2 tools + prompt update):
Hand-coded SOAP client for /realtimeservice2/services/RISService70
(avoids dragging in another zeep instance for one operation).
Reuses AXL_URL/USER/PASS env vars — RisPort lives on the same host.
New tools:
device_registration_status(device_class, status, name_filter, page_size)
device_registration_summary() — cluster-wide breakdown by class
Live-cluster verification (cucm-pub.binghammemorial.org):
Phone: 803 registered=679 unregistered=123 rejected=1
Gateway: 85 registered=41 rejected=44 ← real audit finding
SIPTrunk: 22 registered=18 unregistered=4
HuntList: 28 registered=28
H323/CTI: 0 (cluster doesn't use these)
Discovered while live-verifying: CUCM 15 wraps the RisPort response
in an extra <SelectCmDeviceResult> element inside <selectCmDeviceReturn>.
Older CUCM versions exposed the fields directly. The parser falls
back to either shape; tests cover both (test_legacy_response_shape_still_parses
asserts the older shape still works).
phone_inventory_report prompt updated:
New Step 3 — "Cross-reference with real-time registration" — recommends
device_registration_summary() + device_registration_status(status="UnRegistered")
to surface configured-but-never-registered phones (strongest orphan signal),
PartiallyRegistered phones (firewall/cert/version mismatch indicator),
and registration-state vs config-state mismatches.
Tooling delta worth noting:
AXL device count: 1,377 phones
RisPort device count: 803 phones
Delta (~574) likely templates, hidden phones, or stale config —
itself an audit finding the new tool will surface
to anyone running phone_inventory_report.
README updated:
- Added health(), device_registration_status, device_registration_summary
- Added "Scope and complement" section recommending @calltelemetry/cisco-cucm-mcp
alongside for operational debugging (logs, perfmon, packet capture,
service control). The two servers answer different questions; the LLM
with both can compose audit findings with operational state.
- Listed all 10 prompts (was 4 outdated entries).
Tests: 134 → 155 (+21).
Closes bingham/mcp-cucm-axl#1
route_devices_using_css missed device.fkcallingsearchspace_cgpntransform
and _cdpntransform — the columns trunks use to attach calling-party and
called-party number transformation CSSs. A CSS only referenced via these
columns showed up as "0 references" in impact analysis, leading an
operator to conclude safe-to-delete and break outbound transformations.
Same failure shape as Hamilton CRITICAL #2 (false-zero impact analysis)
but at a different schema layer: that fix added 7 reference points
covering the obvious cases; this fix closes the rest.
What's covered now (71 fkcallingsearchspace_* columns total across 14
tables in CUCM 15):
Templates added for the bulk cases:
_device_query(suffix) — device.fkcallingsearchspace_<suffix>
_devicepool_query(suffix) — devicepool.fkcallingsearchspace_<suffix>
_numplan_query(suffix) — numplan.fkcallingsearchspace_<suffix>
Categories added (51 new):
11× device variants (incl. _cgpntransform and _cdpntransform — the issue)
17× devicepool inheritance variants (closes M1 caveat from audit reports)
13× numplan forwarding/transformation variants (cfbint/cfhr/etc.)
site, externalcallcontrolprofile, recordingprofile, usageprofile,
vipre164transformation×2, incomingtransformationprofile×4
Schema gotchas discovered and codified:
- devicepool, externalcallcontrolprofile, recordingprofile have no
`description` column (verified against syscolumns 2026-04-26)
- site has neither `name` nor `description` — uses `tksite` enum joined
against `typesite.name` for the human-readable form
Live verification on cucm-pub.binghammemorial.org (CUCM 15.0.1.12900-234):
XFORM-Outbound-ANI: 0 → 1 ref (PSTN-Router-SIP-Trk via _cgpntransform)
XFORM-Outbound-DNIS: 0 → 1 ref (PSTN-Router-SIP-Trk via _cdpntransform)
E911CSS: unchanged at 0, but now with `complete: True`
— upgrades from "appears orphan with caveat" to
"confirmed orphan" since DP variants now covered
Internal-CSS: 163 → 174 refs (DP + extra numplan variants)
Tests (128 → 134, +6):
test_issue_1_cgpntransform_column_enumerated
test_issue_1_cdpntransform_column_enumerated
test_finds_trunk_via_cgpntransform_reference (mock-driven E2E)
test_complete_schema_coverage_against_known_columns
— encodes the 71-column snapshot from CUCM 15. If a future CUCM
version adds a new fkcallingsearchspace_* column, the test fires
red so the contributor knows to add it to _CSS_REFERENCE_QUERIES.
test_no_duplicate_table_column_pairs
— guards against double-counting if two categories accidentally
reference the same column.
test_error_in_multiple_tables_propagates
— verifies error reporting works across the new shared-suffix cases
(e.g., _cgpnunknown on both device AND devicepool).
Operator-suggested prompt: "what does my AXL account *actually* have
permission to do?" Resolves the user → access-control-group →
function-role chain for a single account, defaulting to the AXL service
account from AXL_USER env when no userid is given.
The prompt principle came in using table names from older Cisco
docs (`enduserauthgroupmap`, `dirgrouprolemap`) that don't exist on
CUCM 15. The shipped SQL uses the verified CUCM 15 names
(`enduserdirgroupmap`, `functionroledirgroupmap`); a regression test
asserts the deprecated names don't appear in the rendered SQL section,
so any future "fix" reverting to the older names fires red.
Live verification on cucm-pub.binghammemorial.org found the existing
AXL service account (`SupportedSystemsReadOnly`) has 4 roles via the
`ReadOnly-AXL` access control group:
- Standard AXL API Access (full RW — group misnamed)
- Standard AXL Read Only API Access (the genuinely-read-only one)
- Standard Packet Sniffing (PHI-relevant in healthcare)
- Standard RealtimeAndTraceCollection
The first finding is structural: the group `ReadOnly-AXL` contains
the FULL RW role `Standard AXL API Access` despite its name. The
MCP server's structural read-only enforcement (no write methods
registered) is what prevents this from mattering — but the account
itself is over-privileged relative to what the tool needs. The
prompt's findings template surfaces this kind of misnamed-group
case explicitly.
Also discovered (and documented in the prompt body): AXL auth is
case-insensitive for usernames, but SQL `WHERE name = 'X'` is
case-sensitive. Step 3 of the prompt handles the case-mismatch
fallback so a typo like `SupportedSYstemsReadOnly` (env) vs
`SupportedSystemsReadOnly` (cluster canonical) doesn't produce a
silently-empty result.
5 new tests:
- correct CUCM 15 table names embedded in SQL
- explicit userid threads through to the query
- default reads AXL_USER from env
- missing userid AND missing env → clear instruction
- SQL injection defense (single-quote escape)
123 → 128 tests; 9 → 10 prompts. Prompt registration smoke test
updated to assert the new shim is wired.
Builds on the prompts-package extraction. Each new prompt embeds
schema-verified SQL plus a findings template tuned to surface
audit-actionable issues (orphans, drift, capacity outliers, security
posture).
phone_inventory_report(filter=None):
Aggregates by model / device pool / CSS, then anomaly queries for
phones with no description, phones whose description echoes their
MAC-based name, phones with no owner, phones in non-default CSS.
Cross-references owner status (phones owned by inactive users
surface as findings).
user_audit(focus=full|admin|inactive|app_users):
End user + application user inventory, role/group assignments via
the enduserdirgroupmap → dirgroup → functionroledirgroupmap →
functionrole join chain. Security-critical findings: app users
with admin-grade role memberships, local-user accounts with admin
privileges, phones owned by inactive users.
inbound_did_audit():
Reusable form of today's cucm-inbound-did-inventory work. XFORM-
Inbound-DNIS curated list categorized (pass-through, block-trans,
specific renames, wildcards, catch-all hazard). Cross-checked
against Internal-PT route patterns and the operator-curated
PSTN-Screen-PT spam blocklist. Findings for orphan target
extensions and the silent !-catch-all risk.
hunt_pilot_audit():
Hunt pilot inventory with queue settings, line group membership,
and distribution algorithm decoding. Schema knowledge already
Hamilton-verified: huntpilotqueue joins via fknumplan_pilot, NOT
fknumplan (the test asserts the correct column appears in the
rendered prompt). Findings: queue misconfigurations (NULL
destinations, infinite max-wait), empty line groups, dead pilots
with no route-list destination.
Implementation notes:
- Each prompt's SQL was validated against the live cluster
(cucm-pub.binghammemorial.org, CUCM 15.0.1.12900-234).
- user_audit originally used UNION ALL with NULL-typed status
column for the headcounts query; Informix rejected it. Split
into two simpler queries (commented in the prompt body).
- phone_inventory_report uses a Hamilton-style SQL escape for
the optional name_filter (single quotes doubled).
- All four prompts gracefully degrade when the docs index isn't
loaded (verified by test_all_new_prompts_render_without_docs).
114 → 123 tests; 5 → 9 prompts. Full live-cluster verification:
- 12 phone models, 629 Cisco 7841 phones (largest model)
- 1,246 active end users, 25 application users
- Hunt pilots with named distribution algorithms (Broadcast, Top
Down, etc.) — confirms typedistributealgorithm join works
- Hamilton-fixed huntpilotqueue.fknumplan_pilot column verified
in the embedded SQL via dedicated regression test.
Refactor: the four existing inline prompts in server.py move into
individual modules under src/mcp_cucm_axl/prompts/. Server.py keeps
thin @mcp.prompt-decorated shims that delegate to the corresponding
render() function — FastMCP needs the shims because it introspects
their signatures to expose parameters to the LLM, but the prompt
*content* now lives one-prompt-per-file.
Why: server.py's prompt section had grown to ~200 lines of inline
markdown. As more query patterns get documented (see
docs/query-patterns/) this would only worsen. Per-module bodies are
easier to diff, review, and unit-test in isolation.
Layout:
src/mcp_cucm_axl/prompts/
__init__.py
_common.py — shared helpers, keyword sets, render_schema_block
route_plan_overview.py
investigate_pattern.py
audit_routing.py
cucm_sql_help.py
sip_trunk_report.py — NEW
Each prompt module exports a `render(docs, *args) -> str` function
that takes the DocsIndex as a parameter (no module globals). The
shim in server.py grabs the runtime `_docs` and passes it in. Pure
functions = trivially unit-testable.
NEW prompt: sip_trunk_report.
Implementation reference: docs/query-patterns/sip-trunk-report.md
(written separately as a query-pattern doc, validated against the
live cluster). The prompt embeds:
- Step 1: trunk inventory SQL (device + sipdevice + 5 LEFT JOINs)
- Step 2: per-destination SQL (siptrunkdestination)
- Step 3: pointer to existing route_lists_and_groups() tool
- Step 4: findings template (SPOF, profile sprawl, CSS asymmetry,
codec heterogeneity, DNS-vs-IP, security posture)
Optional `name_filter` parameter narrows the inventory via LIKE; the
filter value is escaped for SQL safety (single quotes doubled per
Informix convention).
Tests: 14 new in tests/test_prompts_package.py covering each
prompt's render() with and without docs, plus a registration smoke
test that confirms the FastMCP shim set matches the prompts package
exports (catches the case where a new module is added without its
shim).
Total: 100 → 114 tests; 5 prompts registered; live verification
against cucm-pub.binghammemorial.org confirms the embedded SQL
produces real inventory data. The four original prompts are
behaviorally identical to before — same content, just relocated.
Closes the four remaining findings from the margaret-hamilton review.
13 new regression tests; all 100 pass; live cluster smoke verified.
MAJOR #4 — wildcard regex catastrophic backtracking + silent malformed.
Two changes to _wildcard_to_regex():
a) Bounded the `!` and `@` wildcards to \d{1,50} (was \d+). Adjacent
`!` patterns previously compiled to (\d+)(\d+)... which has
exponential backtracking on near-miss inputs. CUCM dial strings
are practically capped well below 50 digits; the bound keeps
complexity polynomial without losing real-world coverage.
Verified: 10 adjacent `!` against a 30-digit near-miss now finishes
in ~240ms (was unbounded; could have been minutes on real
pathological cases).
b) Unclosed `[` now raises ValueError instead of silently treating the
bracket as a literal. _pattern_matches_number catches the error
and returns False so a single bad pattern doesn't crash
translation_chain — but the bad pattern is no longer invisibly
producing wrong matches. The previous silent fallback meant a
pattern like `[0-9` (typo, missing `]`) would match input
containing the literal characters `[` `0` `-` `9`.
3 new tests covering: bounded-regex shape (`\d{1,N}`), pathological
input completes quickly, unclosed bracket raises explicitly,
well-formed character class still works.
MAJOR #5 — distinguish config errors from operational errors.
Pre-fix: any first-time connection failure set `_connection_error`
and pinned it forever. A transient network blip or session timeout
required restarting the MCP server. Hamilton's framing: Apollo's
software was *designed* to recover from transient faults; pinning
forever is the antithesis of "design the error path first."
Fix: split into two state fields:
_config_error — permanent until restart (missing env vars only)
_last_error — last operational failure, NOT a pin
Operational failures (zeep Client construction, network, TLS, session)
clear from the next call's perspective: the next call attempts fresh.
Configuration errors (missing AXL_URL etc.) stay pinned because
they don't get better on retry.
Added _ConfigError as a private subclass to make the distinction
explicit at the raise site, and connection_status() to expose
connected/connected_at/config_error/last_error for diagnostic
transparency.
3 new tests: config errors pin, operational errors don't pin,
connection_status() reports state.
MINOR #6 — _to_int silent coercion of bad data.
Pre-fix: a non-numeric value from the cluster (data corruption,
schema drift across CUCM versions) silently became None, which
downstream sort logic defaulted to 0 — jumbling the failover order
in the displayed result with no warning.
Fix: still returns None on bad data (caller error path unchanged),
but logs the offending value to stderr so an operator notices
something's wrong at the data layer. None itself is silent
(legitimately-unset column).
2 new tests: real None is silent, bad string logs to stderr with
the offending value visible.
MINOR #7 — standardize tool failure shapes; add health() tool.
Pre-fix: cache_stats and cache_clear returned `{"error": "..."}`
when _cache was None, while AXL-touching tools raised RuntimeError.
LLM consumers had to handle two shapes.
Fix: _require_cache() helper raises RuntimeError consistently with
_client(). All tool failures now use the same exception shape.
Added health() tool that reports cache/axl/docs initialization
status plus the AXL connection_status — gives operators a
self-diagnostic when something fails at bootstrap.
3 new tests: cache_stats raises, cache_clear raises, health()
reports each subsystem.
Three findings from a margaret-hamilton-style review of the MCP server,
fixed with regression tests written first (red → green). One bonus
finding (huntpilotqueue column name) was surfaced by the third fix
itself — exactly the audit-trust failure mode that fix exists to expose.
CRITICAL #1 — sql_validator: comment-strip mutated string literals.
The cleaned query returned by validate_select() is what travels to AXL.
Previously, the comment-strip pass ran before the literal-aware pass,
so `--` or `/* */` markers inside a string literal were silently eaten:
input: WHERE description = 'Smith -- old line'
to AXL: WHERE description = 'Smith (truncated mid-literal)
The LLM saw rows that looked plausible but were not what its query
asked for. "Confidently wrong" is exactly the failure mode the review
was hunting.
Fix: only strip comments on the analysis-only copy used for keyword
detection. The cleaned output preserves the input verbatim (modulo
trailing semicolon and outer whitespace). 6 new tests covering literal
preservation across `--`, `/* */`, LIKE patterns with embedded comment
markers, and forbidden keywords inside real comments.
CRITICAL #2 — cache key omitted cluster identity.
The on-disk cache key was `method::args_json`. An operator swapping
AXL_URL between test and prod (or between two clusters) would silently
serve stale data from cluster A as if from cluster B. The audit
report would be confidently wrong with no signal anything happened.
Fix: AxlCache now takes cluster_id and prefixes all keys with it.
Server bootstrap derives cluster_id as a 12-char SHA-256 prefix of
AXL_URL. cache_stats() surfaces both the current cluster_id and a
`foreign_cluster_entries` count so an env-swap is visible. Schema
migration handles pre-fix cache files via PRAGMA table_info introspection
plus a one-shot ALTER TABLE ADD COLUMN. 5 new tests covering isolation,
shared-id sharing, stats reporting, legacy DB upgrade, and per-cluster
clear() scoping.
MAJOR #3 — find_devices_using_css summary undercounted partial failures.
The function is per-category resilient (one failed query doesn't kill
the whole impact analysis), but the resilience never propagated up to
the response. total_returned and any_truncated only reflected SUCCESSFUL
categories. An LLM consuming "47 references" had no way to know 5
categories errored and the real number was likely much higher.
Fix: response now includes complete: bool, categories_with_errors: int,
and error_categories: [list]. The LLM/auditor sees the partial-failure
state and can decide whether to act on incomplete data. 5 new tests
using a FakeAxlClient stand-in to simulate per-category failures.
BONUS finding (uncovered by Major #3 fix): huntpilotqueue join used
the wrong column. Three CSS impact categories (huntpilot_max_wait_css,
huntpilot_no_agent_css, huntpilot_queue_full_css) were silently
erroring with "Column (fknumplan) not found" because huntpilotqueue
joins via fknumplan_pilot, not fknumplan. With the Major #3 fix in
place, this surfaced immediately as `complete: False, error_categories:
[3 huntpilot_*]` against the live cluster. Fixed inline; live re-run
now reports `complete: True, total_returned: 163` for Internal-CSS.
87 unit tests passing (up from 70). Live cluster smoke test
(cucm-pub.binghammemorial.org, CUCM 15.0.1.12900-234) verifies all
three fixes plus the bonus finding work end-to-end.
Two defects found during live-cluster audit shakedown.
1. SQL validator false-positives on string literals
The forbidden-keyword check tokenized the entire query, including
contents of single-quoted string literals. CSS names like
'Call Forward-CSS', DN descriptions containing 'DELETE', or partition
names with 'INSERT' all tripped the validator even though the SQL
itself was clean read-only. Found while running impact analysis on
"Call Forward-CSS".
Fix: strip string literals (single-quoted, with '' as escape) into
whitespace before the forbidden-keyword tokenization. The cleaned
query returned to the caller still contains the literals — they're
only invisible to the analysis pass.
7 new tests covering: words inside literals (Call/Drop/Delete/etc.),
escaped quotes, multiple literals, and the critical case where a
forbidden keyword appears immediately after a literal.
2. CSS impact analysis missed primary device CSS + 7 other refs
Running route_devices_using_css("E911CSS") returned total=0 even
though E911CSS is configured in the cluster. Root cause: our
enumeration covered device.fkcallingsearchspace_{reroute,restrict,
refer,rdntransform} but not the primary device.fkcallingsearchspace
itself — the column the GUI sets when assigning a CSS to a phone.
The simple unsuffixed name didn't match our earlier "%css%" schema
filter (the actual column spells out "callingsearchspace").
Added 8 new reference categories:
device_primary_css — the big one
device_cgpn_unknown_css — calling-party-unknown
line_monitoring_css — devicenumplanmap monitoring CSS
gateway_h323_called_xform_css — H.323 gateway transform
gateway_sip_called_xform_css — SIP trunk transform
huntpilot_max_wait_css — hunt pilot queue handling
huntpilot_no_agent_css — hunt pilot queue handling
huntpilot_queue_full_css — hunt pilot queue handling
Re-running on live cluster:
Internal-CSS: 146 -> 163 refs (16 new device_primary_css matches)
Call Forward-CSS: previously rejected by validator -> 150 refs
E911CSS: still 0 — high-confidence orphan finding now
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.
