@infinitedusky/indusk-mcp 1.5.2 → 1.5.4

package/dist/bin/commands/extensions.js

@@ -78,6 +78,7 @@ export async function extensionsEnable(projectRoot, names) {
         // Check if already enabled
         if (isEnabled(projectRoot, name)) {
             console.info(`  ${name}: already enabled`);
+            printMcpSetup(projectRoot, name);
             continue;
         }
         // Try to move from disabled
@@ -85,6 +86,7 @@ export async function extensionsEnable(projectRoot, names) {
             console.info(`  ${name}: enabled (was disabled)`);
             runHook(projectRoot, name, "on_init");
             installSkill(projectRoot, name);
+            printMcpSetup(projectRoot, name);
             continue;
         }
         // Try to copy from built-in
@@ -96,6 +98,7 @@ export async function extensionsEnable(projectRoot, names) {
             console.info(`  ${name}: enabled (built-in)`);
             runHook(projectRoot, name, "on_init");
             installSkill(projectRoot, name);
+            printMcpSetup(projectRoot, name);
             continue;
         }
         console.info(`  ${name}: not found — use 'extensions add ${name} --from <source>' for third-party`);
@@ -480,6 +483,56 @@ function runHook(projectRoot, name, hook) {
         console.info(`  ${name}: ${hook} hook failed`);
     }
 }
