denpex-mcp 0.1.0 → 0.2.0

package/README.md

@@ -7,7 +7,7 @@ straight off disk and hands back the root cause and the fix.
 
 - 🩺 **Root cause + escalating fix** (primary → fallback → emergency), verification command, and prevention.
 - 🧭 **Find the culprit rank** in a distributed/NCCL hang, and route GPU Xid faults to the right node action — offline, instantly.
-- 📚 **312-class failure encyclopedia** searchable by error code or symptom.
+- 📚 **Bundled failure encyclopedia** (300+ classes offline; the full corpus runs online) searchable by error code or symptom.
 - 🔒 **Zero-egress mode** (`DENPEX_LOCAL=1`): diagnose entirely on-host, nothing leaves the machine. Plus client-side PII scrubbing even in cloud mode.
 
 ---
@@ -17,9 +17,10 @@ straight off disk and hands back the root cause and the fix.
 ### 1. Get an API key (optional but recommended)
 
 Sign in at **[denpex.com/dashboard](https://denpex.com/dashboard) → API Keys** and create a key (`dpx_…`).
-The key unlocks the cloud LLM fallback on novel errors, your diagnosis history, quota, and
-fleet incidents. *Without a key, `diagnose_crash`, `lookup_failure`, and `analyze_cascade`
-still work fully offline.*
+The key unlocks authenticated cloud diagnosis, your diagnosis history, quota, and fleet
+incidents. *Without a key, `diagnose_crash` uses the same canonical anonymous engine as
+the homepage's three free diagnoses. Set `DENPEX_LOCAL=1` explicitly for zero-egress;
+`lookup_failure` and `analyze_cascade` remain available from the bundled offline data.*
 
 ### 2. Add it to your client
 
@@ -91,8 +92,9 @@ secure data centers, and privacy-sensitive labs. Add `DENPEX_LOCAL=1`:
 } } }
 ```
 
-The bundled engine (31 fast patterns + the 312-class encyclopedia + Xid routing + cascade
-localization) covers the overwhelming majority of real failures. The LLM fallback for novel
+The bundled engine (fast patterns + a 300+-class encyclopedia snapshot + Xid routing + cascade
+localization) covers the common failure classes; the full, continuously-grown corpus and the
+deep-analysis tiers run online. The LLM fallback for novel
 errors is cloud-only and simply unavailable offline.
 
 ---
@@ -101,19 +103,39 @@ errors is cloud-only and simply unavailable offline.
 
 | Tool | What it does | Needs |
 |------|--------------|-------|
-| `diagnose_crash` | Root cause + escalating fix from `logs` / `file` / `dir`. | works offline |
-| `lookup_failure` | Search the 312-class encyclopedia by code/keyword/symptom. | works offline |
+| `diagnose_crash` | Root cause + escalating fix from `logs` / `file` / `dir`. Also accepts `telemetry` (dmesg / nvidia-smi / ibstat), `codeContext` and `topologyMap`. | canonical cloud by default; explicit offline mode |
+| `lookup_failure` | Search the bundled encyclopedia (300+ classes) by code/keyword/symptom. | works offline |
 | `analyze_cascade` | Find the culprit rank in a distributed hang; route Xid faults. | works offline |
+| `submit_fix_outcome` | Report whether a fix worked. **This is what makes the next diagnosis better.** | API key |
 | `check_quota` | Your plan and remaining diagnoses this month. | API key |
 | `recent_diagnoses` | Recall your recent diagnoses and their fixes. | API key |
 | `ask_followup` | Conversational follow-up on a diagnosis. | Team plan / trial |
 | `check_versions` | Flag known-bad CUDA/PyTorch/NCCL/driver combos. | Team plan / trial |
+| `compare_runs` | "It worked yesterday" — isolate what changed between a good run and a bad one. | Team plan / trial |
+| `diff_environments` | Diff torch/CUDA/NCCL/driver versions and env vars between two runs. | Team plan / trial |
+| `validate_checkpoint` | Find the newest checkpoint that is actually safe to resume from. | Team plan / trial |
+| `preflight_check` | "Is this cluster safe to launch on?" — blockers before you burn GPU-hours. | Scale plan |
+| `node_health` | Score every monitored node, worst first. | Scale plan |
+| `predict_failures` | Nodes trending toward a failure that has not happened yet. | Scale plan |
 | `list_incidents` | Incidents Denpex's monitor caught & escalated on your fleet. | Scale plan |
 
 Gated tools degrade gracefully — they tell you exactly which plan unlocks them and which
 tools work on your current plan. The failure encyclopedia is also exposed as resources at
 `denpex://failures/{slug}`.
 
+**Structured output.** Every tool above returns `structuredContent` alongside its
+markdown, validated against a declared output schema — so an agent branches on
+`confidenceBand === "low"` or iterates `rankedHypotheses` instead of regexing prose.
+Two fields deserve attention when you write the agent loop:
+
+- **`confidence: null`** does not mean zero. It means the engine measured this band's
+  historical accuracy and declined to state a number. Treat the verdict as a lead. Do
+  not substitute the raw score.
+- **`unfalsified: true`** means no falsification contract ran on the verdict. It is
+  always true offline (the offline engine has no contract layer), so an offline
+  `GPU_XID_ECC` has *not* been checked against telemetry that would contradict it.
+  Confirm before you drain a node or file an RMA.
+
 ---
 
 ## Environment variables
@@ -132,7 +154,7 @@ tools work on your current plan. The failure encyclopedia is also exposed as res
 ```bash
 npm install
 npm run build      # regenerates the offline corpus, then bundles dist/index.js
-npm test           # 48 unit + protocol-integration tests
+npm test           # 88 unit + protocol-integration tests
 npm run inspector  # interactive protocol inspector (MCP Inspector)
 ```