@calltelemetry/cucm-mcp 0.1.2 → 0.1.4

package/README.md

@@ -30,6 +30,14 @@ CUCM lab environments often use self-signed certificates. By default this server
 
 - `CUCM_MCP_TLS_MODE=strict` (or `MCP_TLS_MODE=strict`)
 
+### Local State (Capture Recovery)
+
+This server persists packet capture metadata to a local JSON file so you can recover/download captures after an MCP restart.
+
+- `CUCM_MCP_STATE_PATH` (default: `./.cucm-mcp-state.json`)
+- `CUCM_MCP_CAPTURE_RUNNING_TTL_MS` (default: 6 hours)
+- `CUCM_MCP_CAPTURE_STOPPED_TTL_MS` (default: 24 hours)
+
 ## Run
 
 ```bash
@@ -74,3 +82,10 @@ Live tests are opt-in via env vars; see `test/live.test.js`.
 - `select_syslog_minutes` - list recent system log files (defaults to `Syslog`)
 - `packet_capture_start` / `packet_capture_stop` - control captures via SSH
 - `packet_capture_stop_and_download` - stop capture + download `.cap` via DIME
+- `packet_capture_state_list` - list captures from state file
+- `packet_capture_download_from_state` - download by captureId after restart
+
+## Packet Capture Notes
+
+- 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`

package/dist/index.js

@@ -5,6 +5,7 @@ import { z } from "zod";
 import { listNodeServiceLogs, selectLogs, selectLogsMinutes, getOneFile, getOneFileAnyWithRetry, writeDownloadedFile, } from "./dime.js";
 import { guessTimezoneString } from "./time.js";
 import { PacketCaptureManager } from "./packetCapture.js";
+import { defaultStateStore } from "./state.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();
@@ -13,8 +14,9 @@ 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.0" });
+const server = new McpServer({ name: "cucm", version: "0.1.4" });
 const captures = new PacketCaptureManager();
+const captureState = defaultStateStore();
 const dimeAuthSchema = z
     .object({
     username: z.string().optional(),
@@ -104,18 +106,23 @@ server.tool("packet_capture_start", "Start a packet capture on CUCM via SSH (uti
     auth: sshAuthSchema,
     iface: z.string().optional().describe("Interface (default eth0)"),
     fileBase: z.string().optional().describe("Capture base name (no dots). Saved as <fileBase>.cap"),
-    count: z.number().int().min(1).max(200000).optional().describe("Packet count (file max is typically 100000)"),
+    count: z.number().int().min(1).max(1_000_000).optional().describe("Packet count (common max is 1000000)"),
+    maxPackets: z
+        .boolean()
+        .optional()
+        .describe("If true and count is omitted, uses a high capture count (1,000,000)"),
     size: z.string().optional().describe("Packet size (e.g. all)"),
     hostFilterIp: z.string().optional().describe("Optional filter: host ip <addr>"),
     portFilter: z.number().int().min(1).max(65535).optional().describe("Optional filter: port <num>"),
-}, async ({ host, sshPort, auth, iface, fileBase, count, size, hostFilterIp, portFilter }) => {
+}, async ({ host, sshPort, auth, iface, fileBase, count, maxPackets, size, hostFilterIp, portFilter }) => {
+    const resolvedCount = count ?? (maxPackets ? 1_000_000 : undefined);
     const result = await captures.start({
         host,
         sshPort,
         auth: auth,
         iface,
         fileBase,
-        count,
+        count: resolvedCount,
         size,
         hostFilterIp,
         portFilter,
@@ -123,6 +130,35 @@ server.tool("packet_capture_start", "Start a packet capture on CUCM via SSH (uti
     return { content: [{ type: "text", text: 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 () => {
+    const pruned = captureState.pruneExpired(captureState.load());
+    captureState.save(pruned);
+    const items = Object.values(pruned.captures).sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+    return { content: [{ type: "text", text: JSON.stringify({ path: captureState.path, captures: items }, null, 2) }] };
+});
+server.tool("packet_capture_state_get", "Get a packet capture record from the local state file.", {
+    captureId: z.string().min(1),
+}, async ({ captureId }) => {
+    const pruned = captureState.pruneExpired(captureState.load());
+    const rec = pruned.captures[captureId];
+    if (!rec) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ path: captureState.path, found: false, captureId }, null, 2),
+                },
+            ],
+        };
+    }
+    return { content: [{ type: "text", text: JSON.stringify({ path: captureState.path, found: true, record: rec }, null, 2) }] };
+});
+server.tool("packet_capture_state_clear", "Delete a capture record from the local state file.", {
+    captureId: z.string().min(1),
+}, async ({ captureId }) => {
+    captureState.remove(captureId);
+    return { content: [{ type: "text", text: JSON.stringify({ removed: true, captureId }, null, 2) }] };
+});
 server.tool("packet_capture_stop", "Stop a packet capture by captureId (sends Ctrl-C).", {
     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)"),
@@ -180,5 +216,53 @@ server.tool("packet_capture_stop_and_download", "Stop a packet capture and downl
         ],
     };
 });