+function printMcpSetup(projectRoot, name) {
+    const manifestPath = resolveManifestPath(extensionsDir(projectRoot), name);
+    if (!manifestPath) {
+        // Try built-in
+        const builtinPath = join(builtinDir, name, "manifest.json");
+        if (!existsSync(builtinPath))
+            return;
+        const manifest = loadExtension(builtinPath);
+        if (!manifest?.mcp_server)
+            return;
+        printMcpInstructions(name, manifest);
+        return;
+    }
+    const manifest = loadExtension(manifestPath);
+    if (!manifest?.mcp_server)
+        return;
+    printMcpInstructions(name, manifest);
+}
+function printMcpInstructions(name, manifest) {
+    const server = manifest.mcp_server;
+    if (!server)
+        return;
+    const needsAuth = server.headers && Object.keys(server.headers).length > 0;
+    // Auto-run claude mcp add for no-auth HTTP servers
+    if (!needsAuth && server.type === "http" && server.url) {
+        const cmd = `claude mcp add -t http -s project -- ${name} ${server.url}`;
+        console.info(`\n  ${name}: adding MCP server...`);
+        try {
+            execSync(cmd, { timeout: 15000, stdio: ["ignore", "pipe", "pipe"] });
+            console.info(`  ${name}: MCP server added (restart Claude Code to load)`);
+        }
+        catch {
+            console.info(`  ${name}: auto-add failed. Run manually:`);
+            console.info(`    ${cmd}`);
+        }
+        return;
+    }
+    // For servers needing auth, print setup instructions
+    if (server.setup_instructions?.length) {
+        console.info(`\n  ${name} MCP setup:`);
+        for (const instruction of server.setup_instructions) {
+            console.info(`    ${instruction}`);
+        }
+    }
+    else if (server.type === "http" && server.url) {
+        console.info(`\n  ${name} MCP setup:`);
+        console.info(`    claude mcp add -t http -- ${name} ${server.url}`);
+    }
+    console.info("");
+}
 function installSkill(projectRoot, name) {
     const manifestPath = resolveManifestPath(extensionsDir(projectRoot), name);
     if (!manifestPath)

package/extensions/excalidraw/manifest.json

@@ -0,0 +1,14 @@
+{
+	"name": "excalidraw",
+	"description": "Hand-drawn diagrams via Excalidraw MCP — conceptual sketches, architecture visuals, debug illustrations",
+	"provides": {
+		"skill": true
+	},
+	"mcp_server": {
+		"type": "http",
+		"url": "https://mcp.excalidraw.com",
+		"setup_instructions": [
+			"claude mcp add -t http -- excalidraw https://mcp.excalidraw.com"
+		]
+	}
+}

package/extensions/excalidraw/skill.md

@@ -0,0 +1,55 @@
+# Excalidraw — Hand-Drawn Diagrams
+
+Excalidraw creates hand-drawn style diagrams directly in chat. Use it for quick visual communication — architecture sketches, debug illustrations, conceptual overviews.
+
+## When to Use Excalidraw vs Mermaid
+
+| Need | Tool | Why |
+|------|------|-----|
+| Architecture overview for a brief or ADR | **Excalidraw** | Conceptual, hand-drawn feel |
+| Sequence diagram in VitePress docs | **Mermaid** | Text-based, diffs in git, renders natively |
+| Quick sketch during debugging | **Excalidraw** | Fast, visual, natural language |
+| Flowchart in a docs page | **Mermaid** | Version-controlled, embedded in markdown |
+| Conceptual diagram during teach mode | **Excalidraw** | Approachable, not overly formal |
+| Class/entity relationship for reference docs | **Mermaid** | Precise, structured, text-diffable |
+
+**Rule of thumb:** If it goes in the docs site, use Mermaid. If it's for in-session communication, use Excalidraw.
+
+## How to Describe Diagrams
+
+Be specific about components, connections, and layout. The more concrete the description, the better the result.
+
+**Good descriptions:**
+- "Draw an architecture diagram showing game-server connected to postgres and redis, with poker-app and dealer-app connecting to game-server via WebSocket, and admin-app connecting via HTTP REST"
+- "Sketch the data flow: user action → WebSocket → game-server → advanceHand → broadcast state → all connected clients"
+- "Draw a box diagram showing the three layers: Next.js apps on top, game-server in the middle, database + redis at the bottom, with arrows showing the communication patterns"
+
+**Bad descriptions:**
+- "Draw the architecture" (too vague)
+- "Make a diagram" (no context)
+- "Show how it works" (which part?)
+
+## Setup
+
+The Excalidraw MCP server is a **remote hosted service** — no npm package, no install, no auth.
+
+```bash
+claude mcp add -t http -- excalidraw https://mcp.excalidraw.com
+```
+
+That's it. No tokens, no config files, no environment variables.
+
+## When to Create Diagrams
+
+- **During `/plan` research or brief**: sketch the proposed architecture to make it concrete
+- **During `/work` teach mode**: visualize what a phase is building before and after
+- **During debugging**: draw the request flow to identify where things break
+- **During retrospective**: before/after architecture comparison
+- **When the user asks**: "draw this", "sketch that", "visualize the flow"
+
+## Limitations
+
+- Diagrams are in-session only — they don't persist to files automatically
+- No version control (unlike Mermaid text)
+- Depends on remote server availability
+- Quality depends on description specificity

package/package.json

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

package/skills/document.md

@@ -108,10 +108,26 @@ The changelog lives at `changelog.md` in the docs site. It uses [Keep a Changelo
 
 The `decisions/` and `lessons/` directories are **not** populated during normal impl work. They are populated during the retrospective/archival process by the retrospective skill. Don't write to them during `/work`.
 
-## Mermaid Diagrams
+## Diagrams
 
 **Prefer diagrams over long prose for architecture, flows, and relationships.** A well-labeled diagram communicates structure faster than paragraphs of text.
 
+### Mermaid vs Excalidraw
+
+Two diagram tools are available. Use the right one for the context:
+
+| Need | Tool | Why |
+|------|------|-----|
+| Formal diagram in the docs site | **Mermaid** | Text-based, diffs in git, renders natively in VitePress |
+| Conceptual sketch during a session | **Excalidraw** | Hand-drawn style, natural language input, fast |
+| Sequence/flowchart for reference docs | **Mermaid** | Structured, precise, version-controlled |
+| Architecture overview for a brief or ADR | **Excalidraw** | Approachable, whiteboard feel |
+| Debug illustration | **Excalidraw** | Quick visual communication |
+
+**Rule of thumb:** If it goes in the docs site, use Mermaid. If it's for in-session communication, use Excalidraw. If the Excalidraw extension isn't enabled, use Mermaid for everything.
+
+## Mermaid Diagrams
+
 ### When to Use Which Diagram Type
 
 | Scenario | Diagram Type | Example |

package/skills/plan.md

@@ -72,7 +72,7 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
    For feature/spike workflows that need new research: Explore the problem space — read code, search the web, check Context7 for library docs. **Query the code graph before scoping** (see toolbelt "Before Modifying Code") — include structural findings in research.md with concrete numbers.
    Document what you find. The research doc records findings and analysis, but saves the recommendation for the brief.
 
-4. **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 the brief and have a conversation about it.** Don't just ask "does this look good?" — walk the user through it: "Here's what I'm proposing we build. Does this match what you had in mind? Is there anything missing, or anything here you don't want?" Iterate until the user is genuinely happy with the direction, then mark it as `accepted`.
+4. **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. **Consider creating a visual sketch** of the proposed architecture with Excalidraw (if the extension is enabled) — a hand-drawn diagram makes the proposal concrete and easier to discuss. **Present the brief and have a conversation about it.** Don't just ask "does this look good?" — walk the user through it: "Here's what I'm proposing we build. Does this match what you had in mind? Is there anything missing, or anything here you don't want?" Iterate until the user is genuinely happy with the direction, then mark it as `accepted`.
 
 5. **If brief is accepted** and the workflow includes an ADR (feature only), write the ADR. The ADR formalizes the decisions that were discussed during research and led to the brief. It records what was chosen, what was rejected, and why. **After the ADR is accepted**, add a one-liner to CLAUDE.md's Key Decisions section per the context skill: `- {decision summary} — see planning/{plan}/adr.md`