@calltelemetry/cucm-mcp 0.1.6 → 0.1.7

package/README.md

@@ -90,3 +90,51 @@ 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`, ...)
+
+### 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/index.js

@@ -14,7 +14,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.7" });
 const captures = new PacketCaptureManager();
 const captureState = defaultStateStore();
 const dimeAuthSchema = z
@@ -187,14 +187,20 @@ server.tool("packet_capture_stop_and_download", "Stop a packet capture and downl
     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,15 +209,29 @@ 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);
     return {
@@ -223,6 +243,7 @@ server.tool("packet_capture_stop_and_download", "Stop a packet capture and downl
                     host: stopped.host,
                     remoteFilePath: dl.filename,
                     stopTimedOut: stopped.stopTimedOut || false,
+                    stopError,
                     savedPath: saved.filePath,
                     bytes: saved.bytes,
                     dimeAttempts: dl.attempts,

package/package.json

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