@infinitedusky/indusk-mcp 1.10.1 → 1.10.3

package/dist/lib/config.d.ts

@@ -44,12 +44,28 @@ export declare function getConfigPath(projectRoot: string): string;
 export declare function readConfig(projectRoot: string): InduskConfig | null;
 export declare function writeConfig(projectRoot: string, config: InduskConfig): void;
 export declare function getPlanningDir(projectRoot: string): string;
+/**
+ * Sanitize a string into a valid Graphiti group id.
+ *
+ * Graphiti uses RediSearch under the hood, which treats `-` as a token separator.
+ * A query like `chitin-sportsbook` parses as "find chitin, exclude sportsbook" and
+ * fails with `Syntax error at offset N near chitin`. Anything that isn't
+ * `[A-Za-z0-9_]` gets replaced with `_`. Multiple separators collapse to one.
+ *
+ * Examples:
+ *   "chitin-sportsbook" → "chitin_sportsbook"
+ *   "my.cool.project"   → "my_cool_project"
+ *   "@scope/pkg"        → "scope_pkg"
+ *   "indusk_already_ok" → "indusk_already_ok" (no change)
+ */
+export declare function sanitizeGroupId(raw: string): string;
 /**
  * Get the Graphiti group id for project-specific episodes.
  *
  * Resolution order:
- *   1. .indusk/config.json `graphiti.groupId` if set
- *   2. Project directory basename
+ *   1. .indusk/config.json `graphiti.groupId` if set (used as-is, not sanitized —
+ *      explicit overrides are trusted; if you set a hyphenated id, that's on you)
+ *   2. Sanitized project directory basename (`-` → `_`, etc., for RediSearch safety)
  *
  * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
  * searching Graphiti — this gives both project-scoped and cross-project knowledge.

package/dist/lib/config.js

@@ -26,12 +26,30 @@ export function getPlanningDir(projectRoot) {
     // Default to new path (will be created by init)
     return newPath;
 }
+/**
+ * Sanitize a string into a valid Graphiti group id.
+ *
+ * Graphiti uses RediSearch under the hood, which treats `-` as a token separator.
+ * A query like `chitin-sportsbook` parses as "find chitin, exclude sportsbook" and
+ * fails with `Syntax error at offset N near chitin`. Anything that isn't
+ * `[A-Za-z0-9_]` gets replaced with `_`. Multiple separators collapse to one.
+ *
+ * Examples:
+ *   "chitin-sportsbook" → "chitin_sportsbook"
+ *   "my.cool.project"   → "my_cool_project"
+ *   "@scope/pkg"        → "scope_pkg"
+ *   "indusk_already_ok" → "indusk_already_ok" (no change)
+ */
+export function sanitizeGroupId(raw) {
+    return raw.replace(/[^A-Za-z0-9_]+/g, "_").replace(/^_+|_+$/g, "");
+}
 /**
  * Get the Graphiti group id for project-specific episodes.
  *
  * Resolution order:
- *   1. .indusk/config.json `graphiti.groupId` if set
- *   2. Project directory basename
+ *   1. .indusk/config.json `graphiti.groupId` if set (used as-is, not sanitized —
+ *      explicit overrides are trusted; if you set a hyphenated id, that's on you)
+ *   2. Sanitized project directory basename (`-` → `_`, etc., for RediSearch safety)
  *
  * Use `[getProjectGroupId(root), "shared"]` as the default group_ids list when
  * searching Graphiti — this gives both project-scoped and cross-project knowledge.
@@ -40,7 +58,7 @@ export function getProjectGroupId(projectRoot) {
     const config = readConfig(projectRoot);
     if (config?.graphiti?.groupId)
         return config.graphiti.groupId;
-    return basename(projectRoot);
+    return sanitizeGroupId(basename(projectRoot));
 }
 /**
  * Whether the OTel gate should fire for this project.

package/extensions/dash0/skill.md

@@ -65,14 +65,22 @@ The MCP server provides 23 tools. The key ones for debugging:
 - **`getFailedChecks`** / **`getFailedCheckDetails`** — View check failures
 - **`searchKnowledgeBase`** — Search Dash0 documentation
 
-### MCP Usage Pattern
+### MCP Usage Pattern — Traces First
+
+**Always start with spans.** Logs are correlated with traces, so finding the right trace first helps you find the right logs — not the other way around.
+
 ```
-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
+1. getSpans (last 30s, no filters) → scan recent spans for anything matching your investigation
+2. Found a relevant span? → getTraceDetails to see the full request chain
+3. Use trace/span IDs to find correlated logs → getLogRecords with traceId filter
+4. getFullLogRecord → drill into a specific log for all attributes
 ```
 
+**Why traces first:**
+- Spans show the full request lifecycle — what happened, how long, what called what
+- Logs are attached to spans via trace context — the trace tells you which logs matter
+- Starting with logs means guessing at filters; starting with spans gives you the map
+
 ## When to Use MCP vs CLI
 
 | Task | Use |
@@ -83,7 +91,7 @@ The MCP server provides 23 tools. The key ones for debugging:
 | 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 `getServiceCatalog` → `getLogRecords` → `getFullLogRecord` |
+| Diagnose a failing service | MCP `getSpans` (last 30s) → `getTraceDetails` → `getLogRecords` (by traceId) |
 | CI/CD observability checks | CLI (scriptable, agent mode) |
 | Discover available attributes | MCP `getAttributeKeys` / `getAttributeValues` |
 
@@ -178,14 +186,16 @@ 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 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
+- **Recent spans first**: use MCP `getSpans` with a short time range (last 30s) to see what the service just did — look for errors, slow spans, or missing expected operations
+- **Then correlated logs**: once you have a trace ID from a relevant span, use `getLogRecords` filtered by that trace ID to see exactly what happened during that request
+- **Only use broad log queries as a fallback** if no spans are present (e.g., the service isn't instrumented yet)
 
 ### During debugging
 When something fails:
-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.
+1. **Get recent spans first** — use MCP `getSpans` with a short time range (last 30s–1m). Don't filter yet — scan the results for spans matching what you're investigating.
+2. **Drill into the trace** — found a relevant span? Use `getTraceDetails` to see the full request chain, timing, errors, and hierarchy.
+3. **Find correlated logs** — use the trace ID from step 2 to query `getLogRecords` with a `traceId` filter. This gives you exactly the logs tied to that request, no guessing.
+4. **Check metrics** — is this a new problem or an existing one? Compare error rates over time.
 
 ### During retrospective
 Query Dash0 for metrics that show the impact of the plan:
@@ -201,5 +211,5 @@ Dash0 ingests standard OpenTelemetry data. If your services already export OTLP
 
 - **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.
+- **CLI has no trace search**: The CLI can only fetch traces by ID (`traces get <id>`), not search for them. Use the MCP `getSpans` tool to search spans — it supports filters and time ranges. The CLI requires you to already have a trace ID.
 - **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.10.1",
+	"version": "1.10.3",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [