@infinitedusky/indusk-mcp 1.0.3 → 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.0.3",
+	"version": "1.1.1",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/{onboard.md → catchup.md}

@@ -1,19 +1,30 @@
 ---
-name: onboard
-description: Get a new agent caught up on the project. Reads context, plans, lessons, and code graph health in one shot. Run at the start of every new session.
+name: catchup
+description: Get caught up on the project. Reads the handoff from the last session, then context, plans, lessons, extensions, and code graph. Run at the start of every new session.
 ---
 
 You are starting a new session on this project. Before doing anything else, get caught up.
 
 ## Steps (execute in order)
 
-### 1. Read Lessons
+### 1. Read Handoff
+Check if `.claude/handoff.md` exists. If it does, read it first — this is the most recent context from the last session. It tells you:
+- What was being worked on
+- Where it stopped
+- What's next
+- Any warnings or open issues
+
+If the handoff exists, present a brief summary to the user: "Last session was working on X, stopped at Y. Ready to pick up there?"
+
+If no handoff exists, skip to step 2.
+
+### 2. Read Lessons
 Call `list_lessons`. Read every lesson. These are rules learned from past mistakes — not suggestions. Internalize them before touching any code.
 
-### 2. Check Infrastructure
+### 3. Check Infrastructure
 Call `check_health`. Verify FalkorDB and CGC are running. If unhealthy, tell the user what's down and how to fix it.
 
-### 3. Read Project Context
+### 4. Read Project Context
 Call `get_context` to read CLAUDE.md. This contains:
 - **Architecture** — what the project is, how it's structured
 - **Conventions** — rules to follow (commit style, no DB from Next.js, no fallback URLs, etc.)
@@ -23,39 +34,49 @@ Call `get_context` to read CLAUDE.md. This contains:
 
 Read it fully. Don't skim.
 
-### 4. Check Active Plans
+### 5. Check Active Plans
 Call `list_plans`. This shows every plan and its status. Pay attention to:
 - Plans with status `in-progress` — these are actively being worked on
 - The current phase of each active plan — this is where `/work` will pick up
 - Dependencies between plans — don't start a blocked plan
 
-### 5. 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?"
 
-### 6. Check Code Graph
+### 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.
 
-### 7. Summarize
+### 8. Summarize
 
-After completing steps 1-6, present a brief summary to the user:
+After completing all steps, present a brief summary to the user:
 
 ```
-**Session ready.**
+**Caught up.**
+- 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]
 
-Ready to work. What would you like to do?
+Ready to pick up. What would you like to do?
 ```
 
 ## When to Use
 
 - Start of every new Claude Code session
-- When the user says "get caught up", "what's going on", "where are we"
+- When the user says "get caught up", "what's going on", "where are we", "catch up"
 - When context was compressed and you need to re-orient
-- `/onboard` explicitly
+- `/catchup` explicitly
 
 ## Important
 

package/skills/handoff.md

@@ -0,0 +1,50 @@
+---
+name: handoff
+description: Write a handoff file before ending a session. Captures what was worked on, where it stopped, what's next, and any warnings for the next agent.
+---
+
+You are ending a session or handing off to another agent. Write a handoff file so the next session can pick up exactly where you left off.
+
+## What to Write
+
+Create or overwrite `.claude/handoff.md` with:
+
+```markdown
+# Handoff
+
+**Date:** {YYYY-MM-DD}
+**Session:** {brief description of what this session focused on}
+
+## What Was Being Worked On
+{Plan name, phase, specific checklist item. Be precise — "Phase 3 of extension-system, item 4: refactor check_health" not "working on extensions."}
+
+## Where It Stopped
+{Last thing completed. First thing that needs doing next. If mid-item, explain exactly where.}
+
+## What's Next
+{The immediate next step. Then the next 2-3 steps after that. This is the pickup point for /catchup.}
+
+## Open Issues
+{Anything broken, failing, or weird. Tests that don't pass. Errors being investigated. Things that worked before but don't now.}
+
+## Decisions Made This Session
+{Any decisions that aren't captured in CLAUDE.md or an ADR yet. These need to be formalized — they're here so they don't get lost between sessions.}
+
+## Watch Out For
+{Gotchas the next agent should know. "The FalkorDB graph needs reindexing." "The hooks aren't published yet — version 1.0.3 has them." "Don't touch init.ts until the extension system PR is merged."}
+```
+
+## When to Write a Handoff
+
+- Before ending any session where work was done
+- When the user says "let's stop here", "wrap up", "hand off"
+- When you're about to run out of context
+- `/handoff` explicitly
+
+## Rules
+
+- **Be specific.** "Working on Phase 3" is useless. "Phase 3, item 4: refactored check_health to use extensions. extensions_status MCP tool created. Next: refactor init to remove hardcoded FalkorDB/CGC." is useful.
+- **Include the ugly parts.** If something is broken, say so. The next agent needs to know.
+- **Decisions that aren't saved anywhere else MUST go here.** They'll be lost otherwise.
+- **Overwrite the previous handoff.** There's only one — the most recent session's. Old handoffs are consumed by /catchup and don't need to persist.
+- **Keep it short.** This isn't a retrospective. It's a sticky note for the next person.