fix: graceful CTI empty state, expanded README use cases

- cti_status now returns friendly empty result when CUCM has no CTI
  apps connected (instead of propagating SOAP 500 'unknown' fault)
- README expanded with 20+ real-world use cases organized by category:
  troubleshooting, capacity, health, inventory

Author: calltelemetry-jason

README.md

@@ -11,9 +11,32 @@ An [MCP](https://modelcontextprotocol.io/) server that gives AI assistants direc
 
 **You ask about your cluster in plain language. The LLM queries RIS and PerfMon for you.**
 
-- *"Are all phones registered?"*
+### Troubleshooting & Triage
+- *"Are all phones registered? Which ones aren't?"*
+- *"Find all phones on subnet 10.1.5.x — are any unregistered?"*
+- *"Is SEP001122334455 registered? What node is it on? What's its IP?"*
+- *"Show me all rejected phones and their rejection reasons"*
+- *"Which CUCM node has the most unregistered devices?"*
+
+### Capacity & Performance
 - *"Show me call volume over the last 5 minutes"*
+- *"How many MTP and transcoder resources are available?"*
+- *"Are we running low on conference bridge resources?"*
+- *"What's the CPU utilization on the publisher?"*
+- *"Monitor SIP trunk call activity for the next 2 minutes"*
+
+### Health & Situational Awareness
 - *"Is the cluster healthy?"*
+- *"Give me a registration breakdown by protocol — how many SIP vs SCCP?"*
+- *"How many Jabber clients are connected via MRA?"*
+- *"Are any CTI applications connected? What's their status?"*
+- *"Compare registration counts to what CUCM thinks is registered via PerfMon"*
+
+### Inventory & Reporting
+- *"How many phones are registered by model/firmware?"*
+- *"List all registered hardware phones and their IPs"*
+- *"What PerfMon counters are available on this cluster?"*
+- *"Show me all instances of Cisco SIP trunk counters"*
 
 ## Installation
 

src/tools/device-tools.ts

@@ -156,15 +156,24 @@ export async function handleDeviceTool(name: string, args: Record<string, unknow
     }
 
     if (name === "cti_status") {
-      const result = await selectCtiItem(creds, {
-        ctiMgrClass: args.ctiMgrClass as string | undefined,
-        maxItems: args.maxItems as number | undefined,
-        appId: args.appId as string | undefined,
-        nodeName: args.nodeName as string | undefined,
-        status: args.status as string | undefined,
-        timeoutMs: args.timeoutMs as number | undefined,
-      });
-      return jsonResponse(result);
+      try {
+        const result = await selectCtiItem(creds, {
+          ctiMgrClass: args.ctiMgrClass as string | undefined,
+          maxItems: args.maxItems as number | undefined,
+          appId: args.appId as string | undefined,
+          nodeName: args.nodeName as string | undefined,
+          status: args.status as string | undefined,
+          timeoutMs: args.timeoutMs as number | undefined,
+        });
+        return jsonResponse(result);
+      } catch (ctiErr) {
+        // CUCM returns SOAP 500 "unknown" when no CTI apps are connected — not a real error
+        const msg = ctiErr instanceof Error ? ctiErr.message : String(ctiErr);
+        if (/500.*unknown|unknown.*500/i.test(msg)) {
+          return jsonResponse({ totalItemsFound: 0, items: [], note: "No CTI applications connected to cluster. Start a JTAPI/TAPI provider to see CTI status." });
+        }
+        throw ctiErr;
+      }
     }
 
     return { content: [{ type: "text", text: `Unknown device tool: ${name}` }], isError: true };