whale-igniter 1.1.0

package/dist/mcp/server.js

@@ -0,0 +1,404 @@
+/**
+ * Whale Igniter MCP server.
+ *
+ * Exposes Whale's core capabilities as MCP tools so AI clients (Claude
+ * Code, Cursor, Zed, etc.) can call them directly without going through
+ * the CLI. This is the v1.0 endgame: instead of asking the user to run
+ * `whale component add Button`, the agent does it autonomously when it
+ * creates the component.
+ *
+ * Wired over stdio, the universal MCP transport. Start it from a client
+ * config (e.g. `claude_desktop_config.json`) pointing at:
+ *
+ *   { "command": "whale", "args": ["mcp", "serve"] }
+ *
+ * Design principles:
+ *
+ *   1. Read tools are non-destructive and always available. The agent
+ *      can introspect freely.
+ *   2. Write tools touch real files. They return human-readable summaries
+ *      so the agent can confirm with the user before/after.
+ *   3. Tool descriptions are written for AI consumption: they answer
+ *      "when should I call this?" not "what does this do?".
+ *   4. Errors are returned as `isError: true` content, not thrown — the
+ *      client expects the protocol shape, not exceptions.
+ */
+import path from "node:path";
+import fs from "fs-extra";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { loadConfig } from "../utils/config.js";
+import { loadComponents, upsertComponent } from "../utils/components.js";
+import { loadDecisions, appendDecision } from "../utils/decisions.js";
+import { loadRefinements, appendRefinement, inferScope } from "../utils/refinements.js";
+import { generateWiki } from "../generators/wikiGenerator.js";
+import { analyze } from "../analyzer/insights.js";
+import { collectReferencedFiles, normalizePath } from "../analyzer/imports.js";
+import { scanComponents } from "../scanner/componentScanner.js";
+import { aggregateTailwind } from "../scanner/tailwindScanner.js";
+import { validateCss } from "../validators/cssValidator.js";
+import { randomUUID } from "node:crypto";
+import { PACKAGE_VERSION } from "../version.js";
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function err(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+function jsonOk(value) {
+    return ok(JSON.stringify(value, null, 2));
+}
+/**
+ * Resolve the target workspace.
+ *
+ * Priority: explicit `target` argument > WHALE_PROJECT env var > cwd.
+ * The env var matters because MCP servers are usually launched by the
+ * client (e.g. Claude Code) and cwd may not be the user's project.
+ */
+function resolveWorkspace(target) {
+    if (target)
+        return path.resolve(target);
+    if (process.env.WHALE_PROJECT)
+        return path.resolve(process.env.WHALE_PROJECT);
+    return process.cwd();
+}
+async function ensureWhaleProject(target) {
+    const config = path.join(target, "whale.config.json");
+    if (!(await fs.pathExists(config))) {
+        return {
+            ok: false,
+            reason: `No whale.config.json found at ${target}. ` +
+                `Run \`whale ignite\` to bootstrap a workspace, or \`whale adopt\` to scan an existing project.`
+        };
+    }
+    return { ok: true };
+}
+export function buildMcpServer() {
+    const server = new McpServer({
+        name: "whale-igniter",
+        version: PACKAGE_VERSION
+    });
+    // -------------------------------------------------------------------------
+    // Read tools — always safe, used by the agent to understand the project.
+    // -------------------------------------------------------------------------
+    server.registerTool("whale_project_overview", {
+        title: "Get project overview",
+        description: "Returns the project's design-system foundations (grid, radii), stack, " +
+            "active packs, AI targets, and counts of decisions, refinements, and " +
+            "components. Call this FIRST when you don't yet have context about a project " +
+            "managed by Whale.",
+        inputSchema: {
+            target: z.string().optional().describe("Workspace path. Defaults to WHALE_PROJECT or cwd.")
+        }
+    }, async ({ target }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        const [config, decisions, refinements, components] = await Promise.all([
+            loadConfig(ws),
+            loadDecisions(ws),
+            loadRefinements(ws),
+            loadComponents(ws)
+        ]);
+        return jsonOk({
+            project: {
+                name: config.projectName,
+                type: config.projectType,
+                stack: config.stack,
+                aiTargets: config.aiTargets
+            },
+            foundations: config.foundations,
+            packs: config.packs,
+            counts: {
+                decisions: decisions.length,
+                activeDecisions: decisions.filter((d) => d.status === "active").length,
+                refinements: refinements.length,
+                components: components.length
+            },
+            ignited: config.ignited
+        });
+    });
+    server.registerTool("whale_list_components", {
+        title: "List components in the catalog",
+        description: "Returns the registered components: names, categories, variants, files. " +
+            "Use this BEFORE creating a new component, to check whether something " +
+            "similar already exists in the project.",
+        inputSchema: {
+            target: z.string().optional(),
+            category: z.string().optional().describe("Filter by category (form, navigation, surface, etc.)")
+        }
+    }, async ({ target, category }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        let components = await loadComponents(ws);
+        if (category)
+            components = components.filter((c) => c.category === category);
+        return jsonOk(components.map((c) => ({
+            name: c.name,
+            category: c.category,
+            description: c.description,
+            variants: c.variants,
+            states: c.states,
+            files: c.files
+        })));
+    });
+    server.registerTool("whale_list_decisions", {
+        title: "List recorded design / architecture decisions",
+        description: "Returns the decisions log: title, category, decision text, status. " +
+            "Call this when you're about to make a non-obvious choice that might " +
+            "already have been decided, or when answering questions about why the " +
+            "project is structured a certain way.",
+        inputSchema: {
+            target: z.string().optional(),
+            category: z.string().optional().describe("Filter by category: architecture | design-system | product | tooling | convention"),
+            activeOnly: z.boolean().optional().describe("Only show decisions with status='active' (default true).")
+        }
+    }, async ({ target, category, activeOnly }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        let decisions = await loadDecisions(ws);
+        if (activeOnly !== false)
+            decisions = decisions.filter((d) => d.status === "active");
+        if (category)
+            decisions = decisions.filter((d) => d.category === category);
+        decisions.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+        return jsonOk(decisions.map((d) => ({
+            title: d.title,
+            category: d.category,
+            status: d.status,
+            context: d.context,
+            decision: d.decision,
+            consequences: d.consequences,
+            date: d.timestamp.slice(0, 10)
+        })));
+    });
+    server.registerTool("whale_list_refinements", {
+        title: "List approved exceptions (refinements)",
+        description: "Refinements are exceptions to the design system that the team has explicitly " +
+            "approved. The validator suppresses matching issues. Call this BEFORE flagging " +
+            "something that looks like a violation — it may be a sanctioned exception.",
+        inputSchema: { target: z.string().optional() }
+    }, async ({ target }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        const refinements = await loadRefinements(ws);
+        return jsonOk(refinements.map((r) => ({
+            note: r.note,
+            scope: r.scope,
+            date: r.timestamp.slice(0, 10)
+        })));
+    });
+    server.registerTool("whale_validate", {
+        title: "Run validators on the project",
+        description: "Runs the CSS/foundation validators and returns issues found. Each issue " +
+            "has severity (error|warning), rule, file, line, and a message. Use this " +
+            "after making changes to verify they don't break the system, or to get a " +
+            "snapshot of current debt.",
+        inputSchema: { target: z.string().optional() }
+    }, async ({ target }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        const issues = await validateCss(ws);
+        return jsonOk({
+            summary: {
+                errors: issues.filter((i) => i.severity === "error").length,
+                warnings: issues.filter((i) => i.severity === "warning").length,
+                total: issues.length
+            },
+            issues
+        });
+    });
+    server.registerTool("whale_insights", {
+        title: "Run local analyzers and surface accountable recommendations",
+        description: "Returns insights about the project state: refinement clusters, decisions " +
+            "in tension, orphan components, token drift, grid drift, catalog coverage " +
+            "gaps. All deterministic, no AI. Call this when the user asks 'how is the " +
+            "project doing?' or 'what should we clean up?'.",
+        inputSchema: {
+            target: z.string().optional(),
+            skipScan: z.boolean().optional().describe("Skip source scan (faster but loses orphan/drift insights).")
+        }
+    }, async ({ target, skipScan }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        const config = await loadConfig(ws);
+        const refinements = await loadRefinements(ws);
+        const decisions = await loadDecisions(ws);
+        const components = await loadComponents(ws);
+        let referencedFiles;
+        let observations;
+        if (!skipScan) {
+            try {
+                const [refs, scanned] = await Promise.all([
+                    collectReferencedFiles(ws),
+                    scanComponents(ws)
+                ]);
+                referencedFiles = refs;
+                const allClassStrings = scanned.flatMap((c) => c.classNames);
+                observations = allClassStrings.length > 0 ? aggregateTailwind(allClassStrings) : undefined;
+            }
+            catch {
+                // Continue without scan — better partial output than failure.
+            }
+        }
+        const normalisedComponents = components.map((c) => ({
+            ...c,
+            files: c.files?.map(normalizePath)
+        }));
+        const insights = analyze({
+            config,
+            refinements,
+            decisions,
+            components: normalisedComponents,
+            observations,
+            referencedFiles
+        });
+        return jsonOk(insights);
+    });
+    // -------------------------------------------------------------------------
+    // Write tools — touch real files. Used by agents to record context as they
+    // work, so the project's memory grows automatically.
+    // -------------------------------------------------------------------------
+    server.registerTool("whale_register_component", {
+        title: "Add a component to the catalog",
+        description: "Register a component you've just created (or that you discovered during " +
+            "work) in intelligence/components.json. The user's CLAUDE.md updates " +
+            "automatically. Call this AFTER creating a component file, so future " +
+            "sessions know it exists.",
+        inputSchema: {
+            target: z.string().optional(),
+            name: z.string().describe("PascalCase component name."),
+            description: z.string().optional().describe("One-sentence description, ≤ 140 chars."),
+            category: z.string().optional().describe("form | navigation | feedback | surface | layout | data | overlay"),
+            variants: z.array(z.string()).optional().describe("Visual variants (e.g. primary, secondary)."),
+            states: z.array(z.string()).optional().describe("Interactive states (hover, focus, disabled)."),
+            files: z.array(z.string()).optional().describe("Paths relative to project root."),
+            tokens: z.array(z.string()).optional().describe("Design tokens the component depends on.")
+        }
+    }, async ({ target, name, description, category, variants, states, files, tokens }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        if (!/^[A-Z][A-Za-z0-9]*$/.test(name)) {
+            return err(`Component name must be PascalCase. Got: ${name}`);
+        }
+        const entry = await upsertComponent(ws, {
+            name,
+            description,
+            category,
+            variants,
+            states,
+            files,
+            tokens
+        });
+        await generateWiki(ws);
+        return ok(`Registered ${entry.name}. CLAUDE.md and the wiki have been regenerated.\n` +
+            `Details: category=${entry.category ?? "(none)"}, variants=${entry.variants?.join(",") ?? "(none)"}.`);
+    });
+    server.registerTool("whale_record_decision", {
+        title: "Record an architectural / product / design decision",
+        description: "Whenever you (or the user) make a non-obvious choice during work, " +
+            "record it here. Future agents and humans inherit the reasoning. " +
+            "Don't use this for trivial decisions like variable names; do use it for " +
+            "anything that took real thought: 'we chose Tailwind over CSS modules because…', " +
+            "'all controls use forwardRef so consumers can attach refs', etc.",
+        inputSchema: {
+            target: z.string().optional(),
+            title: z.string().describe("One-line summary of the decision."),
+            category: z.enum(["architecture", "design-system", "product", "tooling", "convention"]),
+            context: z.string().optional().describe("Why this came up. 1-3 sentences."),
+            decision: z.string().describe("What was decided. Concrete."),
+            consequences: z.string().optional().describe("Tradeoffs or implications.")
+        }
+    }, async ({ target, title, category, context, decision, consequences }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        const created = await appendDecision(ws, {
+            title,
+            category: category,
+            context: context?.trim() || undefined,
+            decision,
+            consequences: consequences?.trim() || undefined
+        });
+        await generateWiki(ws);
+        return ok(`Recorded decision "${created.title}" (id ${created.id.slice(0, 8)}). Wiki updated.`);
+    });
+    server.registerTool("whale_record_refinement", {
+        title: "Record an approved exception to the design system",
+        description: "Use when an apparent violation is intentional — e.g. 'Dashboard cards use " +
+            "radius 0 by design'. The validator infers scope from the note and " +
+            "suppresses matching issues. Mention an issue type (radius, spacing, hex, " +
+            "focus) in the note for the scope to attach.",
+        inputSchema: {
+            target: z.string().optional(),
+            note: z.string().describe("Plain-language explanation of the exception.")
+        }
+    }, async ({ target, note }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        const scope = inferScope(note);
+        await appendRefinement(ws, {
+            id: randomUUID(),
+            timestamp: new Date().toISOString(),
+            note,
+            scope
+        });
+        await generateWiki(ws);
+        const scopeDesc = scope
+            ? `Scope inferred: ${Object.entries(scope).map(([k, v]) => `${k}=${v}`).join(", ")}.`
+            : "No scope inferred — note recorded but validator won't act on it.";
+        return ok(`Refinement recorded. ${scopeDesc}`);
+    });
+    server.registerTool("whale_sync", {
+        title: "Regenerate CLAUDE.md and the LLM wiki",
+        description: "Regenerates the AI-readable context files from intelligence/*.json. Call " +
+            "this if you've manually edited the JSON stores and want the wiki to catch " +
+            "up. Whale auto-syncs on every recorded change, so manual calls are rarely needed.",
+        inputSchema: { target: z.string().optional() }
+    }, async ({ target }) => {
+        const ws = resolveWorkspace(target);
+        const check = await ensureWhaleProject(ws);
+        if (!check.ok)
+            return err(check.reason);
+        const { rootFiles, wikiFiles } = await generateWiki(ws);
+        return ok(`Regenerated ${rootFiles.length} root file(s) and ${wikiFiles.length} wiki file(s).\n` +
+            `Root: ${rootFiles.map((f) => path.relative(ws, f)).join(", ")}`);
+    });
+    return server;
+}
+/**
+ * Entry point used by `whale mcp serve`. Wires the server to stdio and
+ * blocks until the client disconnects. Errors during startup write to
+ * stderr so they appear in client logs; stdout is reserved for protocol.
+ */
+export async function startMcpServer() {
+    const server = buildMcpServer();
+    const transport = new StdioServerTransport();
+    try {
+        await server.connect(transport);
+        // The server runs until the client closes the transport. Don't
+        // print anything to stdout — it would corrupt the MCP framing.
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`whale mcp: server failed to start: ${msg}\n`);
+        process.exit(1);
+    }
+}