@calltelemetry/cucm-mcp 0.1.6 → 0.1.8

package/README.md

@@ -90,3 +90,58 @@ Live tests are opt-in via env vars; see `test/live.test.js`.
 - Use the platform/OS admin for SSH (`administrator` user on most lab systems)
 - To request a high packet count without specifying an exact number, pass `maxPackets: true` to `packet_capture_start`
 - If traffic is low, a small `count` can still run “forever” waiting for packets; use `packet_capture_stop` to cancel, or set `maxDurationMs` to auto-stop
+
+### Auth Note (DIME vs SSH)
+
+CUCM deployments vary:
+
+- SSH and DIME may accept different usernames/passwords.
+- Quick check: the right DIME user returns HTTP 200 for the WSDL.
+
+```bash
+curl -k -u "<user>:<pass>" \
+  "https://<cucm-host>:8443/logcollectionservice2/services/LogCollectionPortTypeService?wsdl" \
+  -o /dev/null -w "%{http_code}\n"
+```
+
+### Recommended Workflow
+
+1) Start capture (returns quickly; capture continues on CUCM):
+
+Tool: `packet_capture_start`
+
+Useful options:
+
+- `count`: stop after N packets (can wait indefinitely if traffic is low)
+- `maxDurationMs`: stop after a fixed time even if packet count isn’t reached
+- `startTimeoutMs`: fail fast if the CUCM CLI prompt isn’t reachable
+- `maxPackets: true`: sets a high capture count (1,000,000) when `count` is omitted
+
+2) Stop + download the capture:
+
+Tool: `packet_capture_stop_and_download`
+
+This:
+
+- stops the SSH capture (best-effort)
+- retries DIME downloads until the file appears
+- tries rolled filenames (`.cap01`, `.cap02`, ...)
+
+### What to Expect in Output
+
+Many MCP clients truncate long JSON. The CUCM MCP tools print a one-line summary first, followed by the full JSON:
+
+- `packet_capture_start`: prints `id`, `remoteFilePath`, and a reminder that capture continues on CUCM until stopped
+- `packet_capture_stop_and_download`: prints `savedPath` and `bytes` so you can immediately open the file
+
+### Viewing the Capture (macOS)
+
+After download, you’ll get a `savedPath` like `/tmp/foo.cap`.
+
+```bash
+# Reveal in Finder
+open -R "/tmp/foo.cap"
+
+# Open in Wireshark
+open -a Wireshark "/tmp/foo.cap"
+```

package/dist/axl.js

