denpex-mcp 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# Denpex MCP server
+
+Diagnose GPU/ML training failures — CUDA OOM, NCCL timeouts, Xid faults, NaN loss,
+checkpoint corruption — **without leaving your AI tool**. Ask Claude Desktop, Cursor,
+or Claude Code to *"diagnose the crash in `./logs/train.err`"* and Denpex reads the log
+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.
+- 🔒 **Zero-egress mode** (`DENPEX_LOCAL=1`): diagnose entirely on-host, nothing leaves the machine. Plus client-side PII scrubbing even in cloud mode.
+
+---
+
+## Quick start (60 seconds)
+
+### 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.*
+
+### 2. Add it to your client
+
+<details open>
+<summary><b>Claude Desktop</b></summary>
+
+Edit `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "denpex": {
+      "command": "npx",
+      "args": ["-y", "denpex-mcp"],
+      "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
+    }
+  }
+}
+```
+Restart Claude Desktop.
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "denpex": {
+      "command": "npx",
+      "args": ["-y", "denpex-mcp"],
+      "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add denpex -e DENPEX_API_KEY=dpx_your_key_here -- npx -y denpex-mcp
+```
+</details>
+
+### 3. Use it
+
+> "My training job crashed — diagnose the log at `./logs/rank0.err`."
+> "What does Xid 79 mean?"
+> "This 64-GPU run is hung. Which rank failed first?"  *(→ `analyze_cascade`)*
+
+Or pick the **`diagnose-training-crash`** prompt your client surfaces.
+
+---
+
+## Offline / air-gapped mode
+
+Diagnose entirely on-host — no network, no logs leaving the cluster. Ideal for VPCs,
+secure data centers, and privacy-sensitive labs. Add `DENPEX_LOCAL=1`:
+
+```json
+{ "mcpServers": { "denpex": {
+  "command": "npx", "args": ["-y", "denpex-mcp"],
+  "env": { "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
+errors is cloud-only and simply unavailable offline.
+
+---
+
+## Tools
+
+| 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 |
+| `analyze_cascade` | Find the culprit rank in a distributed hang; route Xid faults. | works offline |
+| `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 |
+| `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}`.
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `DENPEX_API_KEY` | — | Your `dpx_…` key. Enables cloud tools. |
+| `DENPEX_API_URL` | `https://api.denpex.com` | Override the API base (self-host / staging). |
+| `DENPEX_LOCAL` | `0` | `1` → diagnose entirely on-host (zero egress). |
+| `DENPEX_PRIVACY` | `off` | `mask` / `strict` → scrub PII from logs **before** they leave the machine. |
+
+---
+
+## Develop
+
+```bash
+npm install
+npm run build      # regenerates the offline corpus, then bundles dist/index.js
+npm test           # 48 unit + protocol-integration tests
+npm run inspector  # interactive protocol inspector (MCP Inspector)
+```
+
+The offline corpus (`src/data/denpex_patterns.json`) is generated from the repo's single
+source of truth via `npm run bundle:patterns` — never hand-edit it.