Metadata-Version: 2.4
Name: mcsiphon
Version: 2026.4.27.1
Summary: Read-only MCP server for Cisco Unified CM 15 Trace Collection — wraps the LogCollectionPortTypeService SOAP API for headless log fetch without RTMT. Sibling to mcp-cucm-axl.
Author-email: Ryan Malloy <ryan@supported.systems>
License: MIT
Requires-Python: >=3.11
Requires-Dist: fastmcp>=3.2
Requires-Dist: httpx>=0.27
Requires-Dist: paramiko>=3.5
Requires-Dist: platformdirs>=4.9
Requires-Dist: python-dotenv>=1.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# mcsiphon

Read-only MCP server for **Cisco Unified CM 15** Trace Collection — wraps
the `LogCollectionPortTypeService` SOAP API so an LLM can list, select,
and fetch CUCM log files without needing RTMT.

Companion to [`mcp-cucm-axl`](../axl/) (config) and `mcp-cisco-docs` (docs).
This one handles the operational telemetry.

## What it exposes

| Tool | Purpose |
|---|---|
| `health` | Confirm CUCM connectivity + auth (calls `getTimeZone` under the hood) |
| `get_time_zone` | Server's TZ string |
| `list_node_service_logs` | Enumerate available services per cluster node |
| `select_log_files` | Find log files matching criteria — returns metadata only |
| `get_one_file` | Download one file; caches locally; returns path + preview |
| `render_sip_ladder` | One-shot: fetch SDL trace → preprocess to SIPL/SIPT → run RTMT's `HTMLGenerator` headlessly → return HTML+PNG ladder diagram. Requires `RTMT_LADDER_SCRIPT` and `RTMT_TEMPLATE_DIR` env vars. |

Read-only by structural guarantee — no `selectLogFiles` write parameters
exposed (SFTP push fields are wired off, never accept user input).

## Setup

### 1. Configure environment

Edit `.env`:

```env
TCT_BASE=https://cucm-pub.example.org:8443
TCT_USER=YourServiceAccount
TCT_PASS=YourPassword
TCT_VERIFY_TLS=false   # set true if you've trusted the CUCM CA
```

### 2. Required CUCM RBAC

The service account needs both:

- **`Standard CCM Admin Users`** — webapp baseline gate (without it, every
  request is HTTP 403 with no useful error)
- **`Standard RealtimeAndTraceCollection`** — operation-level grant

Grant via Access Control Group, not direct user-role assignment.

### 3. Run

```bash
uvx mcsiphon          # if installed
# or from source:
uv run mcsiphon
```

### 4. Add to Claude Code

```bash
claude mcp add siphon "uvx mcsiphon"
```

## Sample usage from an LLM

```
LLM: list_node_service_logs()
→ {"cucm-pub.example.org": {"ServiceLog": ["Cisco CallManager", ...], "SystemLog": [...]}, ...}

LLM: select_log_files(services=["Cisco CallManager"], minutes_back=5)
→ [{"node": "cucm-pub", "service": "Cisco CallManager",
    "absolute_path": "/var/log/active/cm/trace/ccm/sdl/SDL001_100_000127.txt.gzo",
    "size_bytes": "211561", "modified_date": "Sun Apr 26 00:23:22 MDT 2026"}]

LLM: get_one_file(absolute_path="/var/log/active/cm/trace/ccm/sdl/SDL001_100_000127.txt.gzo")
→ {"cache_path": "/home/user/.cache/mcsiphon/files/_var_log_..._SDL001_100_000127.txt.gzo",
   "size_bytes": 6742501, "line_count": 56835,
   "preview": "18047782.000 |00:23:18.222 |FileHead |..."}
```

## See also

- [`../rtmt/decompiled/docs/`](../rtmt/decompiled/docs/) — wire protocol
  research notes that informed this implementation