@@ -0,0 +1,130 @@
+import { XMLParser } from "fast-xml-parser";
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@",
+    removeNSPrefix: true,
+    trimValues: true,
+});
+function basicAuthHeader(username, password) {
+    return `Basic ${Buffer.from(`${username}:${password}`, "utf8").toString("base64")}`;
+}
+function escapeXml(s) {
+    return s
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&apos;");
+}
+export function normalizeHost(hostOrUrl) {
+    const s = String(hostOrUrl || "").trim();
+    if (!s)
+        throw new Error("host is required");
+    if (s.includes("://")) {
+        const u = new URL(s);
+        return u.hostname;
+    }
+    return s.replace(/^https?:\/\//, "").replace(/\/+$/, "").split("/")[0];
+}
+export function resolveAxlAuth(auth) {
+    const username = auth?.username || process.env.CUCM_AXL_USERNAME || process.env.CUCM_USERNAME || process.env.CUCM_DIME_USERNAME;
+    const password = auth?.password || process.env.CUCM_AXL_PASSWORD || process.env.CUCM_PASSWORD || process.env.CUCM_DIME_PASSWORD;
+    if (!username || !password) {
+        throw new Error("Missing AXL credentials (provide auth or set CUCM_AXL_USERNAME/CUCM_AXL_PASSWORD)");
+    }
+    return { username, password };
+}
+export function resolveAxlTarget(hostOrUrl, port, version) {
+    const host = normalizeHost(hostOrUrl);
+    const envPort = process.env.CUCM_AXL_PORT ? Number.parseInt(process.env.CUCM_AXL_PORT, 10) : undefined;
+    const resolvedPort = port ?? envPort ?? 8443;
+    const resolvedVersion = version || process.env.CUCM_AXL_VERSION || "15.0";
+    return { host, port: resolvedPort, version: resolvedVersion };
+}
+function soapEnvelope(axlVersion, innerXml) {
+    const ns = `http://www.cisco.com/AXL/API/${escapeXml(axlVersion)}`;
+    return (`<?xml version="1.0" encoding="UTF-8"?>` +
+        `<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="${ns}">` +
+        `<soapenv:Header/>` +
+        `<soapenv:Body>` +
+        innerXml +
+        `</soapenv:Body>` +
+        `</soapenv:Envelope>`);
+}
+async function fetchAxl(target, auth, operation, innerXml, timeoutMs = 30_000) {
+    const url = `https://${target.host}:${target.port}/axl/`;
+    const xmlBody = soapEnvelope(target.version, innerXml);
+    const res = await fetch(url, {
+        method: "POST",
+        headers: {
+            Authorization: basicAuthHeader(auth.username, auth.password),
+            "Content-Type": "text/xml; charset=utf-8",
+            SOAPAction: `CUCM:DB ver=${target.version} ${operation}`,
+            Accept: "*/*",
+        },
+        body: Buffer.from(xmlBody, "utf8"),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    const contentType = res.headers.get("content-type");
+    const text = await res.text().catch(() => "");
+    if (!res.ok) {
+        throw new Error(`CUCM AXL HTTP ${res.status}: ${text || res.statusText}`);
+    }
+    return { contentType, xml: text };
+}
+function parseSoapReturn(operation, xmlText) {
+    const parsed = parser.parse(xmlText);
+    const env = parsed.Envelope || parsed;
+    const body = env.Body || env;
+    const fault = body?.Fault;
+    if (fault) {
+        const faultString = fault.faultstring || fault.faultcode || JSON.stringify(fault);
+        return { fault: String(faultString) };
+    }
+    const resp = body?.[`${operation}Response`];
+    const ret = resp?.return;
+    if (ret == null)
+        return {};
+    if (typeof ret === "string")
+        return { returnValue: ret };
+    // Some AXL responses wrap the value.
+    if (typeof ret === "object" && typeof ret["#text"] === "string")
+        return { returnValue: ret["#text"] };
+    return { returnValue: String(ret) };
+}
+export async function updatePhonePacketCapture(hostOrUrl, args) {
+    const target = resolveAxlTarget(hostOrUrl, args.port, args.version);
+    const auth = resolveAxlAuth(args.auth);
+    const name = String(args.deviceName || "").trim();
+    if (!name)
+        throw new Error("deviceName is required");
+    const mode = String(args.mode || "").trim();
+    if (!mode)
+        throw new Error("mode is required");
+    const duration = Math.trunc(args.durationSeconds);
+    if (!Number.isFinite(duration) || duration <= 0)
+        throw new Error("durationSeconds must be > 0");
+    const innerXml = `<ns:updatePhone>` +
+        `<name>${escapeXml(name)}</name>` +
+        `<packetCaptureMode>${escapeXml(mode)}</packetCaptureMode>` +
+        `<packetCaptureDuration>${escapeXml(String(duration))}</packetCaptureDuration>` +
+        `</ns:updatePhone>`;
+    const { xml } = await fetchAxl(target, auth, "updatePhone", innerXml, args.timeoutMs ?? 30_000);
+    const parsed = parseSoapReturn("updatePhone", xml);
+    if (parsed.fault)
+        throw new Error(`AXL updatePhone fault: ${parsed.fault}`);
+    return { host: target.host, operation: "updatePhone", returnValue: parsed.returnValue };
+}
+export async function applyPhone(hostOrUrl, args) {
+    const target = resolveAxlTarget(hostOrUrl, args.port, args.version);
+    const auth = resolveAxlAuth(args.auth);
+    const name = String(args.deviceName || "").trim();
+    if (!name)
+        throw new Error("deviceName is required");
+    const innerXml = `<ns:applyPhone><name>${escapeXml(name)}</name></ns:applyPhone>`;
+    const { xml } = await fetchAxl(target, auth, "applyPhone", innerXml, args.timeoutMs ?? 30_000);
+    const parsed = parseSoapReturn("applyPhone", xml);
+    if (parsed.fault)
+        throw new Error(`AXL applyPhone fault: ${parsed.fault}`);
+    return { host: target.host, operation: "applyPhone", returnValue: parsed.returnValue };
+}

package/dist/index.js

@@ -6,6 +6,7 @@ import { listNodeServiceLogs, selectLogs, selectLogsMinutes, getOneFile, getOneF
 import { guessTimezoneString } from "./time.js";
 import { PacketCaptureManager } from "./packetCapture.js";
 import { defaultStateStore } from "./state.js";
+import { applyPhone, updatePhonePacketCapture } from "./axl.js";
 // Default to accepting self-signed/invalid certs (common on CUCM lab/dev).
 // Opt back into strict verification with CUCM_MCP_TLS_MODE=strict.
 const tlsMode = (process.env.CUCM_MCP_TLS_MODE || process.env.MCP_TLS_MODE || "").toLowerCase();
@@ -14,7 +15,7 @@ const strictTls = tlsMode === "strict" || tlsMode === "verify";
 // Set CUCM_MCP_TLS_MODE=strict to enforce verification.
 if (!strictTls)
     process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
-const server = new McpServer({ name: "cucm", version: "0.1.6" });
+const server = new McpServer({ name: "cucm", version: "0.1.8" });
 const captures = new PacketCaptureManager();
 const captureState = defaultStateStore();
 const dimeAuthSchema = z
@@ -29,6 +30,12 @@ const sshAuthSchema = z
     password: z.string().optional(),
 })
     .optional();
+const axlAuthSchema = z
+    .object({
+    username: z.string().optional(),
+    password: z.string().optional(),
+})
+    .optional();
 server.tool("guess_timezone_string", "Build a best-effort DIME timezone string for selectLogFiles.", {}, async () => ({
     content: [{ type: "text", text: JSON.stringify({ timezone: guessTimezoneString(new Date()) }, null, 2) }],
 }));
@@ -82,6 +89,66 @@ server.tool("select_syslog_minutes", "Convenience wrapper: select system log fil
     const result = await selectLogsMinutes(host, minutesBack, { systemLogs: [systemLog || "Syslog"], searchStr }, timezone, auth, port);
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 });
+server.tool("phone_packet_capture_enable", "Enable phone packet capture via CUCM AXL (updatePhone packetCaptureMode/Duration + applyPhone).", {
+    host: z.string().describe("CUCM host/IP"),
+    port: z.number().int().min(1).max(65535).optional().describe("AXL port (default 8443)"),
+    axlVersion: z.string().optional().describe("AXL API version (default env CUCM_AXL_VERSION or 15.0)"),
+    auth: axlAuthSchema.describe("AXL auth (optional; defaults to CUCM_AXL_USERNAME/CUCM_AXL_PASSWORD)"),
+    deviceName: z.string().min(1).describe("Phone device name (e.g. SEP505C885DF37F)"),
+    mode: z
+        .string()
+        .optional()
+        .describe('packetCaptureMode value (commonly "Batch Processing Mode")'),
+    durationSeconds: z
+        .number()
+        .int()
+        .min(1)
+        .max(60 * 60)
+        .optional()
+        .describe("packetCaptureDuration in seconds (default 60)"),
+    apply: z.boolean().optional().describe("Run applyPhone after updatePhone (default true)"),
+    timeoutMs: z.number().int().min(1000).max(5 * 60_000).optional().describe("AXL request timeout"),
+}, async ({ host, port, axlVersion, auth, deviceName, mode, durationSeconds, apply, timeoutMs }) => {
+    const update = await updatePhonePacketCapture(host, {
+        deviceName,
+        mode: mode || "Batch Processing Mode",
+        durationSeconds: durationSeconds ?? 60,
+        auth: auth,
+        port,
+        version: axlVersion,
+        timeoutMs,
+    });
+    const shouldApply = apply ?? true;
+    const applied = shouldApply
+        ? await applyPhone(host, {
+            deviceName,
+            auth: auth,
+            port,
+            version: axlVersion,
+            timeoutMs,
+        })
+        : undefined;
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    host: update.host,
+                    deviceName,
+                    packetCaptureMode: mode || "Batch Processing Mode",
+                    packetCaptureDuration: durationSeconds ?? 60,
+                    updatePhoneReturn: update.returnValue,
+                    applied: shouldApply,
+                    applyPhoneReturn: applied?.returnValue,
+                    notes: [
+                        "Phone may need to reset to pick up config.",
+                        "Place the call during the duration window; CUCM writes the capture to its TFTP directory (CUCM behavior/version dependent).",
+                    ],
+                }, null, 2),
+            },
+        ],
+    };
+});
 server.tool("download_file", "Download a single file via DIME GetOneFile and write it to disk.", {
     host: z.string(),
     port: z.number().int().min(1).max(65535).optional(),
@@ -143,7 +210,12 @@ server.tool("packet_capture_start", "Start a packet capture on CUCM via SSH (uti
         maxDurationMs,
         startTimeoutMs,
     });
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    const summary = `Started CUCM packet capture (SSH). ` +
+        `id=${result.id} host=${result.host} fileBase=${result.fileBase} remoteFilePath=${result.remoteFilePath}. ` +
+        `Stops when packet count is reached, when you call packet_capture_stop, or via maxDurationMs.`;
+    return {
+        content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(result, null, 2)}` }],
+    };
 });
 server.tool("packet_capture_list", "List active packet captures started by this MCP server.", {}, async () => ({ content: [{ type: "text", text: JSON.stringify(captures.list(), null, 2) }] }));
 server.tool("packet_capture_state_list", "List packet captures from the local state file (survives MCP restarts).", {}, async () => {
@@ -179,22 +251,47 @@ server.tool("packet_capture_stop", "Stop a packet capture by captureId (sends Ct
     captureId: z.string().min(1),
     timeoutMs: z.number().int().min(1000).max(10 * 60_000).optional().describe("How long to wait for stop (default ~90s)"),
 }, async ({ captureId, timeoutMs }) => {
-    const result = await captures.stop(captureId, timeoutMs);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    try {
+        const result = await captures.stop(captureId, timeoutMs);
+        const summary = `Stopped capture. id=${result.id} stopTimedOut=${Boolean(result.stopTimedOut)} remoteFilePath=${result.remoteFilePath}`;
+        return { content: [{ type: "text", text: `${summary}\n\n${JSON.stringify(result, null, 2)}` }] };
+    }
+    catch (e) {
+        const stopError = e instanceof Error ? e.message : String(e || "");
+        const pruned = captureState.pruneExpired(captureState.load());
+        const rec = pruned.captures[captureId];
+        if (!rec)
+            throw e;
+        const summary = `Failed to stop capture (returning state record). id=${captureId} stopError=${JSON.stringify(stopError)}`;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${summary}\n\n${JSON.stringify({ stopError, record: rec }, null, 2)}`,
+                },
+            ],
+        };
+    }
 });
 server.tool("packet_capture_stop_and_download", "Stop a packet capture and download the resulting .cap file via DIME.", {
     captureId: z.string().min(1),
     dimePort: z.number().int().min(1).max(65535).optional(),
     auth: dimeAuthSchema.describe("DIME auth (optional; defaults to CUCM_DIME_USERNAME/CUCM_DIME_PASSWORD)"),
     outFile: z.string().optional().describe("Optional output path for the downloaded .cap file"),
-    stopTimeoutMs: z.number().int().min(1000).max(10 * 60_000).optional().describe("How long to wait for SSH capture stop"),
+    stopTimeoutMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(10 * 60_000)
+        .optional()
+        .describe("How long to wait for SSH capture stop (default 300000)"),
     downloadTimeoutMs: z
         .number()
         .int()
         .min(1000)
         .max(10 * 60_000)
         .optional()
-        .describe("How long to wait for the capture file to appear in DIME"),
+        .describe("How long to wait for the capture file to appear in DIME (default 300000)"),
     downloadPollIntervalMs: z
         .number()
         .int()
@@ -203,31 +300,50 @@ server.tool("packet_capture_stop_and_download", "Stop a packet capture and downl
         .optional()
         .describe("How often to retry DIME GetOneFile when the file isn't there yet"),
 }, async ({ captureId, dimePort, auth, outFile, stopTimeoutMs, downloadTimeoutMs, downloadPollIntervalMs }) => {
-    const stopped = await captures.stop(captureId, stopTimeoutMs);
-    const candidates = (stopped.remoteFileCandidates || []).length
-        ? stopped.remoteFileCandidates
-        : [stopped.remoteFilePath];
+    const stopTimeout = stopTimeoutMs ?? 300_000;
+    const dlTimeout = downloadTimeoutMs ?? 300_000;
+    const dlPoll = downloadPollIntervalMs ?? 2000;
+    let stopped;
+    let stopError;
+    try {
+        stopped = await captures.stop(captureId, stopTimeout);
+    }
+    catch (e) {
+        stopError = e instanceof Error ? e.message : String(e || "");
+        // Fall back to state file (useful if stop failed or MCP restarted).
+        const pruned = captureState.pruneExpired(captureState.load());
+        const rec = pruned.captures[captureId];
+        if (!rec)
+            throw new Error(`Failed to stop capture and capture not found in state: ${captureId}. stopError=${stopError}`);
+        stopped = rec;
+    }
+    const candidates = (stopped.remoteFileCandidates || []).length ? stopped.remoteFileCandidates : [stopped.remoteFilePath];
     const dl = await getOneFileAnyWithRetry(stopped.host, candidates, {
         auth: auth,
         port: dimePort,
-        timeoutMs: downloadTimeoutMs,
-        pollIntervalMs: downloadPollIntervalMs,
+        timeoutMs: dlTimeout,
+        pollIntervalMs: dlPoll,
     });
     const saved = writeDownloadedFile(dl, outFile);
+    const summary = `Capture downloaded. ` +
+        `id=${captureId} stopTimedOut=${Boolean(stopped.stopTimedOut)} remoteFilePath=${dl.filename} ` +
+        `savedPath=${saved.filePath} bytes=${saved.bytes}` +
+        (stopError ? ` stopError=${JSON.stringify(stopError)}` : "");
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({
+                text: `${summary}\n\n${JSON.stringify({
                     captureId: stopped.id,
                     host: stopped.host,
                     remoteFilePath: dl.filename,
                     stopTimedOut: stopped.stopTimedOut || false,
+                    stopError,
                     savedPath: saved.filePath,
                     bytes: saved.bytes,
                     dimeAttempts: dl.attempts,
                     dimeWaitedMs: dl.waitedMs,
-                }, null, 2),
+                }, null, 2)}`,
             },
         ],
     };
@@ -263,11 +379,12 @@ server.tool("packet_capture_download_from_state", "Download a capture file using
         pollIntervalMs: downloadPollIntervalMs,
     });
     const saved = writeDownloadedFile(dl, outFile);
+    const summary = `Capture downloaded from state. id=${captureId} remoteFilePath=${dl.filename} savedPath=${saved.filePath} bytes=${saved.bytes}`;
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({
+                text: `${summary}\n\n${JSON.stringify({
                     captureId,
                     host: rec.host,
                     remoteFilePath: dl.filename,
@@ -275,7 +392,7 @@ server.tool("packet_capture_download_from_state", "Download a capture file using
                     bytes: saved.bytes,
                     dimeAttempts: dl.attempts,
                     dimeWaitedMs: dl.waitedMs,
-                }, null, 2),
+                }, null, 2)}`,
             },
         ],
     };

