@infinitedusky/indusk-mcp 0.3.0 → 0.4.1

package/dist/bin/commands/init.js

@@ -196,6 +196,19 @@ export async function init(projectRoot, options = {}) {
         console.info("  missing: Docker — install Docker or OrbStack to enable FalkorDB");
     }
     const cgcInstalled = checkCGC();
+    // 9. Auto-index the codebase into the graph
+    if (dockerAvailable && cgcInstalled) {
+        console.info("\n[Code Graph]");
+        console.info("  indexing: scanning codebase...");
+        const { indexProject } = await import("../../tools/graph-tools.js");
+        const result = indexProject(projectRoot);
+        if (result.success) {
+            console.info(`  done: ${result.output}`);
+        }
+        else {
+            console.info(`  error: ${result.output}`);
+        }
+    }
     // Summary
     console.info("\nDone!");
     if (!cgcInstalled || !dockerAvailable) {
@@ -210,7 +223,6 @@ export async function init(projectRoot, options = {}) {
     }
     console.info("\nNext steps:");
     console.info("  1. Edit CLAUDE.md with your project details");
-    console.info("  2. Install Biome: pnpm add -D @biomejs/biome");
-    console.info("  3. Start a Claude Code session — MCP tools will be available");
-    console.info("  4. Start planning: /plan your-first-feature");
+    console.info("  2. Start a Claude Code session — MCP tools will be available");
+    console.info("  3. Start planning: /plan your-first-feature");
 }

package/dist/bin/commands/update.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, readFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { globSync } from "glob";
@@ -14,21 +14,25 @@ export async function update(projectRoot) {
     const skillsTarget = join(projectRoot, ".claude/skills");
     const skillFiles = globSync("*.md", { cwd: skillsSource });
     let updated = 0;
-    let skipped = 0;
+    let added = 0;
+    let current = 0;
     for (const file of skillFiles) {
         const skillName = file.replace(".md", "");
         const sourceFile = join(skillsSource, file);
-        const targetFile = join(skillsTarget, skillName, "SKILL.md");
+        const targetDir = join(skillsTarget, skillName);
+        const targetFile = join(targetDir, "SKILL.md");
         if (!existsSync(targetFile)) {
-            console.info(`  skip: ${skillName} (not installed — run init first)`);
-            skipped++;
+            mkdirSync(targetDir, { recursive: true });
+            cpSync(sourceFile, targetFile);
+            console.info(`  added: ${skillName} (new skill)`);
+            added++;
             continue;
         }
         const sourceHash = fileHash(sourceFile);
         const targetHash = fileHash(targetFile);
         if (sourceHash === targetHash) {
             console.info(`  current: ${skillName}`);
-            skipped++;
+            current++;
         }
         else {
             cpSync(sourceFile, targetFile);
@@ -36,5 +40,5 @@ export async function update(projectRoot) {
             updated++;
         }
     }
-    console.info(`\n${updated} updated, ${skipped} current.`);
+    console.info(`\n${added} added, ${updated} updated, ${current} current.`);
 }

package/dist/server/index.js

@@ -3,6 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerContextTools } from "../tools/context-tools.js";
 import { registerDocumentTools } from "../tools/document-tools.js";
+import { registerGraphTools } from "../tools/graph-tools.js";
 import { registerPlanTools } from "../tools/plan-tools.js";
 import { registerQualityTools } from "../tools/quality-tools.js";
 import { registerSystemTools } from "../tools/system-tools.js";