+server.tool("packet_capture_download_from_state", "Download a capture file using the local state record (useful after MCP restart).", {
+    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"),
+    downloadTimeoutMs: z
+        .number()
+        .int()
+        .min(1000)
+        .max(10 * 60_000)
+        .optional()
+        .describe("How long to wait for the capture file to appear in DIME"),
+    downloadPollIntervalMs: z
+        .number()
+        .int()
+        .min(250)
+        .max(30_000)
+        .optional()
+        .describe("How often to retry DIME GetOneFile when the file isn't there yet"),
+}, async ({ captureId, dimePort, auth, outFile, downloadTimeoutMs, downloadPollIntervalMs }) => {
+    const pruned = captureState.pruneExpired(captureState.load());
+    const rec = pruned.captures[captureId];
+    if (!rec)
+        throw new Error(`Capture not found in state: ${captureId}`);
+    const dl = await getOneFileAnyWithRetry(rec.host, rec.remoteFileCandidates?.length ? rec.remoteFileCandidates : [rec.remoteFilePath], {
+        auth: auth,
+        port: dimePort,
+        timeoutMs: downloadTimeoutMs,
+        pollIntervalMs: downloadPollIntervalMs,
+    });
+    const saved = writeDownloadedFile(dl, outFile);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    captureId,
+                    host: rec.host,
+                    remoteFilePath: dl.filename,
+                    savedPath: saved.filePath,
+                    bytes: saved.bytes,
+                    dimeAttempts: dl.attempts,
+                    dimeWaitedMs: dl.waitedMs,
+                }, null, 2),
+            },
+        ],
+    };
+});
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/packetCapture.js

@@ -1,5 +1,6 @@
 import crypto from "node:crypto";
 import { Client } from "ssh2";
+import { defaultStateStore } from "./state.js";
 function extractCapFilePath(text) {
     if (!text)
         return undefined;
@@ -89,8 +90,39 @@ export function remoteCaptureCandidates(fileBase, maxParts = 10) {
     }
     return out;
 }
+function waitFor(channel, session, predicate, timeoutMs, timeoutMessage) {
+    return new Promise((resolve, reject) => {
+        if (predicate())
+            return resolve();
+        const onData = () => {
+            if (predicate())
+                cleanup(true);
+        };
+        let timer;
+        const cleanup = (ok) => {
+            channel.off("data", onData);
+            channel.stderr.off("data", onData);
+            if (timer)
+                clearTimeout(timer);
+            if (ok)
+                resolve();
+            else {
+                const tail = (session.lastStdout || session.lastStderr || "").slice(-400);
+                reject(new Error(`${timeoutMessage}. lastOutput=${JSON.stringify(tail)}`));
+            }
+        };
+        channel.on("data", onData);
+        channel.stderr.on("data", onData);
+        timer = setTimeout(() => cleanup(false), Math.max(1000, timeoutMs));
+        timer.unref?.();
+    });
+}
 export class PacketCaptureManager {
     active = new Map();
+    state;
+    constructor(opts) {
+        this.state = opts?.state || defaultStateStore();
+    }
     list() {
         return [...this.active.values()].map((a) => a.session);
     }
@@ -114,6 +146,11 @@ export class PacketCaptureManager {
             remoteFilePath: remoteCapturePath(fileBase),
             remoteFileCandidates: remoteCaptureCandidates(fileBase),
         };
+        // Persist early so we can recover/download even if the MCP process restarts.
+        this.state.upsert({
+            ...session,
+            stoppedAt: session.stoppedAt,
+        });
         await new Promise((resolve, reject) => {
             client
                 .on("ready", () => resolve())
@@ -126,8 +163,10 @@ export class PacketCaptureManager {
                 readyTimeout: 15000,
             });
         });
+        // 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) => {
-            client.exec(cmd, { pty: true }, (err, ch) => {
+            client.shell({ term: "vt100", cols: 120, rows: 40 }, (err, ch) => {
                 if (err)
                     return reject(err);
                 resolve(ch);
@@ -135,21 +174,48 @@ export class PacketCaptureManager {
         });
         channel.on("data", (buf) => {
             session.lastStdout = buf.toString("utf8").slice(-2000);
+            this.state.upsert({ ...session, stoppedAt: session.stoppedAt });
         });
         channel.stderr.on("data", (buf) => {
             session.lastStderr = buf.toString("utf8").slice(-2000);
+            this.state.upsert({ ...session, stoppedAt: session.stoppedAt });
         });
         channel.on("close", (code) => {
             session.exitCode = code;
+            session.stoppedAt = session.stoppedAt || new Date().toISOString();
             // If the capture stopped unexpectedly, drop it from the active map.
             this.active.delete(id);
+            this.state.upsert({ ...session, stoppedAt: session.stoppedAt });
             try {
                 client.end();
+                client.destroy();
             }
             catch {
                 // ignore
             }
         });
+        // Wait for prompt before running capture command.
+        try {
+            await waitFor(channel, session, () => looksLikeCucmPrompt(session.lastStdout) || looksLikeCucmPrompt(session.lastStderr), 30_000, "Timeout waiting for CUCM CLI prompt");
+            channel.write(`${cmd}\n`);
+        }
+        catch (e) {
+            try {
+                channel.end();
+                channel.close();
+            }
+            catch {
+                // ignore
+            }
+            try {
+                client.end();
+                client.destroy();
+            }
+            catch {
+                // ignore
+            }
+            throw e;
+        }
         this.active.set(id, { session, client, channel });
         return session;
     }
@@ -159,6 +225,9 @@ export class PacketCaptureManager {
             throw new Error(`Unknown captureId: ${captureId}`);
         const { channel, client, session } = a;
         const done = new Promise((resolve) => {
+            if (looksLikeCucmPrompt(session.lastStdout) || looksLikeCucmPrompt(session.lastStderr)) {
+                return resolve();
+            }
             // CUCM CLI can keep the SSH channel open after the command finishes
             // (it returns to a prompt rather than exiting). Treat prompt as "stopped".
             const onData = () => {
@@ -221,16 +290,27 @@ export class PacketCaptureManager {
             }
         })();
         try {
-            await Promise.race([
-                done,
-                new Promise((_, reject) => setTimeout(() => reject(new Error("Timeout waiting for capture to stop")), resolvedTimeoutMs)),
-            ]);
+            let timer;
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Timeout waiting for capture to stop")), resolvedTimeoutMs);
+                // Don't keep the process alive just because we're waiting.
+                timer.unref?.();
+            });
+            try {
+                await Promise.race([done, timeout]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
         }
         catch (e) {
             // Don't hard-fail: if the CLI doesn't emit a prompt/exit, we still want to:
             // - close SSH resources
             // - let the caller try DIME downloads (.cap, .cap01, etc)
             session.stopTimedOut = true;
+            session.stoppedAt = session.stoppedAt || new Date().toISOString();
+            this.state.upsert({ ...session, stoppedAt: session.stoppedAt });
             try {
                 channel.close();
             }
@@ -239,6 +319,7 @@ export class PacketCaptureManager {
             }
         }
         session.stoppedAt = new Date().toISOString();
+        this.state.upsert({ ...session, stoppedAt: session.stoppedAt });
         // If we're back at a CUCM prompt, try to close the session cleanly.
         if (looksLikeCucmPrompt(session.lastStdout) || looksLikeCucmPrompt(session.lastStderr)) {
             try {
@@ -270,10 +351,12 @@ export class PacketCaptureManager {
                 session.remoteFileCandidates = [inferred, ...session.remoteFileCandidates];
             }
         }
+        this.state.upsert({ ...session, stoppedAt: session.stoppedAt });
         // stop() implies cleanup
         this.active.delete(captureId);
         try {
             client.end();
+            client.destroy();
         }
         catch {
             // ignore

package/dist/state.js

@@ -0,0 +1,117 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+export function defaultStatePath() {
+    // Prefer explicit env var.
+    const envPath = process.env.CUCM_MCP_STATE_PATH;
+    if (envPath && envPath.trim())
+        return envPath.trim();
+    // Default: a git-ignored file in the working directory.
+    // This matches typical MCP dev setup where command runs with --cwd cucm-mcp.
+    return `${process.cwd().replace(/\/+$/, "")}/.cucm-mcp-state.json`;
+}
+export function newEmptyState() {
+    return { version: 1, captures: {} };
+}
+export function nowIso() {
+    return new Date().toISOString();
+}
+export function clampText(s, max = 2000) {
+    if (s == null)
+        return undefined;
+    const t = String(s);
+    if (t.length <= max)
+        return t;
+    return t.slice(t.length - max);
+}
+export function computeExpiresAt({ startedAt, stoppedAt, runningTtlMs, stoppedTtlMs, }) {
+    const base = stoppedAt ? Date.parse(stoppedAt) : Date.parse(startedAt);
+    const ttl = stoppedAt ? stoppedTtlMs : runningTtlMs;
+    const ms = Number.isFinite(base) ? base + ttl : Date.now() + ttl;
+    return new Date(ms).toISOString();
+}
+export function isExpired(rec, atMs = Date.now()) {
+    const exp = Date.parse(rec.expiresAt);
+    if (!Number.isFinite(exp))
+        return false;
+    return exp <= atMs;
+}
+export class CaptureStateStore {
+    path;
+    runningTtlMs;
+    stoppedTtlMs;
+    constructor(opts) {
+        this.path = opts?.path || defaultStatePath();
+        this.runningTtlMs = Math.max(60_000, opts?.runningTtlMs ?? 6 * 60 * 60_000);
+        this.stoppedTtlMs = Math.max(60_000, opts?.stoppedTtlMs ?? 24 * 60 * 60_000);
+    }
+    load() {
+        try {
+            const raw = readFileSync(this.path, "utf8");
+            const parsed = JSON.parse(raw);
+            if (!parsed || parsed.version !== 1 || typeof parsed.captures !== "object")
+                return newEmptyState();
+            return parsed;
+        }
+        catch {
+            return newEmptyState();
+        }
+    }
+    save(state) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        const tmp = `${this.path}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+        renameSync(tmp, this.path);
+    }
+    pruneExpired(state) {
+        const s = state || this.load();
+        const now = Date.now();
+        const captures = {};
+        for (const [k, v] of Object.entries(s.captures || {})) {
+            if (!v || typeof v !== "object")
+                continue;
+            if (isExpired(v, now))
+                continue;
+            captures[k] = v;
+        }
+        return { version: 1, captures };
+    }
+    upsert(rec) {
+        const state = this.pruneExpired(this.load());
+        const updatedAt = nowIso();
+        const expiresAt = computeExpiresAt({
+            startedAt: rec.startedAt,
+            stoppedAt: rec.stoppedAt,
+            runningTtlMs: this.runningTtlMs,
+            stoppedTtlMs: this.stoppedTtlMs,
+        });
+        state.captures[rec.id] = {
+            ...rec,
+            lastStdout: clampText(rec.lastStdout),
+            lastStderr: clampText(rec.lastStderr),
+            updatedAt,
+            expiresAt,
+        };
+        this.save(state);
+    }
+    remove(id) {
+        const state = this.load();
+        if (state.captures?.[id]) {
+            delete state.captures[id];
+            this.save(state);
+        }
+    }
+}
+export function defaultStateStore() {
+    // Allow env tuning.
+    const running = process.env.CUCM_MCP_CAPTURE_RUNNING_TTL_MS
+        ? Number.parseInt(process.env.CUCM_MCP_CAPTURE_RUNNING_TTL_MS, 10)
+        : undefined;
+    const stopped = process.env.CUCM_MCP_CAPTURE_STOPPED_TTL_MS
+        ? Number.parseInt(process.env.CUCM_MCP_CAPTURE_STOPPED_TTL_MS, 10)
+        : undefined;
+    return new CaptureStateStore({
+        path: defaultStatePath(),
+        runningTtlMs: Number.isFinite(running) ? running : undefined,
+        stoppedTtlMs: Number.isFinite(stopped) ? stopped : undefined,
+    });
+}

package/package.json

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