package/dist/packetCapture.js

@@ -151,18 +151,33 @@ export class PacketCaptureManager {
             ...session,
             stoppedAt: session.stoppedAt,
         });
-        await new Promise((resolve, reject) => {
-            client
-                .on("ready", () => resolve())
-                .on("error", (e) => reject(e))
-                .connect({
-                host: opts.host,
-                port: sshPort,
-                username: auth.username,
-                password: auth.password,
-                readyTimeout: 15000,
-            });
+        const startTimeoutMs = Math.max(2000, Math.trunc(opts.startTimeoutMs ?? 30_000));
+        let connectTimer;
+        const connectTimeout = new Promise((_, reject) => {
+            connectTimer = setTimeout(() => reject(new Error(`SSH connect timed out after ${startTimeoutMs}ms`)), startTimeoutMs);
+            connectTimer.unref?.();
         });
+        try {
+            await Promise.race([
+                new Promise((resolve, reject) => {
+                    client
+                        .on("ready", () => resolve())
+                        .on("error", (e) => reject(e))
+                        .connect({
+                        host: opts.host,
+                        port: sshPort,
+                        username: auth.username,
+                        password: auth.password,
+                        readyTimeout: 15000,
+                    });
+                }),
+                connectTimeout,
+            ]);
+        }
+        finally {
+            if (connectTimer)
+                clearTimeout(connectTimer);
+        }
         // CUCM SSH presents an interactive CLI shell. `exec()` is not reliably supported,
         // so we open a shell and type commands at the prompt.
         const channel = await new Promise((resolve, reject) => {
@@ -196,7 +211,7 @@ export class PacketCaptureManager {
         });
         // Wait for prompt before running capture command.
         // Some CUCM shells don't print a prompt until you send a newline.
-        const promptTimeoutMs = Math.max(2000, Math.trunc(opts.startTimeoutMs ?? 30_000));
+        const promptTimeoutMs = startTimeoutMs;
         try {
             try {
                 channel.write("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/cucm-mcp",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "private": false,
   "type": "module",
   "description": "MCP server for CUCM tooling (DIME logs, syslog, packet capture)",