denpex-mcp 0.2.18 → 0.2.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +168 -168
  2. package/dist/index.js +3571 -3441
  3. package/package.json +65 -65
package/README.md CHANGED
@@ -1,168 +1,168 @@
1
- # Denpex MCP server
2
-
3
- Diagnose GPU/ML training failures. CUDA OOM, NCCL timeouts, Xid faults, NaN loss,
4
- checkpoint corruption, **without leaving your AI tool**. Ask Claude Desktop, Cursor,
5
- or Claude Code to *"diagnose the crash in `./logs/train.err`"* and Denpex reads the log
6
- straight off disk and hands back the root cause and the fix.
7
-
8
- - 🩺 **Root cause + escalating fix** (primary → fallback → emergency), verification command, and prevention.
9
- - 🧭 **Find the culprit rank** in a distributed/NCCL hang, and route GPU Xid faults to the right node action, offline, instantly.
10
- - 📚 **Bundled failure encyclopedia** (500+ documented classes) searchable by error code or symptom.
11
- - 🔒 **Zero-egress mode** (`DENPEX_LOCAL=1`): diagnose entirely on-host, nothing leaves the machine. Plus client-side PII scrubbing even in cloud mode.
12
-
13
- ---
14
-
15
- ## Quick start (60 seconds)
16
-
17
- ### 1. Get an API key (optional but recommended)
18
-
19
- Sign in at **[denpex.com/dashboard](https://denpex.com/dashboard) → API Keys** and create a key (`dpx_…`).
20
- The key unlocks authenticated cloud diagnosis, your diagnosis history, quota, and fleet
21
- incidents. *Without a key, the first `diagnose_crash` cloud run is frictionless and uses
22
- the same canonical anonymous engine as the homepage. Later new anonymous diagnoses need
23
- the browser check at [denpex.com](https://denpex.com/#instant-diagnosis), which MCP cannot
24
- complete, or an API key. Anonymous clarifications reuse the server-issued, log-bound
25
- refinement token automatically (or accept it explicitly after an MCP restart), so
26
- answering Denpex does not spend another diagnosis and cannot be forged with a public
27
- boolean header. Set `DENPEX_LOCAL=1` explicitly for zero-egress;
28
- `lookup_failure` and `analyze_cascade` remain available from the bundled offline data.*
29
-
30
- ### 2. Add it to your client
31
-
32
- <details open>
33
- <summary><b>Claude Desktop</b></summary>
34
-
35
- Edit `claude_desktop_config.json`
36
- (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
37
-
38
- ```json
39
- {
40
- "mcpServers": {
41
- "denpex": {
42
- "command": "npx",
43
- "args": ["-y", "denpex-mcp"],
44
- "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
45
- }
46
- }
47
- }
48
- ```
49
- Restart Claude Desktop.
50
- </details>
51
-
52
- <details>
53
- <summary><b>Cursor</b></summary>
54
-
55
- Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
56
-
57
- ```json
58
- {
59
- "mcpServers": {
60
- "denpex": {
61
- "command": "npx",
62
- "args": ["-y", "denpex-mcp"],
63
- "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
64
- }
65
- }
66
- }
67
- ```
68
- </details>
69
-
70
- <details>
71
- <summary><b>Claude Code</b></summary>
72
-
73
- ```bash
74
- claude mcp add denpex -e DENPEX_API_KEY=dpx_your_key_here -- npx -y denpex-mcp
75
- ```
76
- </details>
77
-
78
- ### 3. Use it
79
-
80
- > "My training job crashed, diagnose the log at `./logs/rank0.err`."
81
- > "What does Xid 79 mean?"
82
- > "This 64-GPU run is hung. Which rank failed first?" *(→ `analyze_cascade`)*
83
-
84
- Or pick the **`diagnose-training-crash`** prompt your client surfaces.
85
-
86
- ---
87
-
88
- ## Offline / air-gapped mode
89
-
90
- Diagnose entirely on-host, no network, no logs leaving the cluster. Ideal for VPCs,
91
- secure data centers, and privacy-sensitive labs. Add `DENPEX_LOCAL=1`:
92
-
93
- ```json
94
- { "mcpServers": { "denpex": {
95
- "command": "npx", "args": ["-y", "denpex-mcp"],
96
- "env": { "DENPEX_LOCAL": "1" }
97
- } } }
98
- ```
99
-
100
- The package bundles the same canonical deterministic diagnosis pipeline used by the hosted
101
- wrapper: 10,700+ patterns, causal detectors and contradiction gates, Xid routing, cross-rank
102
- cascade localization, and the 500+ class encyclopedia. It returns the initiating rank/node
103
- when the evidence identifies one. Only the hosted LLM fallback and live-research enrichment
104
- are unavailable offline.
105
-
106
- ---
107
-
108
- ## Tools
109
-
110
- | Tool | What it does | Needs |
111
- |------|--------------|-------|
112
- | `diagnose_crash` | Root cause + escalating fix from `logs` / `file` / `dir`. Also accepts `telemetry` (dmesg / nvidia-smi / ibstat), `codeContext`, `topologyMap`, typed `operatorAnswers`, and (after an anonymous MCP restart) the prior `refinementToken`. | canonical cloud by default; explicit offline mode |
113
- | `lookup_failure` | Search the bundled encyclopedia (500+ classes) by code/keyword/symptom. | works offline |
114
- | `analyze_cascade` | Find the culprit rank in a distributed hang; route Xid faults. | works offline |
115
- | `submit_fix_outcome` | Report whether a fix worked. **This is what makes the next diagnosis better.** | API key |
116
- | `check_quota` | Your plan and remaining diagnoses this month. | API key |
117
- | `recent_diagnoses` | Recall your recent diagnoses and their fixes. | API key |
118
- | `ask_followup` | Conversational follow-up on a diagnosis. | Team plan / trial |
119
- | `check_versions` | Flag known-bad CUDA/PyTorch/NCCL/driver combos. | Team plan / trial |
120
- | `compare_runs` | "It worked yesterday", isolate what changed between a good run and a bad one. | Team plan / trial |
121
- | `diff_environments` | Diff torch/CUDA/NCCL/driver versions and env vars between two runs. | Team plan / trial |
122
- | `validate_checkpoint` | Find the newest checkpoint that is actually safe to resume from. | Team plan / trial |
123
- | `preflight_check` | "Is this cluster safe to launch on?", blockers before you burn GPU-hours. | Scale plan |
124
- | `node_health` | Score every monitored node, worst first. | Scale plan |
125
- | `predict_failures` | Nodes trending toward a failure that has not happened yet. | Scale plan |
126
- | `list_incidents` | Incidents Denpex's monitor caught & escalated on your fleet. | Scale plan |
127
-
128
- Gated tools degrade gracefully, they tell you exactly which plan unlocks them and which
129
- tools work on your current plan. The failure encyclopedia is also exposed as resources at
130
- `denpex://failures/{slug}`.
131
-
132
- **Structured output.** Every tool above returns `structuredContent` alongside its
133
- markdown, validated against a declared output schema, so an agent branches on
134
- `confidenceBand === "low"` or iterates `rankedHypotheses` instead of regexing prose.
135
- Two fields deserve attention when you write the agent loop:
136
-
137
- - **`confidence: null`** does not mean zero. It means the engine measured this band's
138
- historical accuracy and declined to state a number. Treat the verdict as a lead. Do
139
- not substitute the raw score.
140
- - **`unfalsified: true`** identifies only the explicitly enabled reduced compatibility
141
- fallback, where the canonical contradiction graph did not run. Normal cloud and
142
- `DENPEX_LOCAL=1` diagnosis both use the canonical engine and set it to false.
143
-
144
- ---
145
-
146
- ## Environment variables
147
-
148
- | Variable | Default | Purpose |
149
- |----------|---------|---------|
150
- | `DENPEX_API_KEY` |, | Your `dpx_…` key. Enables cloud tools. |
151
- | `DENPEX_API_URL` | `https://api.denpex.com` | Override the API base (self-host / staging). |
152
- | `DENPEX_LOCAL` | `0` | `1` → diagnose entirely on-host (zero egress). |
153
- | `DENPEX_PRIVACY` | `off` | `mask` / `strict` → scrub PII from logs **before** they leave the machine. |
154
-
155
- ---
156
-
157
- ## Develop
158
-
159
- ```bash
160
- npm install
161
- npm run build # regenerates the canonical engine + corpus, then bundles dist/index.js
162
- npm test # 111 unit + protocol-integration tests
163
- npm run inspector # interactive protocol inspector (MCP Inspector)
164
- ```
165
-
166
- The offline corpus (`src/data/denpex_patterns.json`) and canonical engine
167
- (`src/offline/canonical-engine.mjs`) are generated from the repo's single source of truth
168
- during `npm run build`, never hand-edit either artifact.
1
+ # Denpex MCP server
2
+
3
+ Diagnose GPU/ML training failures. CUDA OOM, NCCL timeouts, Xid faults, NaN loss,
4
+ checkpoint corruption, **without leaving your AI tool**. Ask Claude Desktop, Cursor,
5
+ or Claude Code to *"diagnose the crash in `./logs/train.err`"* and Denpex reads the log
6
+ straight off disk and hands back the root cause and the fix.
7
+
8
+ - 🩺 **Root cause + escalating fix** (primary → fallback → emergency), verification command, and prevention.
9
+ - 🧭 **Find the culprit rank** in a distributed/NCCL hang, and route GPU Xid faults to the right node action, offline, instantly.
10
+ - 📚 **Bundled failure encyclopedia** (500+ documented classes) searchable by error code or symptom.
11
+ - 🔒 **Zero-egress mode** (`DENPEX_LOCAL=1`): diagnose entirely on-host, nothing leaves the machine. Plus client-side PII scrubbing even in cloud mode.
12
+
13
+ ---
14
+
15
+ ## Quick start (60 seconds)
16
+
17
+ ### 1. Get an API key (optional but recommended)
18
+
19
+ Sign in at **[denpex.com/dashboard](https://denpex.com/dashboard) → API Keys** and create a key (`dpx_…`).
20
+ The key unlocks authenticated cloud diagnosis, your diagnosis history, quota, and fleet
21
+ incidents. *Without a key, the first `diagnose_crash` cloud run is frictionless and uses
22
+ the same canonical anonymous engine as the homepage. Later new anonymous diagnoses need
23
+ the browser check at [denpex.com](https://denpex.com/#instant-diagnosis), which MCP cannot
24
+ complete, or an API key. Anonymous clarifications reuse the server-issued, log-bound
25
+ refinement token automatically (or accept it explicitly after an MCP restart), so
26
+ answering Denpex does not spend another diagnosis and cannot be forged with a public
27
+ boolean header. Set `DENPEX_LOCAL=1` explicitly for zero-egress;
28
+ `lookup_failure` and `analyze_cascade` remain available from the bundled offline data.*
29
+
30
+ ### 2. Add it to your client
31
+
32
+ <details open>
33
+ <summary><b>Claude Desktop</b></summary>
34
+
35
+ Edit `claude_desktop_config.json`
36
+ (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
37
+
38
+ ```json
39
+ {
40
+ "mcpServers": {
41
+ "denpex": {
42
+ "command": "npx",
43
+ "args": ["-y", "denpex-mcp"],
44
+ "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
45
+ }
46
+ }
47
+ }
48
+ ```
49
+ Restart Claude Desktop.
50
+ </details>
51
+
52
+ <details>
53
+ <summary><b>Cursor</b></summary>
54
+
55
+ Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
56
+
57
+ ```json
58
+ {
59
+ "mcpServers": {
60
+ "denpex": {
61
+ "command": "npx",
62
+ "args": ["-y", "denpex-mcp"],
63
+ "env": { "DENPEX_API_KEY": "dpx_your_key_here" }
64
+ }
65
+ }
66
+ }
67
+ ```
68
+ </details>
69
+
70
+ <details>
71
+ <summary><b>Claude Code</b></summary>
72
+
73
+ ```bash
74
+ claude mcp add denpex -e DENPEX_API_KEY=dpx_your_key_here -- npx -y denpex-mcp
75
+ ```
76
+ </details>
77
+
78
+ ### 3. Use it
79
+
80
+ > "My training job crashed, diagnose the log at `./logs/rank0.err`."
81
+ > "What does Xid 79 mean?"
82
+ > "This 64-GPU run is hung. Which rank failed first?" *(→ `analyze_cascade`)*
83
+
84
+ Or pick the **`diagnose-training-crash`** prompt your client surfaces.
85
+
86
+ ---
87
+
88
+ ## Offline / air-gapped mode
89
+
90
+ Diagnose entirely on-host, no network, no logs leaving the cluster. Ideal for VPCs,
91
+ secure data centers, and privacy-sensitive labs. Add `DENPEX_LOCAL=1`:
92
+
93
+ ```json
94
+ { "mcpServers": { "denpex": {
95
+ "command": "npx", "args": ["-y", "denpex-mcp"],
96
+ "env": { "DENPEX_LOCAL": "1" }
97
+ } } }
98
+ ```
99
+
100
+ The package bundles the same canonical deterministic diagnosis pipeline used by the hosted
101
+ wrapper: 10,700+ patterns, causal detectors and contradiction gates, Xid routing, cross-rank
102
+ cascade localization, and the 500+ class encyclopedia. It returns the initiating rank/node
103
+ when the evidence identifies one. Only the hosted LLM fallback and live-research enrichment
104
+ are unavailable offline.
105
+
106
+ ---
107
+
108
+ ## Tools
109
+
110
+ | Tool | What it does | Needs |
111
+ |------|--------------|-------|
112
+ | `diagnose_crash` | Root cause + escalating fix from `logs` / `file` / `dir`. Also accepts `telemetry` (dmesg / nvidia-smi / ibstat), `codeContext`, `topologyMap`, typed `operatorAnswers`, and (after an anonymous MCP restart) the prior `refinementToken`. | canonical cloud by default; explicit offline mode |
113
+ | `lookup_failure` | Search the bundled encyclopedia (500+ classes) by code/keyword/symptom. | works offline |
114
+ | `analyze_cascade` | Find the culprit rank in a distributed hang; route Xid faults. | works offline |
115
+ | `submit_fix_outcome` | Report whether a fix worked. **This is what makes the next diagnosis better.** | API key |
116
+ | `check_quota` | Your plan and remaining diagnoses this month. | API key |
117
+ | `recent_diagnoses` | Recall your recent diagnoses and their fixes. | API key |
118
+ | `ask_followup` | Conversational follow-up on a diagnosis. | Team plan / trial |
119
+ | `check_versions` | Flag known-bad CUDA/PyTorch/NCCL/driver combos. | Team plan / trial |
120
+ | `compare_runs` | "It worked yesterday", isolate what changed between a good run and a bad one. | Team plan / trial |
121
+ | `diff_environments` | Diff torch/CUDA/NCCL/driver versions and env vars between two runs. | Team plan / trial |
122
+ | `validate_checkpoint` | Find the newest checkpoint that is actually safe to resume from. | Team plan / trial |
123
+ | `preflight_check` | "Is this cluster safe to launch on?", blockers before you burn GPU-hours. | Scale plan |
124
+ | `node_health` | Score every monitored node, worst first. | Scale plan |
125
+ | `predict_failures` | Nodes trending toward a failure that has not happened yet. | Scale plan |
126
+ | `list_incidents` | Incidents Denpex's monitor caught & escalated on your fleet. | Scale plan |
127
+
128
+ Gated tools degrade gracefully, they tell you exactly which plan unlocks them and which
129
+ tools work on your current plan. The failure encyclopedia is also exposed as resources at
130
+ `denpex://failures/{slug}`.
131
+
132
+ **Structured output.** Every tool above returns `structuredContent` alongside its
133
+ markdown, validated against a declared output schema, so an agent branches on
134
+ `confidenceBand === "low"` or iterates `rankedHypotheses` instead of regexing prose.
135
+ Two fields deserve attention when you write the agent loop:
136
+
137
+ - **`confidence: null`** does not mean zero. It means the engine measured this band's
138
+ historical accuracy and declined to state a number. Treat the verdict as a lead. Do
139
+ not substitute the raw score.
140
+ - **`unfalsified: true`** identifies only the explicitly enabled reduced compatibility
141
+ fallback, where the canonical contradiction graph did not run. Normal cloud and
142
+ `DENPEX_LOCAL=1` diagnosis both use the canonical engine and set it to false.
143
+
144
+ ---
145
+
146
+ ## Environment variables
147
+
148
+ | Variable | Default | Purpose |
149
+ |----------|---------|---------|
150
+ | `DENPEX_API_KEY` |, | Your `dpx_…` key. Enables cloud tools. |
151
+ | `DENPEX_API_URL` | `https://api.denpex.com` | Override the API base (self-host / staging). |
152
+ | `DENPEX_LOCAL` | `0` | `1` → diagnose entirely on-host (zero egress). |
153
+ | `DENPEX_PRIVACY` | `off` | `mask` / `strict` → scrub PII from logs **before** they leave the machine. |
154
+
155
+ ---
156
+
157
+ ## Develop
158
+
159
+ ```bash
160
+ npm install
161
+ npm run build # regenerates the canonical engine + corpus, then bundles dist/index.js
162
+ npm test # 111 unit + protocol-integration tests
163
+ npm run inspector # interactive protocol inspector (MCP Inspector)
164
+ ```
165
+
166
+ The offline corpus (`src/data/denpex_patterns.json`) and canonical engine
167
+ (`src/offline/canonical-engine.mjs`) are generated from the repo's single source of truth
168
+ during `npm run build`, never hand-edit either artifact.