@infinitedusky/indusk-mcp 1.1.0 → 1.1.1

package/dist/tools/graph-tools.js

@@ -69,7 +69,7 @@ export function indexProject(projectRoot) {
 }
 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.",
+        description: "Index the project codebase into the code graph. Run this after init or when the codebase has changed significantly.",
     }, async () => {
         const result = indexProject(projectRoot);
         return {
@@ -113,4 +113,159 @@ export function registerGraphTools(server, projectRoot) {
             content: [{ type: "text", text: output }],
         };
     });
+    server.registerTool("graph_visualize", {
+        description: "Launch the interactive code graph visualization in the browser. Shows nodes (files, functions, classes) and relationships (calls, imports, inherits). Use when the user wants to see or explore the code graph visually.",
+    }, async () => {
+        const cgc = cgcPath();
+        if (!cgc) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: "CGC not installed" }) },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            execSync(`${cgc} visualize --port 8111 &`, {
+                encoding: "utf-8",
+                timeout: 5000,
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: projectRoot,
+                env: {
+                    ...process.env,
+                    DATABASE_TYPE: "falkordb-remote",
+                    FALKORDB_HOST: process.env.FALKORDB_HOST ?? "falkordb.orb.local",
+                    FALKORDB_GRAPH_NAME: process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot),
+                },
+            });
+        }
+        catch {
+            // visualize runs in background, the timeout catch is expected
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        url: "http://localhost:8111",
+                        message: "Code graph visualization started at http://localhost:8111 — open in browser",
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("graph_doctor", {
+        description: "Run CGC diagnostics to check database connection, configuration, and system health. Use when graph tools return errors or when debugging graph issues.",
+    }, async () => {
+        const output = runCgc("doctor", projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+    server.registerTool("graph_find_dead_code", {
+        description: "Find potentially unused functions (dead code) across the indexed codebase. Useful for cleanup and refactoring.",
+    }, async () => {
+        const output = runCgc("analyze dead-code", projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+    server.registerTool("graph_complexity", {
+        description: "Find the most complex functions in the codebase by cyclomatic complexity. Useful for identifying refactoring targets.",
+        inputSchema: {
+            limit: z.number().default(10).describe("Number of results to return"),
+        },
+    }, async ({ limit }) => {
+        const output = runCgc(`analyze complexity --limit ${limit}`, projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+    server.registerTool("graph_callers", {
+        description: "Find all functions that call a given function. Use to understand impact before modifying a function.",
+        inputSchema: {
+            function_name: z.string().describe("Name of the function to find callers for"),
+        },
+    }, async ({ function_name }) => {
+        const output = runCgc(`analyze callers "${function_name}"`, projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+    server.registerTool("graph_callees", {
+        description: "Find all functions that a given function calls. Use to understand what a function depends on.",
+        inputSchema: {
+            function_name: z.string().describe("Name of the function to find callees for"),
+        },
+    }, async ({ function_name }) => {
+        const output = runCgc(`analyze calls "${function_name}"`, projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+    server.registerTool("graph_find", {
+        description: "Search the code graph for functions, classes, or modules by name or content. Faster than grep for structural queries.",
+        inputSchema: {
+            query: z.string().describe("Name or keyword to search for"),
+            type: z
+                .enum(["name", "pattern", "content"])
+                .default("name")
+                .describe("Search type: exact name, substring pattern, or content search"),
+        },
+    }, async ({ query, type }) => {
+        const output = runCgc(`find ${type} "${query}"`, projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
+    server.registerTool("graph_watch", {
+        description: "Start watching the project directory for file changes and auto-update the graph. Keeps the graph current without manual re-indexing.",
+    }, async () => {
+        const cgc = cgcPath();
+        if (!cgc) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: "CGC not installed" }) },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            execSync(`${cgc} watch ${projectRoot} &`, {
+                encoding: "utf-8",
+                timeout: 5000,
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: projectRoot,
+                env: {
+                    ...process.env,
+                    DATABASE_TYPE: "falkordb-remote",
+                    FALKORDB_HOST: process.env.FALKORDB_HOST ?? "falkordb.orb.local",
+                    FALKORDB_GRAPH_NAME: process.env.FALKORDB_GRAPH_NAME ?? basename(projectRoot),
+                },
+            });
+        }
+        catch {
+            // watch runs in background
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        message: `Watching ${projectRoot} for changes — graph will auto-update`,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("graph_stats", {
+        description: "Get statistics about the indexed codebase: file count, function count, class count, module count.",
+    }, async () => {
+        const output = runCgc("stats", projectRoot);
+        return {
+            content: [{ type: "text", text: output }],
+        };
+    });
 }

package/extensions/cgc/skill.md

@@ -2,34 +2,75 @@
 
 CodeGraphContext (CGC) provides structural code intelligence — dependency analysis, dead code detection, complexity metrics — via a FalkorDB graph database.
 
+## How to Use the Graph
+
+**All graph operations go through indusk-mcp tools.** Do not call CGC's MCP tools directly — use the `graph_*` tools from indusk-mcp instead. They handle configuration, error recovery, and provide a consistent interface whether calling the MCP server or CLI under the hood.
+
 ## When to Query the Graph
 
 - **Before modifying any file**: call `query_dependencies` to understand blast radius
-- **During planning research**: call `analyze_code_relationships` to scope work with real numbers
-- **During verification**: call `query_dependencies` with direction "dependents" to find affected tests
-- **During retrospective**: call `find_most_complex_functions` and `find_dead_code` for cleanup opportunities
+- **During planning research**: call `graph_find` and `query_dependencies` to scope work with real data
+- **During verification**: call `graph_callers` to find affected consumers, then test them
+- **During retrospective**: call `graph_find_dead_code` and `graph_complexity` for cleanup opportunities
+- **When debugging structure**: call `graph_visualize` to see the graph in the browser
 
-## Available Tools (from codegraphcontext MCP server)
+## Available Tools (all from indusk-mcp)
 
+### Core
 | Tool | When |
 |------|------|
-| `find_code` | Search by name |
-| `analyze_code_relationships` | Understand dependencies |
-| `find_most_complex_functions` | Find refactoring targets |
-| `find_dead_code` | Find unused code |
-| `execute_cypher_query` | Custom graph queries |
-| `visualize_graph_query` | Browser visualization link |
-| `get_repository_stats` | Codebase size and structure |
+| `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 |
+| `graph_stats` | Codebase size and structure overview |
+
+### Analysis
+| Tool | When |
+|------|------|
+| `graph_callers` | Find all functions that call a given function |
+| `graph_callees` | Find all functions a given function calls |
+| `graph_find` | Search for functions, classes, modules by name or content |
+| `graph_find_dead_code` | Find unused functions for cleanup |
+| `graph_complexity` | Find most complex functions for refactoring targets |
+
+### Operations
+| Tool | When |
+|------|------|
+| `graph_visualize` | Launch interactive graph UI in the browser |
+| `graph_watch` | Auto-update graph on file changes (stays current) |
+| `graph_doctor` | Diagnose graph issues (connection, config, health) |
 
 ## Visualizing
 
-When asked to "show the graph" or "display dependencies":
-1. Call `visualize_graph_query` with a Cypher query — returns a browser URL
-2. For text output, use `execute_cypher_query` and format as a table
+When asked to "show the graph", "display dependencies", or "visualize":
+1. Call `graph_visualize` — launches the interactive playground UI at http://localhost:8111
+2. For text output, use `query_graph` with a Cypher query and format as a table
+3. FalkorDB's own browser UI is also available at `falkordb.orb.local:3000`
+
+## Troubleshooting
+
+**If any graph tool fails, call `graph_doctor` first.** It checks:
+- CGC installation
+- FalkorDB connection
+- Configuration validity
+- Parser availability
+
+**Common issues:**
+- FalkorDB not running → `docker start falkordb` (or start OrbStack)
+- Repo not indexed → call `index_project`
+- Data lost after container recreation → volume was on wrong path, reindex
+- OrbStack not running → DNS resolution fails, start OrbStack app
 
 ## Setup
 
-- FalkorDB runs as a global Docker container: `falkordb.orb.local`
+- FalkorDB runs as a global Docker container at `falkordb.orb.local`
 - CGC installed via pipx: `pipx install codegraphcontext`
 - Per-project isolation via `FALKORDB_GRAPH_NAME` in `.mcp.json`
-- Index with `add_code_to_graph` or `monitor_directory`
+- Auto-watch enabled: graph updates automatically on file changes
+- SCIP indexer enabled: higher accuracy call resolution for TypeScript
+- Volume mount: `/var/lib/falkordb/data` (not `/data` — see community lesson)
+
+## Known Limitations
+
+- **Import resolution noise**: CGC creates Module nodes for every import, including npm packages (React, Next, etc.). These are orphan nodes. Filter in Cypher with `WHERE EXISTS((m)-[:CONTAINS]->())` to see only project modules.
+- **No dependency resolution control**: Can't disable Module node creation for external imports. This is a CGC limitation.

package/hooks/validate-impl-structure.js

@@ -179,13 +179,6 @@ for (const line of lines) {
 }
 if (currentPhase) phases.push(currentPhase);
 
-// Check for opt-out content in gate sections
-// Re-scan to check if sections that exist have (none needed) or skip-reason:
-const isOptedOut = (text) =>
-	text.includes("(none needed)") ||
-	text.includes("(not applicable)") ||
-	text.includes("skip-reason:");
-
 // Validate each phase
 const errors = [];
 for (const phase of phases) {

package/package.json

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

package/skills/catchup.md

@@ -40,8 +40,16 @@ Call `list_plans`. This shows every plan and its status. Pay attention to:
 - The current phase of each active plan — this is where `/work` will pick up
 - Dependencies between plans — don't start a blocked plan
 
-### 6. Check Extensions
-Call `extensions_status` to see what extensions are enabled and their capabilities. This tells you what tools are integrated and what domain knowledge is available.
+### 6. Review Skills and Extensions
+Call `extensions_status` to see what extensions are enabled and their capabilities.
+
+Then read all installed skill files in `.claude/skills/*/SKILL.md`. These define your workflows:
+- **Process skills** (plan, work, verify, context, document, retrospective) — how you build things
+- **Domain skills** (typescript, nextjs, etc.) — technology-specific best practices
+- **Extension skills** (cgc, composable-env, etc.) — tool integrations and when to use them
+- **Utility skills** (catchup, handoff, toolbelt) — operational skills
+
+Understand what each skill does and when to use it. You should be able to answer: "What slash commands are available and what do they do?"
 
 ### 7. Check Code Graph
 Call `get_repository_stats` to understand the codebase size and structure. This gives you a sense of what's indexed and queryable. If it fails, the CGC extension may not be enabled or FalkorDB may be down — check_health will have flagged this.
@@ -55,6 +63,7 @@ After completing all steps, present a brief summary to the user:
 - Handoff: [summary of last session's work, or "none"]
 - Lessons: N loaded
 - Infrastructure: [healthy / issues]
+- Skills: N installed [list names]
 - Extensions: N enabled [list names]
 - Active plans: [list with current phase]
 - Codebase: [N files indexed]