Telcoladder MCP server

TelcoLadder

<!-- mcp-name: io.github.gollumw/telcoladder -->

Deterministic 5G / 4G / IMS signalling analyzer and call-flow correlator. The correlation and root-cause layer on top of tshark: one subscriber across every interface, every failure explained from a verified cause table, and nothing generated.

For core-network SRE and R&D, RAN/core interoperability test, and third-line troubleshooting at vendors and operators. It assumes you already read signalling for a living.

pip install telcoladder
telcoladder check                             # verifies tshark and its dissectors
telcoladder summarize failed_attach.pcapng    # one page of facts, every failure cited

What you get

Two outputs from one analysis. Mermaid you can paste into a ticket:

sequenceDiagram
    autonumber
    participant gNB
    participant AMF
    Note over gNB,AMF: SUPI 001011234567895
    gNB->>AMF: #35;7 InitialUEMessage ▸ Registration request
    AMF->>gNB: #35;8 DownlinkNASTransport ▸ Authentication request
    rect rgb(255, 226, 226)
    gNB->>AMF: #35;9 UplinkNASTransport ▸ Authentication failure
    Note over AMF: Synch failure (#35;21) — 3GPP TS 24.501 §9.11.3.2
    end
    rect rgb(255, 226, 226)
    AMF->>gNB: #35;10 DownlinkNASTransport ▸ Registration reject
    Note over gNB: Protocol error, unspecified (#35;111) — 3GPP TS 24.501 §9.11.3.2
    end

That is real output from tests/fixtures/ki-mismatch, not an illustration: a UE provisioned with the wrong key, captured on a local Open5GS testbed. It is not the MAC failure you would expect — a UE whose K does not match computes an AUTS the network cannot resynchronise from, so you get #21 and then a bare #111. The cause table says so because we ran it, not because it sounded right.

And the same capture in the browser: a packet list driven by real tshark display filters, per-frame decode tree and bytes, the ladder with the initiator and the cause on every failing event, and a per-PDU-session matrix where every cell cites the frame it came from.

What it reads

Every cause code is resolved through a hand-verified table to the specification it comes from, what it means in plain language, and the root causes that actually produce it in the field — 775 of them, every name taken verbatim from tshark and re-checked against it by a test. Nothing is generated: a cause the table does not carry is reported as not catalogued, and a clause number is printed only where a person transcribed it. Every network function is named rather than shown as an IP, with the evidence for that name on hover.

The pain, and what replaces it

Shortened. The full README is on GitHub.