@infinitedusky/indusk-mcp 0.1.0

package/dist/tools/context-tools.js

@@ -0,0 +1,61 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { parseContext, SECTION_NAMES, updateSection, validateContext, } from "../lib/context-parser.js";
+export function registerContextTools(server, projectRoot) {
+    const claudeMdPath = join(projectRoot, "CLAUDE.md");
+    server.registerTool("get_context", {
+        description: "Returns CLAUDE.md parsed into its 6 canonical sections with validation status",
+    }, async () => {
+        const parsed = parseContext(claudeMdPath);
+        const validation = validateContext(parsed);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ ...parsed, validation }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("update_context", {
+        description: "Update a specific section of CLAUDE.md. Validates that the section exists and structure is preserved.",
+        inputSchema: {
+            section: z.enum(SECTION_NAMES).describe("The section to update"),
+            content: z.string().describe("New content for the section (replaces existing content)"),
+        },
+    }, async ({ section, content }) => {
+        // Validate current structure before modifying
+        const parsed = parseContext(claudeMdPath);
+        const validation = validateContext(parsed);
+        if (!validation.valid) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: false,
+                            error: "CLAUDE.md structure is invalid — fix manually before updating via tool",
+                            validation,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        updateSection(claudeMdPath, section, content);
+        // Validate after update
+        const afterParsed = parseContext(claudeMdPath);
+        const afterValidation = validateContext(afterParsed);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        section,
+                        structureValid: afterValidation.valid,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDocumentTools(server: McpServer, projectRoot: string): void;

package/dist/tools/document-tools.js

@@ -0,0 +1,77 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join, relative } from "node:path";
+import { parseAllPlans } from "../lib/plan-parser.js";
+function findMarkdownFiles(dir, base) {
+    if (!existsSync(dir))
+        return [];
+    const results = [];
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory() && !entry.name.startsWith(".")) {
+            results.push(...findMarkdownFiles(fullPath, base));
+        }
+        else if (entry.name.endsWith(".md")) {
+            results.push(relative(base, fullPath));
+        }
+    }
+    return results;
+}
+export function registerDocumentTools(server, projectRoot) {
+    const docsDir = join(projectRoot, "apps/indusk-docs/src");
+    server.registerTool("list_docs", {
+        description: "List all markdown files in the VitePress docs directory (apps/indusk-docs/src/)",
+    }, async () => {
+        const files = findMarkdownFiles(docsDir, docsDir);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ docsDir: "apps/indusk-docs/src", files }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("check_docs_coverage", {
+        description: "Compare completed plans to existing decision/lesson pages in the docs site. Flags plans that lack corresponding documentation.",
+    }, async () => {
+        const plans = parseAllPlans(projectRoot);
+        const completedPlans = plans.filter((p) => p.stageStatus === "completed" || p.documents.includes("retrospective.md"));
+        // Check decisions directory for matching pages
+        const decisionsDir = join(docsDir, "decisions");
+        const lessonsDir = join(docsDir, "lessons");
+        const decisionFiles = existsSync(decisionsDir)
+            ? readdirSync(decisionsDir).filter((f) => f.endsWith(".md") && f !== "index.md")
+            : [];
+        const lessonFiles = existsSync(lessonsDir)
+            ? readdirSync(lessonsDir).filter((f) => f.endsWith(".md") && f !== "index.md")
+            : [];
+        // Check each completed plan for a matching decision page
+        const coverage = completedPlans.map((plan) => {
+            const hasDecision = decisionFiles.some((f) => f.includes(plan.name));
+            const hasLesson = lessonFiles.some((f) => f.includes(plan.name));
+            return {
+                plan: plan.name,
+                stage: plan.stage,
+                stageStatus: plan.stageStatus,
+                hasDecisionPage: hasDecision,
+                hasLessonPage: hasLesson,
+                gap: !hasDecision,
+            };
+        });
+        const gaps = coverage.filter((c) => c.gap);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        completedPlans: completedPlans.length,
+                        documented: coverage.filter((c) => !c.gap).length,
+                        gaps: gaps.length,
+                        coverage,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerPlanTools(server: McpServer, projectRoot: string): void;

package/dist/tools/plan-tools.js

@@ -0,0 +1,158 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { getAllPhaseCompletions, parseImpl } from "../lib/impl-parser.js";
+import { parseAllPlans, parsePlan } from "../lib/plan-parser.js";
+export function registerPlanTools(server, projectRoot) {
+    server.registerTool("list_plans", {
+        description: "List all plans in the planning/ directory with their stage, status, next step, and dependencies",
+    }, async () => {
+        const plans = parseAllPlans(projectRoot);
+        return {
+            content: [{ type: "text", text: JSON.stringify(plans, null, 2) }],
+        };
+    });
+    server.registerTool("get_plan_status", {
+        description: "Get detailed status of a specific plan including phase progress and blocked items",
+        inputSchema: { name: z.string().describe("Plan directory name (e.g. 'mcp-dev-system')") },
+    }, async ({ name }) => {
+        const planDir = join(projectRoot, "planning", name);
+        const plan = parsePlan(planDir);
+        const implPath = join(planDir, "impl.md");
+        const impl = parseImpl(implPath);
+        const completions = impl.phases.length > 0 ? getAllPhaseCompletions(impl) : [];
+        const result = {
+            ...plan,
+            implStatus: impl.status,
+            phases: completions,
+        };
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    server.registerTool("advance_plan", {
+        description: "Validate whether a plan can advance to the next stage. Returns what is missing if blocked.",
+        inputSchema: { name: z.string().describe("Plan directory name") },
+    }, async ({ name }) => {
+        const planDir = join(projectRoot, "planning", name);
+        const plan = parsePlan(planDir);
+        const implPath = join(planDir, "impl.md");
+        const impl = parseImpl(implPath);
+        const respond = (result) => ({
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        });
+        // Brief → ADR: brief status must be "accepted"
+        if (plan.stage === "brief") {
+            if (plan.stageStatus === "accepted") {
+                return respond({ allowed: true, transition: "brief → adr", nextStage: "Create adr" });
+            }
+            return respond({
+                allowed: false,
+                transition: "brief → adr",
+                missing: [`Brief status is '${plan.stageStatus}', must be 'accepted'`],
+            });
+        }
+        // ADR → Impl: ADR status must be "accepted"
+        if (plan.stage === "adr") {
+            if (plan.stageStatus === "accepted") {
+                return respond({ allowed: true, transition: "adr → impl", nextStage: "Create impl" });
+            }
+            return respond({
+                allowed: false,
+                transition: "adr → impl",
+                missing: [`ADR status is '${plan.stageStatus}', must be 'accepted'`],
+            });
+        }
+        // Impl phases and impl → retrospective
+        if (plan.stage === "impl" && impl.phases.length > 0) {
+            const completions = getAllPhaseCompletions(impl);
+            const currentPhase = completions.find((c) => !c.complete);
+            if (currentPhase) {
+                const missing = [];
+                for (const [gate, items] of Object.entries(currentPhase.uncheckedByGate)) {
+                    for (const item of items) {
+                        missing.push(`[${gate}] ${item}`);
+                    }
+                }
+                return respond({
+                    allowed: false,
+                    transition: `phase ${currentPhase.phase} → phase ${currentPhase.phase + 1}`,
+                    currentPhase: currentPhase.phase,
+                    phaseName: currentPhase.name,
+                    missing,
+                });
+            }
+            // All phases complete — check impl status for retrospective
+            if (impl.status !== "completed") {
+                return respond({
+                    allowed: false,
+                    transition: "impl → retrospective",
+                    missing: ["Impl status is not 'completed' — update frontmatter status"],
+                });
+            }
+            return respond({
+                allowed: true,
+                transition: "impl → retrospective",
+                nextStage: "Create retrospective",
+            });
+        }
+        // Research or other stages
+        if (plan.stageStatus === "accepted" || plan.stageStatus === "completed") {
+            return respond({ allowed: true, nextStage: plan.nextStep });
+        }
+        return respond({
+            allowed: false,
+            missing: [`${plan.stage} status is '${plan.stageStatus}', needs 'accepted' or 'completed'`],
+        });
+    });
+    server.registerTool("order_plans", {
+        description: "Get plan execution order based on dependencies (topological sort)",
+    }, async () => {
+        const plans = parseAllPlans(projectRoot);
+        // Topological sort via Kahn's algorithm
+        const inDegree = new Map();
+        const adj = new Map();
+        for (const plan of plans) {
+            inDegree.set(plan.name, 0);
+            adj.set(plan.name, []);
+        }
+        for (const plan of plans) {
+            for (const dep of plan.dependencies) {
+                if (adj.has(dep)) {
+                    adj.get(dep)?.push(plan.name);
+                    inDegree.set(plan.name, (inDegree.get(plan.name) ?? 0) + 1);
+                }
+            }
+        }
+        const queue = [];
+        for (const [name, degree] of inDegree) {
+            if (degree === 0)
+                queue.push(name);
+        }
+        const ordered = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (!current)
+                break;
+            ordered.push(current);
+            for (const neighbor of adj.get(current) ?? []) {
+                const newDegree = (inDegree.get(neighbor) ?? 1) - 1;
+                inDegree.set(neighbor, newDegree);
+                if (newDegree === 0)
+                    queue.push(neighbor);
+            }
+        }
+        const plansByName = new Map(plans.map((p) => [p.name, p]));
+        const result = ordered.map((name) => {
+            const plan = plansByName.get(name);
+            return {
+                name,
+                stage: plan?.stage,
+                stageStatus: plan?.stageStatus,
+                dependencies: plan?.dependencies ?? [],
+            };
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerQualityTools(server: McpServer, projectRoot: string): void;

package/dist/tools/quality-tools.js

@@ -0,0 +1,130 @@
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+function parseBiomeOutput(output) {
+    const diagnostics = [];
+    // Biome outputs diagnostics in a format like:
+    // file.ts:line:col lint/category/ruleName  LEVEL  ━━━
+    //   message text
+    const diagRegex = /^(.+?):(\d+):(\d+)\s+([\w/]+)\s+(?:FIXABLE\s+)?/gm;
+    let match = diagRegex.exec(output);
+    while (match) {
+        diagnostics.push({
+            file: match[1],
+            line: Number.parseInt(match[2], 10),
+            column: Number.parseInt(match[3], 10),
+            rule: match[4],
+            message: "",
+            severity: "error",
+        });
+        match = diagRegex.exec(output);
+    }
+    // Also catch the info-level diagnostics
+    const infoRegex = /^(.+?):(\d+):(\d+)\s+([\w/]+)\s+FIXABLE/gm;
+    for (let infoMatch = infoRegex.exec(output); infoMatch !== null; infoMatch = infoRegex.exec(output)) {
+        const file = infoMatch[1];
+        const line = Number.parseInt(infoMatch[2], 10);
+        const rule = infoMatch[4];
+        const existing = diagnostics.find((d) => d.file === file && d.line === line && d.rule === rule);
+        if (existing) {
+            existing.severity = "info";
+        }
+    }
+    return diagnostics;
+}
+export function registerQualityTools(server, projectRoot) {
+    server.registerTool("get_quality_config", {
+        description: "Read biome.json and biome-rationale.md, returning the quality config as structured data",
+    }, async () => {
+        const biomePath = join(projectRoot, "biome.json");
+        const rationalePath = join(projectRoot, "biome-rationale.md");
+        const biomeConfig = existsSync(biomePath)
+            ? JSON.parse(readFileSync(biomePath, "utf-8"))
+            : null;
+        const rationale = existsSync(rationalePath) ? readFileSync(rationalePath, "utf-8") : null;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ biomeConfig, rationale }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("suggest_rule", {
+        description: "Given a mistake description, suggest Biome rules that could prevent it. Searches the installed Biome rule catalog.",
+        inputSchema: {
+            description: z.string().describe("Description of the mistake or pattern to prevent"),
+        },
+    }, async ({ description }) => {
+        // Get the list of rules from biome rage
+        let rulesOutput;
+        try {
+            rulesOutput = execSync("npx biome rage --linter", {
+                cwd: projectRoot,
+                encoding: "utf-8",
+                timeout: 15000,
+            });
+        }
+        catch {
+            rulesOutput = "";
+        }
+        // Search for keywords from the description in the rules list
+        const keywords = description
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((w) => w.length > 3);
+        const lines = rulesOutput.split("\n");
+        const matches = lines.filter((line) => {
+            const lower = line.toLowerCase();
+            return keywords.some((kw) => lower.includes(kw));
+        });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        query: description,
+                        keywords,
+                        suggestions: matches.length > 0
+                            ? matches.slice(0, 20)
+                            : ["No matching rules found — consider a custom approach or check biome docs"],
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("quality_check", {
+        description: "Run `biome check` and return structured results with file, line, rule, and severity",
+    }, async () => {
+        let output;
+        let exitCode;
+        try {
+            output = execSync("npx biome check", {
+                cwd: projectRoot,
+                encoding: "utf-8",
+                timeout: 30000,
+            });
+            exitCode = 0;
+        }
+        catch (err) {
+            const execErr = err;
+            output = (execErr.stdout ?? "") + (execErr.stderr ?? "");
+            exitCode = execErr.status ?? 1;
+        }
+        const diagnostics = parseBiomeOutput(output);
+        const passed = exitCode === 0;
+        // Extract the summary line
+        const summaryMatch = output.match(/Checked \d+ files?.*/);
+        const summary = summaryMatch ? summaryMatch[0] : "";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ passed, exitCode, summary, diagnostics }, null, 2),
+                },
+            ],
+        };
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerSystemTools(server: McpServer, projectRoot: string): void;

package/dist/tools/system-tools.js

@@ -0,0 +1,147 @@
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(__dirname, "../..");
+function fileHash(path) {
+    return createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 12);
+}
+export function registerSystemTools(server, projectRoot) {
+    server.registerTool("get_system_version", {
+        description: "Return the installed indusk-mcp package version",
+    }, async () => {
+        const pkgPath = join(packageRoot, "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ name: pkg.name, version: pkg.version }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("check_health", {
+        description: "Check health of dev system dependencies: FalkorDB connectivity, CGC installation, and Docker container status. Errors indicate the system is degraded.",
+    }, async () => {
+        const checks = [];
+        // Check FalkorDB TCP connectivity
+        const falkordbHost = process.env.FALKORDB_HOST ?? "localhost";
+        const falkordbPort = Number.parseInt(process.env.FALKORDB_PORT ?? "6379", 10);
+        const falkordbOk = await new Promise((resolve) => {
+            const socket = createConnection({ host: falkordbHost, port: falkordbPort }, () => {
+                socket.destroy();
+                resolve(true);
+            });
+            socket.setTimeout(3000);
+            socket.on("timeout", () => {
+                socket.destroy();
+                resolve(false);
+            });
+            socket.on("error", () => {
+                resolve(false);
+            });
+        });
+        checks.push({
+            name: "falkordb",
+            status: falkordbOk ? "ok" : "error",
+            detail: falkordbOk
+                ? `Connected to ${falkordbHost}:${falkordbPort}`
+                : `Cannot connect to FalkorDB at ${falkordbHost}:${falkordbPort} — run: docker start falkordb`,
+        });
+        // Check CGC installed — cgc prints version to stderr, so check binary exists
+        const cgcPaths = [join(process.env.HOME ?? "", ".local/bin/cgc"), "/usr/local/bin/cgc"];
+        const cgcPath = cgcPaths.find((p) => existsSync(p));
+        checks.push({
+            name: "codegraphcontext",
+            status: cgcPath ? "ok" : "error",
+            detail: cgcPath
+                ? `CGC found at ${cgcPath}`
+                : "CGC not found — install via: pipx install codegraphcontext",
+        });
+        // Check FalkorDB Docker container
+        let containerRunning = false;
+        try {
+            const ps = execSync('docker ps --filter name=falkordb --format "{{.Status}}"', {
+                encoding: "utf-8",
+                timeout: 5000,
+                stdio: ["ignore", "pipe", "pipe"],
+            }).trim();
+            containerRunning = ps.length > 0;
+            checks.push({
+                name: "falkordb-container",
+                status: containerRunning ? "ok" : "error",
+                detail: containerRunning
+                    ? `Container status: ${ps}`
+                    : "FalkorDB container not running — run: docker start falkordb",
+            });
+        }
+        catch {
+            checks.push({
+                name: "falkordb-container",
+                status: "error",
+                detail: "Docker not available or falkordb container not found",
+            });
+        }
+        const healthy = checks.every((c) => c.status === "ok");
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ healthy, checks }, null, 2),
+                },
+            ],
+            isError: !healthy,
+        };
+    });
+    server.registerTool("get_skill_versions", {
+        description: "Compare installed skills in .claude/skills/ to package skills. Returns status per skill: installed, current, or outdated.",
+    }, async () => {
+        const skillsSource = join(packageRoot, "skills");
+        const skillsTarget = join(projectRoot, ".claude/skills");
+        if (!existsSync(skillsSource)) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: "Package skills directory not found" }, null, 2),
+                    },
+                ],
+            };
+        }
+        const packageSkills = readdirSync(skillsSource).filter((f) => f.endsWith(".md"));
+        const skills = packageSkills.map((file) => {
+            const skillName = file.replace(".md", "");
+            const sourceFile = join(skillsSource, file);
+            const targetFile = join(skillsTarget, skillName, "SKILL.md");
+            const packageHash = fileHash(sourceFile);
+            const installed = existsSync(targetFile);
+            const installedHash = installed ? fileHash(targetFile) : null;
+            return {
+                name: skillName,
+                installed,
+                current: installed && packageHash === installedHash,
+                packageHash,
+                installedHash,
+            };
+        });
+        const summary = {
+            total: skills.length,
+            installed: skills.filter((s) => s.installed).length,
+            current: skills.filter((s) => s.current).length,
+            outdated: skills.filter((s) => s.installed && !s.current).length,
+            missing: skills.filter((s) => !s.installed).length,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ summary, skills }, null, 2),
+                },
+            ],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@infinitedusky/indusk-mcp",
+	"version": "0.1.0",
+	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
+	"type": "module",
+	"files": [
+		"dist",
+		"skills",
+		"templates",
+		"!dist/**/*.test.*",
+		"!dist/__tests__"
+	],
+	"bin": {
+		"indusk": "dist/bin/cli.js",
+		"dev-system": "dist/bin/cli.js"
+	},
+	"exports": {
+		".": "./dist/server/index.js"
+	},
+	"scripts": {
+		"dev": "tsx watch src/server/index.ts",
+		"build": "tsc",
+		"start": "node dist/server/index.js",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.1",
+		"commander": "^13.0.0",
+		"glob": "^11.0.0",
+		"gray-matter": "^4.0.3",
+		"zod": "^4.3.6"
+	},
+	"devDependencies": {
+		"@types/node": "^22.0.0",
+		"tsx": "^4.19.0",
+		"typescript": "^5.7.0"
+	}
+}