@infinitedusky/indusk-mcp 1.4.5 → 1.5.0

package/dist/bin/commands/extensions.js

@@ -95,7 +95,6 @@ export async function extensionsEnable(projectRoot, names) {
             console.info(`  ${name}: enabled (built-in)`);
             runHook(projectRoot, name, "on_init");
             installSkill(projectRoot, name);
-            installMcpServer(projectRoot, name);
             continue;
         }
         console.info(`  ${name}: not found — use 'extensions add ${name} --from <source>' for third-party`);
@@ -466,54 +465,6 @@ function runHook(projectRoot, name, hook) {
         console.info(`  ${name}: ${hook} hook failed`);
     }
 }
-function installMcpServer(projectRoot, name) {
-    const extPath = join(extensionsDir(projectRoot), `${name}.json`);
-    const manifest = loadExtension(extPath);
-    if (!manifest?.mcp_server)
-        return;
-    const mcpJsonPath = join(projectRoot, ".mcp.json");
-    let mcpConfig = {};
-    if (existsSync(mcpJsonPath)) {
-        try {
-            mcpConfig = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
-        }
-        catch {
-            mcpConfig = {};
-        }
-    }
-    if (!mcpConfig.mcpServers)
-        mcpConfig.mcpServers = {};
-    if (mcpConfig.mcpServers[name]) {
-        console.info(`  ${name}: .mcp.json entry already exists`);
-    }
-    else {
-        const serverConfig = {};
-        const srv = manifest.mcp_server;
-        if (srv.type)
-            serverConfig.type = srv.type;
-        if (srv.url)
-            serverConfig.url = srv.url;
-        if (srv.command)
-            serverConfig.command = srv.command;
-        if (srv.args)
-            serverConfig.args = srv.args;
-        if (srv.headers)
-            serverConfig.headers = srv.headers;
-        if (srv.env)
-            serverConfig.env = srv.env;
-        mcpConfig.mcpServers[name] = serverConfig;
-        writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, "\t") + "\n");
-        console.info(`  ${name}: added to .mcp.json`);
-    }
-    // Print setup instructions if any
-    if (manifest.mcp_server.setup_instructions) {
-        console.info(`\n  Setup required for ${name}:`);
-        for (const instruction of manifest.mcp_server.setup_instructions) {
-            console.info(`    ${instruction}`);
-        }
-        console.info("");
-    }
-}
 function installSkill(projectRoot, name) {
     const extPath = join(extensionsDir(projectRoot), `${name}.json`);
     const manifest = loadExtension(extPath);

package/dist/bin/commands/init.js

@@ -17,6 +17,20 @@ function run(cmd, options) {
         return "";
     }
 }