@@ -17,6 +18,7 @@ export async function startServer() {
     registerQualityTools(server, projectRoot);
     registerDocumentTools(server, projectRoot);
     registerSystemTools(server, projectRoot);
+    registerGraphTools(server, projectRoot);
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/dist/tools/graph-tools.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function indexProject(projectRoot: string): {
+    success: boolean;
+    output: string;
+};
+export declare function registerGraphTools(server: McpServer, projectRoot: string): void;

package/dist/tools/graph-tools.js

@@ -0,0 +1,116 @@
+import { execSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { z } from "zod";
+function cgcPath() {
+    const paths = [join(process.env.HOME ?? "", ".local/bin/cgc"), "/usr/local/bin/cgc"];
+    return paths.find((p) => existsSync(p)) ?? null;
+}
+function runCgc(args, projectRoot) {
+    const cgc = cgcPath();
+    if (!cgc) {
+        return JSON.stringify({ error: "CGC not installed — run: pipx install codegraphcontext" });
+    }
+    try {
+        return execSync(`${cgc} ${args}`, {
+            encoding: "utf-8",
+            timeout: 60000,
+            stdio: ["ignore", "pipe", "pipe"],
+            cwd: projectRoot,
+            env: {
+                ...process.env,
+                DATABASE_TYPE: "falkordb-remote",
+                FALKORDB_HOST: process.env.FALKORDB_HOST ?? "localhost",
+                FALKORDB_PORT: process.env.FALKORDB_PORT ?? "6379",
+                FALKORDB_GRAPH_NAME: process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot),
+            },
+        }).trim();
+    }
+    catch (err) {
+        const execErr = err;
+        return JSON.stringify({
+            error: execErr.stderr?.trim() || execErr.message || "CGC command failed",
+        });
+    }
+}
+export function indexProject(projectRoot) {
+    const cgc = cgcPath();
+    if (!cgc) {
+        return { success: false, output: "CGC not installed — run: pipx install codegraphcontext" };
+    }
+    const graphName = process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot);
+    try {
+        // Check if .cgcignore exists
+        const hasIgnore = existsSync(join(projectRoot, ".cgcignore"));
+        const output = execSync(`${cgc} index ${projectRoot}`, {
+            encoding: "utf-8",
+            timeout: 120000,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: {
+                ...process.env,
+                DATABASE_TYPE: "falkordb-remote",
+                FALKORDB_HOST: process.env.FALKORDB_HOST ?? "localhost",
+                FALKORDB_PORT: process.env.FALKORDB_PORT ?? "6379",
+                FALKORDB_GRAPH_NAME: graphName,
+            },
+        }).trim();
+        return {
+            success: true,
+            output: `Indexed into graph '${graphName}'${hasIgnore ? " (with .cgcignore)" : " (no .cgcignore — consider creating one)"}. ${output}`,
+        };
+    }
+    catch (err) {
+        const execErr = err;
+        return {
+            success: false,
+            output: execErr.stderr?.trim() || execErr.message || "Index failed",
+        };
+    }
+}
+export function registerGraphTools(server, projectRoot) {
+    server.registerTool("index_project", {
+        description: "Index the project codebase into the code graph. Run this after init or when the codebase has changed significantly. Uses CGC under the hood.",
+    }, async () => {
+        const result = indexProject(projectRoot);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            isError: !result.success,
+        };
+    });
+    server.registerTool("query_dependencies", {
+        description: "Query what depends on a file or module, and what it depends on. Use BEFORE modifying any file to understand blast radius.",
+        inputSchema: {
+            target: z.string().describe("File path, function name, or module to query"),
+            direction: z
+                .enum(["dependents", "dependencies", "both"])
+                .default("both")
+                .describe("Direction: what depends on this (dependents), what this depends on (dependencies), or both"),
+        },
+    }, async ({ target, direction }) => {
+        let query;
+        if (direction === "dependents") {
+            query = `MATCH (dependent)-[r]->(target) WHERE target.name CONTAINS '${target}' RETURN dependent.name as dependent, type(r) as relationship, target.name as target`;
+        }
+        else if (direction === "dependencies") {
+            query = `MATCH (source)-[r]->(dep) WHERE source.name CONTAINS '${target}' RETURN source.name as source, type(r) as relationship, dep.name as dependency`;
+        }
+        else {
+            query = `MATCH (a)-[r]-(b) WHERE a.name CONTAINS '${target}' RETURN a.name as source, type(r) as relationship, b.name as related ORDER BY relationship`;
+        }
+        const output = runCgc(`query "${query}"`, projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+    server.registerTool("query_graph", {
+        description: "Run a custom Cypher query against the code graph. Use for advanced structural queries not covered by query_dependencies.",
+        inputSchema: {
+            cypher: z.string().describe("Cypher query to execute (read-only)"),
+        },
+    }, async ({ cypher }) => {
+        const output = runCgc(`query "${cypher}"`, projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+}

package/package.json

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

package/skills/context.md

@@ -78,6 +78,7 @@ After writing a retrospective, read the "Insights Worth Carrying Forward" and "W
 - If it changes the project's architecture or structure → update **Architecture**
 - Update **Current State** to reflect the plan's completion
 - If the retrospective's "Quality Ratchet" section adds a new Biome rule, also add the enforced pattern to **Conventions**
+- **REQUIRED: Query the code graph** — call `query_dependencies` on the key files that changed to verify the Architecture section still reflects reality. If the plan changed how modules connect, update Architecture with the new relationships.
 
 Do this immediately after writing the retrospective, before moving on.
 

package/skills/document.md

@@ -18,6 +18,8 @@ After context items are done, the document gate asks one question:
 
 **"Does this phase change something a user or developer needs to know?"**
 
+To answer this accurately, **REQUIRED: call `query_dependencies`** on the key files changed in this phase. If the change affects files with many dependents, it likely needs documentation. If it's internal with no downstream consumers, it might not.
+
 - If **yes**: write or update the relevant page in `apps/indusk-docs/src/`
 - If **no**: skip — not every phase produces documentation. The gate asks the question but doesn't always produce output.
 

package/skills/plan.md

@@ -31,7 +31,12 @@ General-purpose research (insights useful across plans) also lives in `research/
 
 1. **Figure out where things stand.** If a plan folder already exists, read what's there. Check frontmatter statuses. The next document to write is the first one that's missing or incomplete.
 
-2. **If starting fresh**, create the plan folder and start with research. Explore the problem space — read code, search the web, check Context7 for library docs. **Query the code graph** (`analyze_code_relationships`, `find_code`, `get_repository_stats`) to understand the structural landscape before scoping. Document what you find. The research doc records findings and analysis, but saves the recommendation for the brief.
+2. **If starting fresh**, create the plan folder and start with research. Explore the problem space — read code, search the web, check Context7 for library docs. **REQUIRED: Query the code graph before scoping:**
+   - Call `query_dependencies` on the target area to understand what depends on it and what it depends on
+   - Call `find_code` to find existing implementations you might reuse or need to modify
+   - Call `get_repository_stats` to understand the size of the area you're about to scope
+   - Include the graph findings in research.md — concrete numbers like "X has 12 dependents across 3 apps"
+   Document what you find. The research doc records findings and analysis, but saves the recommendation for the brief.
 
 3. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. Present for review.
 

package/skills/retrospective.md

@@ -40,7 +40,16 @@ Key sections to fill in honestly:
 - **What We'd Do Differently** — hindsight decisions
 - **Insights Worth Carrying Forward** — takeaways for future plans
 
-### Step 2: Docs Audit
+### Step 2: Structural Audit (Code Graph)
+
+**REQUIRED:** Before reviewing docs or tests, query the code graph to understand what actually changed:
+
+1. Call `query_dependencies` on the key files from this plan — verify the dependency relationships match what was designed
+2. Call `find_most_complex_functions` — check if the plan introduced high-complexity code that should be refactored
+3. Call `find_dead_code` — check if the plan left behind unused functions from refactoring
+4. Include findings in the retrospective under "What Actually Happened" — e.g., "Plan touched 8 files with 23 downstream dependents"
+
+### Step 3: Docs Audit
 
 Review every documentation page that was written or updated during this plan's impl phases.
 
@@ -52,7 +61,7 @@ For each page:
 
 Fix any discrepancies found. Plans often diverge from their impl during execution — the docs must reflect reality.
 
-### Step 3: Test Audit
+### Step 4: Test Audit
 
 Review the test files created or modified during this plan.
 
@@ -62,7 +71,7 @@ Review the test files created or modified during this plan.
 
 Flag gaps but don't necessarily fix them all now — add them as items to a follow-up plan if they're significant.
 
-### Step 4: Quality Audit
+### Step 5: Quality Audit
 
 Review mistakes made during this plan's implementation.
 
@@ -72,7 +81,7 @@ Review mistakes made during this plan's implementation.
 
 The quality ratchet only gets tighter. Every retrospective is an opportunity to prevent the same class of mistake from happening again.
 
-### Step 5: Context Audit
+### Step 6: Context Audit
 
 Re-read CLAUDE.md in full. After the entire impl is done, verify:
 
@@ -84,7 +93,7 @@ Re-read CLAUDE.md in full. After the entire impl is done, verify:
 
 Fix any inaccuracies. The impl may have changed things that weren't anticipated in the per-phase context updates.
 
-### Step 6: Knowledge Handoff
+### Step 7: Knowledge Handoff
 
 Distill planning artifacts into the docs site so the knowledge survives archival.
 
@@ -103,7 +112,7 @@ Not every plan produces a lessons page — only create one if the insights are g
 
 **Update sidebar:** Add new decision/lesson pages to the VitePress sidebar config in `apps/indusk-docs/src/.vitepress/config.ts`.
 
-### Step 7: Archival
+### Step 8: Archival
 
 Move the planning artifacts to the archive:
 

package/skills/toolbelt.md

@@ -57,24 +57,46 @@ These come from the codegraphcontext MCP server:
 | Check for dead code | `find_dead_code` |
 | Scope a plan during research | `analyze_code_relationships` on the target area |
 | Custom graph queries | `execute_cypher_query` |
+| Visualize the graph | `visualize_graph_query` — returns a browser link to view the graph |
+| Get repo stats | `get_repository_stats` |
+| See what's indexed | `list_indexed_repositories` |
+
+### Visualizing the Code Graph
+
+When the user asks to "show the graph", "display dependencies", or "visualize":
+
+1. Call `visualize_graph_query` with a Cypher query like `MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 100` — this returns a URL to open in the browser.
+2. For a specific file's dependencies: `MATCH (n)-[r]->(m) WHERE n.name CONTAINS 'filename' RETURN n, r, m`
+3. For the full project overview: `MATCH (n) RETURN n LIMIT 200`
+
+If the user wants text-based output instead, use `execute_cypher_query` directly and format the results as a table or list.
 
 ## Tool Reference
 
-### indusk (14 tools)
+### indusk (17 tools)
 
 | Tool | When to use |
 |------|-------------|
+| **Graph (use these constantly)** | |
+| `index_project` | After init, or when codebase changed significantly |
+| `query_dependencies` | **BEFORE modifying any file** — understand blast radius |
+| `query_graph` | Custom Cypher queries for advanced structural analysis |
+| **Plans** | |
 | `list_plans` | Session start, orientation |
 | `get_plan_status` | Before working on a plan, checking progress |
 | `advance_plan` | End of every phase — validates all gates |
 | `order_plans` | Understanding plan dependencies |
+| **Context** | |
 | `get_context` | Session start, after context updates |
 | `update_context` | Updating CLAUDE.md sections programmatically |
+| **Quality** | |
 | `get_quality_config` | Reviewing Biome rules, after retros |
 | `suggest_rule` | Finding Biome rules for new patterns |
 | `quality_check` | After verification items, before advancing |
+| **Docs** | |
 | `list_docs` | After document items, checking coverage |
 | `check_docs_coverage` | After retros, finding doc gaps |
+| **System** | |
 | `get_system_version` | Debugging, version checks |
 | `get_skill_versions` | Checking for outdated skills |
 | `check_health` | Session start, debugging connectivity |

package/skills/verify.md

@@ -56,7 +56,7 @@ When the work skill is executing an impl and reaches verification items, run che
    - Skip for: markdown changes, config-only changes with no test files
    - Catches: behavioral regressions, broken logic
    - Run affected app's tests, not the full suite
-   - **Use the code graph to find affected tests** — query `analyze_code_relationships` for the changed file to discover which test files import or depend on it. Run those tests specifically rather than guessing.
+   - **REQUIRED: Use the code graph to find affected tests** — call `query_dependencies` on the changed file with direction "dependents" to discover which test files import or depend on it. Run those tests specifically rather than guessing. Do not skip this step.
 
 4. **Build** — `pnpm turbo build --filter={app}`
    - Only for: shared package changes, build config changes

package/skills/work.md

@@ -25,12 +25,12 @@ Implementation plans live in `planning/{plan-name}/impl.md` as checklists. Your
 5. **Work through the checklist in order.**
    - Start from the first unchecked item (`- [ ]`)
    - For each item:
-     a. **Query the code graph first** — before modifying a file, use `analyze_code_relationships` or `find_code` to understand its dependents. If the file is widely imported, flag the blast radius before proceeding.
-     b. **Check for existing code** — before writing new functions, use `find_code` to search for functions that already do what you need. Reuse and extend existing code rather than duplicating. Stay DRY.
+     a. **REQUIRED: Query the code graph** — before modifying ANY file, call `query_dependencies` on that file. Review the dependents list. If >3 dependents, flag the blast radius to the user before proceeding. This is not optional.
+     b. **REQUIRED: Check for existing code** — before writing new functions, call `find_code` to search for functions that already do what you need. Reuse and extend existing code rather than duplicating. Stay DRY.
      c. Read the relevant source files
      d. Implement the change
-     d. Immediately edit impl.md to check the item off (`- [ ]` → `- [x]`)
-     e. Move to the next item
+     e. Immediately edit impl.md to check the item off (`- [ ]` → `- [x]`)
+     f. Move to the next item
    - Do NOT skip ahead or work out of order unless there's a dependency reason
    - Do NOT batch checklist updates — check each off as soon as it's done