+function ensureGitignoreMcpJson(projectRoot) {
+    const gitignorePath = join(projectRoot, ".gitignore");
+    if (existsSync(gitignorePath)) {
+        const content = readFileSync(gitignorePath, "utf-8");
+        if (content.includes(".mcp.json"))
+            return;
+        writeFileSync(gitignorePath, `${content.trimEnd()}\n\n# MCP config (contains auth tokens)\n.mcp.json\n`);
+        console.info("  updated: .gitignore (added .mcp.json)");
+    }
+    else {
+        writeFileSync(gitignorePath, "# MCP config (contains auth tokens)\n.mcp.json\n");
+        console.info("  created: .gitignore (with .mcp.json)");
+    }
+}
 function createCgcIgnore(projectRoot) {
     const ignorePath = join(projectRoot, ".cgcignore");
     if (existsSync(ignorePath)) {
@@ -101,56 +115,45 @@ export async function init(projectRoot, options = {}) {
         mkdirSync(planningDir, { recursive: true });
         console.info("  create: planning/");
     }
-    // 4. Set up .mcp.json with both indusk and codegraphcontext
+    // 4. Set up MCP servers via claude mcp add
     console.info("\n[MCP config]");
+    // Check which servers already exist
     const mcpJsonPath = join(projectRoot, ".mcp.json");
-    const induskEntry = {
-        command: "npx",
-        args: ["@infinitedusky/indusk-mcp", "serve"],
-        env: { PROJECT_ROOT: "." },
-    };
-    const cgcEntry = {
-        command: "cgc",
-        args: ["mcp", "start"],
-        env: {
-            DATABASE_TYPE: "falkordb-remote",
-            FALKORDB_HOST: "falkordb.orb.local",
-            FALKORDB_GRAPH_NAME: projectName,
-        },
-    };
+    let existingServers = new Set();
     if (existsSync(mcpJsonPath)) {
-        const existing = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
-        let updated = false;
-        existing.mcpServers = existing.mcpServers || {};
-        if (!existing.mcpServers.indusk || force) {
-            existing.mcpServers.indusk = induskEntry;
-            console.info(`  ${existing.mcpServers.indusk ? "overwrite" : "add"}: .mcp.json indusk entry`);
-            updated = true;
+        try {
+            const existing = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
+            existingServers = new Set(Object.keys(existing.mcpServers || {}));
         }
-        else {
-            console.info("  skip: .mcp.json indusk entry (already exists)");
+        catch { }
+    }
+    // Add indusk MCP server (no secrets)
+    if (!existingServers.has("indusk") || force) {
+        try {
+            execSync(`claude mcp add -t stdio -s project -e PROJECT_ROOT=. -- indusk npx @infinitedusky/indusk-mcp serve`, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
+            console.info("  added: indusk MCP server (via claude mcp add)");
         }
-        if (!existing.mcpServers.codegraphcontext || force) {
-            existing.mcpServers.codegraphcontext = cgcEntry;
-            console.info(`  ${existing.mcpServers.codegraphcontext ? "overwrite" : "add"}: .mcp.json codegraphcontext (graph: ${projectName})`);
-            updated = true;
+        catch {
+            console.info("  failed: could not add indusk MCP server — run manually:");
+            console.info('    claude mcp add -t stdio -s project -e PROJECT_ROOT=. -- indusk npx @infinitedusky/indusk-mcp serve');
         }
-        else {
-            console.info("  skip: .mcp.json codegraphcontext entry (already exists)");
+    }
+    else {
+        console.info("  skip: indusk MCP server (already exists)");
+    }
+    // Add codegraphcontext MCP server (no secrets)
+    if (!existingServers.has("codegraphcontext") || force) {
+        try {
+            execSync(`claude mcp add -t stdio -s project -e DATABASE_TYPE=falkordb-remote -e FALKORDB_HOST=falkordb.orb.local -e FALKORDB_GRAPH_NAME=${projectName} -- codegraphcontext cgc mcp start`, { cwd: projectRoot, stdio: "pipe", timeout: 10000 });
+            console.info(`  added: codegraphcontext MCP server (graph: ${projectName})`);
         }
-        if (updated) {
-            writeFileSync(mcpJsonPath, `${JSON.stringify(existing, null, "\t")}\n`);
+        catch {
+            console.info("  failed: could not add codegraphcontext MCP server — run manually:");
+            console.info(`    claude mcp add -t stdio -s project -e DATABASE_TYPE=falkordb-remote -e FALKORDB_HOST=falkordb.orb.local -e FALKORDB_GRAPH_NAME=${projectName} -- codegraphcontext cgc mcp start`);
         }
     }
     else {
-        const mcpJson = {
-            mcpServers: {
-                indusk: induskEntry,
-                codegraphcontext: cgcEntry,
-            },
-        };
-        writeFileSync(mcpJsonPath, `${JSON.stringify(mcpJson, null, "\t")}\n`);
-        console.info("  create: .mcp.json (indusk + codegraphcontext)");
+        console.info("  skip: codegraphcontext MCP server (already exists)");
     }
     // 5. Generate .vscode/settings.json
     console.info("\n[Editor]");
@@ -255,6 +258,7 @@ export async function init(projectRoot, options = {}) {
     }
     // 8. Create .cgcignore (always overwrite — package-owned)
     createCgcIgnore(projectRoot);
+    ensureGitignoreMcpJson(projectRoot);
     // 9. Run on_init hooks from enabled extensions
     console.info("\n[Extension Hooks]");
     const { getEnabledExtensions } = await import("../../lib/extension-loader.js");
@@ -278,43 +282,9 @@ export async function init(projectRoot, options = {}) {
                 console.info(`  ${ext.manifest.name}: ${result.slice(0, 100)}`);
             }
         }
-        // Print expected .mcp.json config for extensions with mcp_server
-        if (ext.manifest.mcp_server) {
-            const mcpJsonPath = join(projectRoot, ".mcp.json");
-            let hasMcpEntry = false;
-            if (existsSync(mcpJsonPath)) {
-                try {
-                    const mcpConfig = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
-                    hasMcpEntry = !!mcpConfig?.mcpServers?.[ext.manifest.name];
-                }
-                catch { }
-            }
-            if (!hasMcpEntry) {
-                const srv = ext.manifest.mcp_server;
-                const config = {};
-                if (srv.type)
-                    config.type = srv.type;
-                if (srv.url)
-                    config.url = srv.url;
-                if (srv.command)
-                    config.command = srv.command;
-                if (srv.args)
-                    config.args = srv.args;
-                if (srv.headers)
-                    config.headers = srv.headers;
-                if (srv.env)
-                    config.env = srv.env;
-                console.info(`\n  ${ext.manifest.name}: add this to .mcp.json:\n`);
-                console.info(`    "${ext.manifest.name}": ${JSON.stringify(config, null, "      ")}\n`);
-                if (srv.setup_instructions) {
-                    for (const instruction of srv.setup_instructions) {
-                        console.info(`    ${instruction}`);
-                    }
-                }
-            }
-            else {
-                console.info(`  ${ext.manifest.name}: .mcp.json entry exists`);
-            }
+        // Print setup instructions for extensions with mcp_server
+        if (ext.manifest.mcp_server?.setup_instructions) {
+            console.info(`\n  ${ext.manifest.name}: MCP server setup needed — see .claude/skills/${ext.manifest.name}/SKILL.md for instructions`);
         }
     }
     if (enabledExts.length === 0) {

package/dist/bin/commands/update.js

@@ -180,41 +180,10 @@ export async function update(projectRoot) {
                 cpSync(builtinSkill, targetSkill);
                 console.info(`  added: ${name} skill`);
             }
-            // Print mcp_server config if extension has one
+            // Print setup reference for extensions with mcp_server
             const manifest = loadExtension(enabledManifest);
-            if (manifest?.mcp_server) {
-                const mcpJsonPath = join(projectRoot, ".mcp.json");
-                let hasMcpEntry = false;
-                if (existsSync(mcpJsonPath)) {
-                    try {
-                        const mcpConfig = JSON.parse(readFileSync(mcpJsonPath, "utf-8"));
-                        hasMcpEntry = !!mcpConfig?.mcpServers?.[name];
-                    }
-                    catch { }
-                }
-                if (!hasMcpEntry) {
-                    const srv = manifest.mcp_server;
-                    const config = {};
-                    if (srv.type)
-                        config.type = srv.type;
-                    if (srv.url)
-                        config.url = srv.url;
-                    if (srv.command)
-                        config.command = srv.command;
-                    if (srv.args)
-                        config.args = srv.args;
-                    if (srv.headers)
-                        config.headers = srv.headers;
-                    if (srv.env)
-                        config.env = srv.env;
-                    console.info(`\n  ${name}: add this to .mcp.json:\n`);
-                    console.info(`    "${name}": ${JSON.stringify(config, null, "      ")}\n`);
-                    if (srv.setup_instructions) {
-                        for (const instruction of srv.setup_instructions) {
-                            console.info(`    ${instruction}`);
-                        }
-                    }
-                }
+            if (manifest?.mcp_server?.setup_instructions) {
+                console.info(`  ${name}: MCP server setup — see .claude/skills/${name}/SKILL.md`);
             }
         }
         console.info(`\n${extUpdated} updated, ${extCurrent} current.`);

package/extensions/dash0/manifest.json

@@ -15,7 +15,7 @@
 		]
 	},
 	"mcp_server": {
-		"type": "streamableHttp",
+		"type": "http",
 		"url": "DASH0_ENDPOINT_MCP",
 		"headers": {
 			"Authorization": "Bearer DASH0_AUTH_TOKEN"

package/extensions/dash0/skill.md

@@ -14,53 +14,151 @@ Dash0 provides access to your OpenTelemetry data — logs, traces, and metrics
 - Installed via `brew install dash0hq/dash0-cli/dash0`
 - Auto-detects Claude Code and enables agent mode (JSON output, no prompts)
 - Use for: log queries, trace lookups, PromQL metrics, dashboard management, asset deployment
+- **All query commands require `--experimental` flag**
 - Key commands:
-  - `dash0 logs query` — search logs
-  - `dash0 traces get <trace-id>` — fetch trace details
-  - `dash0 metrics instant --query 'sum(...)'` — PromQL queries
+  - `dash0 --experimental logs query --from now-1h` — search logs (default time range is very narrow, always specify `--from`)
+  - `dash0 --experimental traces get <trace-id>` — fetch trace details by ID (no search/query for traces — use logs to find trace IDs first)
+  - `dash0 --experimental metrics instant --query 'sum(...)'` — PromQL queries
   - `dash0 dashboards list` — view dashboards
   - `dash0 apply -f assets.yaml` — deploy dashboards, views, checks (GitOps)
 
 ## When to Use Dash0
 
-- **Test failures**: query recent traces to see what happened in the service during the test
+- **Test failures**: query recent logs/traces to see what happened in the service during the test
 - **Debugging production issues**: search logs for errors, find related traces by trace ID
 - **Performance investigation**: query metrics (PromQL) to check latency, throughput, error rates
 - **Deployment verification**: check traces and error rates after deploying a change
 - **During /work verification**: if a verification step involves checking service health, query Dash0
 - **Dashboard management**: use the CLI to create/update dashboards from YAML definitions
 
+## MCP Tools Reference
+
+The MCP server provides 23 tools. The key ones for debugging:
+
+### Logs
+- **`getLogRecords`** — Query logs with filters, time range, pagination. Returns summary table.
+  - Always pass `dataset: "dev"` for our environment
+  - `timeRange` requires ISO timestamps: `{"from": "...", "to": "..."}`
+  - `filters`: `[{"key": "service.name", "operator": "is", "value": "game-server"}]`
+  - `logAttributeKeys`: specify which attributes to show in the table (e.g. `["service.name", "otel.scope.name"]`)
+  - Returns log record IDs for drilling into full details
+- **`getFullLogRecord`** — Get ALL attributes of a single log record by ID. Use this to see custom attributes (roomCode, walletAddress, agent name, etc.) that aren't in the summary table.
+- **`getLogCorrelations`** — Find patterns and correlations in logs
+
+### Traces
+- **`getSpans`** — Search for spans (traces) with filters and time range
+- **`getTraceDetails`** — Get full trace tree by trace ID, including hierarchy, events, and comparison to similar spans
+- **`getSpanCorrelations`** — Find patterns in spans
+
+### Services
+- **`getServiceCatalog`** — All services with RED metrics (requests, errors, duration) and dependency map
+- **`getServiceDetails`** — Deep dive into a single service
+
+### Metrics
+- **`promql`** — Run PromQL queries
+- **`getMetricCatalog`** — List available metrics
+- **`getMetricDetails`** — Details on a specific metric
+
+### Other
+- **`getAttributeKeys`** / **`getAttributeValues`** — Discover what attributes exist in the data
+- **`listDashboards`** / **`listDatasets`** — List dashboards and datasets
+- **`getFailedChecks`** / **`getFailedCheckDetails`** — View check failures
+- **`searchKnowledgeBase`** — Search Dash0 documentation
+
+### MCP Usage Pattern
+```
+1. getLogRecords → find the log summary, get log record IDs
+2. getFullLogRecord → drill into a specific log for all attributes
+3. If log has traceId → getTraceDetails to see the full request chain
+4. getServiceCatalog → see all services, error rates, dependencies
+```
+
 ## When to Use MCP vs CLI
 
 | Task | Use |
 |------|-----|
-| Query logs during a session | MCP tools |
-| Search traces by service or ID | MCP tools |
+| Query logs during a session | MCP `getLogRecords` (preferred) or CLI |
+| Get full log details with all attributes | MCP `getFullLogRecord` (by log record ID) |
+| Search traces by service or ID | MCP `getSpans` or CLI `traces get <id>` |
+| Get full trace hierarchy | MCP `getTraceDetails` (preferred) |
 | Run PromQL metrics query | Either — MCP for simple, CLI for complex |
 | Deploy dashboard from YAML | CLI (`dash0 apply -f`) |
-| Diagnose a failing service | MCP tools (faster, in-session) |
+| Diagnose a failing service | MCP `getServiceCatalog` → `getLogRecords` → `getFullLogRecord` |
 | CI/CD observability checks | CLI (scriptable, agent mode) |
-| Get trace details for debugging | Either |
+| Discover available attributes | MCP `getAttributeKeys` / `getAttributeValues` |
+
+## CLI Usage Patterns
+
+### Query logs
+```bash
+# Always use --experimental and --from (default range is too narrow)
+source ~/.zshrc  # ensure DASH0_API_TOKEN is available
+dash0 --experimental logs query --from now-1h --limit 10
+
+# Filter by service
+dash0 --experimental logs query --from now-1h --filter "service.name is game-server"
+
+# Filter by severity
+dash0 --experimental logs query --from now-1h --filter "otel.log.severity.range is_one_of ERROR WARN"
+
+# CSV output for readability
+dash0 --experimental logs query --from now-1h -o csv
+
+# Include custom columns
+dash0 --experimental logs query --from now-1h -o csv \
+  --column time --column severity --column service.name --column body
+
+# JSON output (OTLP format)
+dash0 --experimental logs query --from now-1h -o json --limit 5
+```
+
+### Get trace details
+```bash
+# Traces don't have a search/query — you need a trace ID
+# Get trace IDs from logs first, then fetch the trace:
+dash0 --experimental traces get <trace-id>
+
+# Follow span links to related traces
+dash0 --experimental traces get <trace-id> --follow-span-links
+```
+
+### Authentication
+The CLI uses profiles. If auth fails, ensure the profile has the token:
+```bash
+dash0 config profiles list           # check existing profiles
+dash0 config profiles create dev \
+  --api-url https://api.europe-west4.gcp.dash0.com \
+  --auth-token $DASH0_API_TOKEN \
+  --dataset dev
+```
+
+If the profile exists but auth still fails, pass `--auth-token` explicitly:
+```bash
+dash0 --experimental logs query --auth-token "$DASH0_API_TOKEN" \
+  --api-url "https://api.europe-west4.gcp.dash0.com" \
+  --dataset dev --from now-1h
+```
+
+**Important:** Claude Code's shell may not have `DASH0_API_TOKEN` loaded. Run `source ~/.zshrc` before any `dash0` command if you get auth errors.
 
 ## Setup
 
-### MCP Server (enabled automatically by `extensions enable dash0`)
+### MCP Server
 
 **Important:** The Dash0 MCP server is a remote hosted service, not an npm package. Do not use `npx` or install anything for the MCP server. You only need a URL and an auth token.
 
-The `.mcp.json` entry is added when you enable the extension:
+Add the MCP server via the Claude Code CLI:
 
-```json
-"dash0": {
-  "type": "streamableHttp",
-  "url": "YOUR_ENDPOINT_URL",
-  "headers": {
-    "Authorization": "Bearer YOUR_AUTH_TOKEN"
-  }
-}
+```bash
+source ~/.zshrc  # ensure DASH0_API_TOKEN is available
+claude mcp add -t http -s project \
+  -H "Authorization: Bearer $DASH0_API_TOKEN" \
+  -- dash0 "https://api.YOUR_REGION.dash0.com/mcp"
 ```
 
-Get your endpoint URL and auth token from Dash0: Organization Settings > Endpoints > MCP, and Organization Settings > Auth Tokens.
+**Important:** The type is `http` (not `streamable-http` or `streamableHttp`). Get your auth token from Dash0: Organization Settings > Auth Tokens. The URL is your Dash0 API endpoint + `/mcp`.
+
+**Never manually edit `.mcp.json`** — always use `claude mcp add`.
 
 ### CLI
 
@@ -69,8 +167,9 @@ brew tap dash0hq/dash0-cli https://github.com/dash0hq/dash0-cli
 brew install dash0hq/dash0-cli/dash0
 
 dash0 config profiles create dev \
-  --api-url https://api.us-west-2.aws.dash0.com \
-  --auth-token YOUR_AUTH_TOKEN
+  --api-url https://api.europe-west4.gcp.dash0.com \
+  --auth-token YOUR_AUTH_TOKEN \
+  --dataset dev
 ```
 
 The CLI auto-detects Claude Code sessions and switches to agent mode (JSON output, no confirmation prompts, structured errors on stderr).
@@ -79,14 +178,13 @@ The CLI auto-detects Claude Code sessions and switches to agent mode (JSON outpu
 
 ### During verification
 When a verification step involves checking that a service is working correctly, don't just check the HTTP status — query Dash0 for:
-- Recent error traces for the service
-- Error rate metrics before and after your change
+- Recent error logs for the service: `dash0 --experimental logs query --from now-15m --filter "service.name is game-server" --filter "otel.log.severity.range is_one_of ERROR WARN"`
 - Log entries matching the feature you modified
 
 ### During debugging
 When something fails:
-1. Check logs first — search for errors in the relevant service
-2. Find the trace — use the trace ID from logs to get the full request flow
+1. Check logs first — `dash0 --experimental logs query --from now-1h --filter "otel.log.severity.range is_one_of ERROR WARN" -o csv`
+2. Find the trace — look for trace IDs in log entries, then `dash0 --experimental traces get <trace-id>`
 3. Check metrics — is this a new problem or an existing one? Compare error rates over time.
 
 ### During retrospective
@@ -98,3 +196,10 @@ Query Dash0 for metrics that show the impact of the plan:
 ## Connecting to OpenTelemetry
 
 Dash0 ingests standard OpenTelemetry data. If your services already export OTLP telemetry, point the OTLP exporter at Dash0's endpoint. See [Dash0 docs](https://www.dash0.com/documentation/dash0) for setup per language.
+
+## Known Issues
+
+- **CLI `--experimental` required**: All query commands (logs, traces, metrics) require the `--experimental` flag. This will change when these commands become stable.
+- **Default time range is narrow**: Always specify `--from` when querying logs. Without it, you may get empty results.
+- **No trace search**: The CLI can only fetch traces by ID (`traces get <id>`), not search for them. Find trace IDs in log entries first.
+- **Profile auth may not load in Claude Code shell**: Run `source ~/.zshrc` before `dash0` commands if auth fails.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.4.5",
+	"version": "1.5.0",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [