capy-mcp 1.0.1 → 1.0.2

package/README.md

@@ -6,9 +6,10 @@ It does not generate the preview page itself. It gives an AI coding agent the re
 
 ## What it exposes
 
-The server currently registers one MCP tool:
+The server currently registers two MCP tools:
 
 - `get_preview_brief`
+- `get_design_system`
 
 The tool accepts:
 
@@ -26,6 +27,8 @@ The tool returns structured content with:
 - `warnings`
 - `instructions`
 
+`get_design_system` writes a stable JSON artifact, by default at `.capy/design-system.json`, and returns a summary plus the artifact contents. This file is meant to be the machine-readable source of truth that later coding sessions can load before making UI changes.
+
 ## Install
 
 ```bash
@@ -56,12 +59,19 @@ Example stdio MCP config:
 ## Library usage
 
 ```ts
-import { buildPreviewBrief, detectFramework } from "capy-mcp";
+import {
+  buildDesignSystemArtifact,
+  buildPreviewBrief,
+  detectFramework,
+  writeDesignSystemArtifact,
+} from "capy-mcp";
 
 const framework = await detectFramework(process.cwd());
 const brief = await buildPreviewBrief(process.cwd(), {
   task: "build_preview",
 });
+const designSystem = await buildDesignSystemArtifact(process.cwd());
+await writeDesignSystemArtifact(process.cwd());
 ```
 
 ## Local development

package/dist/brief.js

@@ -1,7 +1,5 @@
-import { glob } from "glob";
-import { join } from "path";
 import { detectFramework } from "./framework.js";
-import { fileExists, toPosixPath } from "./files.js";
+import { buildProjectFacts } from "./project.js";
 const SECTION_ORDER = [
     "Foundations",
     "Colors",
@@ -39,37 +37,6 @@ export async function buildPreviewBrief(projectRoot, input) {
         instructions: buildInstructions(projectFacts, input),
     };
 }
-async function buildProjectFacts(projectRoot, framework) {
-    const componentDirs = await findExistingDirectories(projectRoot, [
-        "src/components",
-        "src/ui",
-        "src/features",
-        "components",
-        "ui",
-        "features",
-    ]);
-    const pageDirs = await findExistingDirectories(projectRoot, [
-        "src/app",
-        "app",
-        "src/pages",
-        "pages",
-        "src/routes",
-        "routes",
-    ]);
-    const styleFiles = await findStyleFiles(projectRoot);
-    const likelyUiDirs = Array.from(new Set([...componentDirs, ...pageDirs.filter((dir) => !dir.endsWith("/preview"))]));
-    return {
-        framework: framework.kind,
-        routingStyle: framework.routingStyle,
-        previewRoute: framework.previewRoute,
-        previewEntryFile: framework.previewEntryFile,
-        packageManager: framework.packageManager,
-        likelyComponentDirs: componentDirs,
-        likelyStyleFiles: styleFiles,
-        likelyPageDirs: pageDirs,
-        likelyUiDirs,
-    };
-}
 function buildInspectionPlan(projectFacts) {
     const appShellTargets = uniqueCompact([
         firstMatching(projectFacts.likelyPageDirs, "src/app")
@@ -154,33 +121,6 @@ function buildInstructions(projectFacts, input) {
     const userGoal = input.userGoal ? ` User goal: ${input.userGoal}.` : "";
     return `${lead}${userGoal} Read the app shell first, then global styles, then component directories. After that, implement ${projectFacts.previewEntryFile} as a vertically scrollable preview surface using the repo's real design language and existing components.`;
 }
-async function findExistingDirectories(projectRoot, candidates) {
-    const results = [];
-    for (const candidate of candidates) {
-        if (await fileExists(join(projectRoot, candidate))) {
-            results.push(candidate);
-        }
-    }
-    return results;
-}
-async function findStyleFiles(projectRoot) {
-    const files = await glob(["**/*.{css,scss,sass,less}"], {
-        cwd: projectRoot,
-        nodir: true,
-        ignore: [
-            "**/node_modules/**",
-            "**/.next/**",
-            "**/dist/**",
-            "**/build/**",
-            "**/.capy/**",
-            "**/coverage/**",
-        ],
-    });
-    return files
-        .map((file) => toPosixPath(file))
-        .filter((file) => !file.includes("/preview/"))
-        .sort();
-}
 function uniqueCompact(values) {
     return Array.from(new Set(values.filter(Boolean)));
 }

package/dist/design-system.d.ts

@@ -0,0 +1,3 @@
+import type { DesignSystemArtifact, DesignSystemBuildInput } from "./types.js";
+export declare function buildDesignSystemArtifact(projectRoot: string, input?: DesignSystemBuildInput): Promise<DesignSystemArtifact>;
+export declare function writeDesignSystemArtifact(projectRoot: string, input?: DesignSystemBuildInput): Promise<DesignSystemArtifact>;

package/dist/design-system.js

@@ -0,0 +1,176 @@
+import { glob } from "glob";
+import { basename, join } from "path";
+import { buildPreviewBrief } from "./brief.js";
+import { readText, toPosixPath, writeText } from "./files.js";
+import { detectFramework } from "./framework.js";
+import { buildProjectFacts } from "./project.js";
+const DEFAULT_ARTIFACT_PATH = ".capy/design-system.json";
+export async function buildDesignSystemArtifact(projectRoot, input = {}) {
+    const framework = await detectFramework(projectRoot);
+    const projectFacts = await buildProjectFacts(projectRoot, framework);
+    const previewBrief = await buildPreviewBrief(projectRoot, {
+        task: input.mode === "update" ? "update_preview" : "build_preview",
+        changedFiles: input.changedFiles,
+        userGoal: input.userGoal,
+    });
+    const cssVariables = await collectCssVariables(projectRoot, projectFacts.likelyStyleFiles);
+    const components = await collectComponents(projectRoot, projectFacts);
+    const artifactPath = input.artifactPath ?? DEFAULT_ARTIFACT_PATH;
+    const sourceFiles = Array.from(new Set([
+        ...projectFacts.likelyStyleFiles,
+        ...components.map((component) => component.path),
+    ])).sort();
+    return {
+        meta: {
+            generatedAt: new Date().toISOString(),
+            mode: input.mode ?? "build",
+            artifactPath,
+            framework: framework.kind,
+            routingStyle: framework.routingStyle,
+            previewRoute: framework.previewRoute,
+            previewEntryFile: framework.previewEntryFile,
+            packageManager: framework.packageManager,
+            changedFiles: input.changedFiles ?? [],
+            sourceFiles,
+        },
+        directories: {
+            componentDirs: projectFacts.likelyComponentDirs,
+            pageDirs: projectFacts.likelyPageDirs,
+            styleFiles: projectFacts.likelyStyleFiles,
+            uiDirs: projectFacts.likelyUiDirs,
+        },
+        tokens: {
+            cssVariables,
+            styleFiles: projectFacts.likelyStyleFiles,
+        },
+        components,
+        preview: {
+            route: projectFacts.previewRoute,
+            entryFile: projectFacts.previewEntryFile,
+            sections: previewBrief.deliverableSpec.sections,
+            updateStrategy: previewBrief.updateStrategy,
+        },
+        guidance: {
+            summary: buildSummary(projectFacts, framework, components, cssVariables),
+            warnings: previewBrief.warnings,
+            instructions: [
+                "Read this file before making UI changes or updating /preview.",
+                "Prefer the listed components, tokens, and preview sections over inventing new UI structure.",
+                input.mode === "update"
+                    ? "When updating, inspect changedFiles first and only refresh affected sections unless foundations changed."
+                    : "If this artifact looks incomplete, inspect the listed sourceFiles before expanding it.",
+            ],
+        },
+    };
+}
+export async function writeDesignSystemArtifact(projectRoot, input = {}) {
+    const artifact = await buildDesignSystemArtifact(projectRoot, input);
+    const artifactFile = join(projectRoot, artifact.meta.artifactPath);
+    await writeText(artifactFile, `${JSON.stringify(artifact, null, 2)}\n`);
+    return artifact;
+}
+async function collectCssVariables(projectRoot, styleFiles) {
+    const variables = [];
+    for (const relativePath of styleFiles) {
+        const fileContents = await readText(join(projectRoot, relativePath));
+        if (!fileContents)
+            continue;
+        const regex = /--([A-Za-z0-9-_]+)\s*:\s*([^;}{]+);/g;
+        let match;
+        while ((match = regex.exec(fileContents)) !== null) {
+            variables.push({
+                name: `--${match[1]}`,
+                value: match[2].trim(),
+                category: classifyCssVariable(match[1]),
+                file: relativePath,
+                line: lineNumberAt(fileContents, match.index),
+            });
+        }
+    }
+    return variables;
+}
+async function collectComponents(projectRoot, projectFacts) {
+    if (projectFacts.likelyComponentDirs.length === 0) {
+        return [];
+    }
+    const patterns = projectFacts.likelyComponentDirs.map((dir) => `${dir}/**/*.{tsx,jsx,ts,js}`);
+    const files = await glob(patterns, {
+        cwd: projectRoot,
+        nodir: true,
+        ignore: [
+            "**/*.test.*",
+            "**/*.spec.*",
+            "**/*.stories.*",
+            "**/*.story.*",
+            "**/node_modules/**",
+            "**/.next/**",
+            "**/dist/**",
+            "**/build/**",
+            "**/coverage/**",
+            "**/preview/**",
+        ],
+    });
+    const componentRecords = await Promise.all(files
+        .map((file) => toPosixPath(file))
+        .sort()
+        .map(async (relativePath) => {
+        const contents = await readText(join(projectRoot, relativePath));
+        const exports = contents ? extractExports(contents) : [];
+        const fallbackName = basename(relativePath).replace(/\.[^.]+$/, "");
+        return {
+            name: exports[0] ?? fallbackName,
+            path: relativePath,
+            exports,
+            kind: classifyComponentKind(relativePath),
+        };
+    }));
+    return componentRecords;
+}
+function buildSummary(projectFacts, framework, components, cssVariables) {
+    return [
+        `Framework: ${framework.label}.`,
+        `Preview target: ${projectFacts.previewEntryFile}.`,
+        `Found ${components.length} component candidates and ${cssVariables.length} CSS variables.`,
+        "Use this artifact as the canonical machine-readable UI map before editing the app or /preview.",
+    ].join(" ");
+}
+function extractExports(contents) {
+    const exports = new Set();
+    const patterns = [
+        /export\s+function\s+([A-Z][A-Za-z0-9_]*)/g,
+        /export\s+const\s+([A-Z][A-Za-z0-9_]*)/g,
+        /export\s+class\s+([A-Z][A-Za-z0-9_]*)/g,
+        /export\s+default\s+function\s+([A-Z][A-Za-z0-9_]*)/g,
+    ];
+    for (const pattern of patterns) {
+        let match;
+        while ((match = pattern.exec(contents)) !== null) {
+            exports.add(match[1]);
+        }
+    }
+    return Array.from(exports);
+}
+function classifyComponentKind(relativePath) {
+    if (relativePath.includes("/features/"))
+        return "feature";
+    if (relativePath.includes("/ui/"))
+        return "primitive";
+    if (relativePath.includes("/components/"))
+        return "component";
+    return "unknown";
+}
+function classifyCssVariable(name) {
+    if (/(color|bg|text|border|surface|accent|primary|secondary|foreground)/i.test(name)) {
+        return "color";
+    }
+    if (/(font|type|text|leading|tracking|heading|body)/i.test(name)) {
+        return "typography";
+    }
+    if (/(space|spacing|gap|radius|shadow|size|width|height)/i.test(name)) {
+        return "layout";
+    }
+    return "other";
+}
+function lineNumberAt(contents, index) {
+    return contents.slice(0, index).split("\n").length;
+}

package/dist/files.d.ts

@@ -1,3 +1,4 @@
 export declare function fileExists(path: string): Promise<boolean>;
 export declare function readText(path: string): Promise<string | null>;
+export declare function writeText(path: string, contents: string): Promise<void>;
 export declare function toPosixPath(path: string): string;

package/dist/files.js

@@ -1,4 +1,5 @@
-import { readFile, stat } from "fs/promises";
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { dirname } from "path";
 export async function fileExists(path) {
     try {
         await stat(path);
@@ -16,6 +17,10 @@ export async function readText(path) {
         return null;
     }
 }
+export async function writeText(path, contents) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, contents, "utf8");
+}
 export function toPosixPath(path) {
     return path.replace(/\\/g, "/");
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { buildPreviewBrief } from "./brief.js";
+export { buildDesignSystemArtifact, writeDesignSystemArtifact } from "./design-system.js";
 export { detectFramework } from "./framework.js";
 export { createServer, main } from "./server.js";
-export type { DeliverableSpec, FrameworkInfo, FrameworkKind, InspectionStep, PreviewBrief, ProjectFacts, RoutingStyle, } from "./types.js";
+export type { ComponentRecord, CssVariableRecord, DesignSystemArtifact, DesignSystemBuildInput, DeliverableSpec, FrameworkInfo, FrameworkKind, InspectionStep, PreviewBrief, ProjectFacts, RoutingStyle, } from "./types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { buildPreviewBrief } from "./brief.js";
+export { buildDesignSystemArtifact, writeDesignSystemArtifact } from "./design-system.js";
 export { detectFramework } from "./framework.js";
 export { createServer, main } from "./server.js";

package/dist/project.d.ts

@@ -0,0 +1,2 @@
+import type { FrameworkInfo, ProjectFacts } from "./types.js";
+export declare function buildProjectFacts(projectRoot: string, framework: FrameworkInfo): Promise<ProjectFacts>;

package/dist/project.js

@@ -0,0 +1,61 @@
+import { glob } from "glob";
+import { join } from "path";
+import { fileExists, toPosixPath } from "./files.js";
+export async function buildProjectFacts(projectRoot, framework) {
+    const componentDirs = await findExistingDirectories(projectRoot, [
+        "src/components",
+        "src/ui",
+        "src/features",
+        "components",
+        "ui",
+        "features",
+    ]);
+    const pageDirs = await findExistingDirectories(projectRoot, [
+        "src/app",
+        "app",
+        "src/pages",
+        "pages",
+        "src/routes",
+        "routes",
+    ]);
+    const styleFiles = await findStyleFiles(projectRoot);
+    const likelyUiDirs = Array.from(new Set([...componentDirs, ...pageDirs.filter((dir) => !dir.endsWith("/preview"))]));
+    return {
+        framework: framework.kind,
+        routingStyle: framework.routingStyle,
+        previewRoute: framework.previewRoute,
+        previewEntryFile: framework.previewEntryFile,
+        packageManager: framework.packageManager,
+        likelyComponentDirs: componentDirs,
+        likelyStyleFiles: styleFiles,
+        likelyPageDirs: pageDirs,
+        likelyUiDirs,
+    };
+}
+async function findExistingDirectories(projectRoot, candidates) {
+    const results = [];
+    for (const candidate of candidates) {
+        if (await fileExists(join(projectRoot, candidate))) {
+            results.push(candidate);
+        }
+    }
+    return results;
+}
+async function findStyleFiles(projectRoot) {
+    const files = await glob(["**/*.{css,scss,sass,less}"], {
+        cwd: projectRoot,
+        nodir: true,
+        ignore: [
+            "**/node_modules/**",
+            "**/.next/**",
+            "**/dist/**",
+            "**/build/**",
+            "**/.capy/**",
+            "**/coverage/**",
+        ],
+    });
+    return files
+        .map((file) => toPosixPath(file))
+        .filter((file) => !file.includes("/preview/"))
+        .sort();
+}

package/dist/server.js

@@ -3,10 +3,11 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { buildPreviewBrief } from "./brief.js";
+import { writeDesignSystemArtifact } from "./design-system.js";
 export function createServer(projectRoot = process.cwd()) {
     const server = new McpServer({
         name: "capy",
-        version: "0.2.0",
+        version: "1.0.2",
     });
     server.registerTool("get_preview_brief", {
         title: "Get Preview Brief",
@@ -117,6 +118,83 @@ export function createServer(projectRoot = process.cwd()) {
             structuredContent,
         };
     });
+    server.registerTool("get_design_system", {
+        title: "Get Design System",
+        description: "Builds and writes a stable machine-readable design-system artifact for the current repo. Use this when the agent needs a durable JSON source of truth for future UI work.",
+        inputSchema: {
+            artifactPath: z
+                .string()
+                .default(".capy/design-system.json")
+                .describe("Where to write the design-system JSON artifact relative to the repo root."),
+            mode: z
+                .enum(["build", "update"])
+                .default("build")
+                .describe("Whether this is the first artifact pass or an incremental refresh."),
+            changedFiles: z
+                .array(z.string())
+                .optional()
+                .describe("Files changed since the previous pass, when known."),
+            userGoal: z
+                .string()
+                .optional()
+                .describe("Optional end-user request to keep the artifact guidance aligned with the task."),
+        },
+        outputSchema: {
+            artifact_path: z.string(),
+            framework: z.enum([
+                "next-app-router",
+                "next-pages-router",
+                "react-router",
+                "react-no-router",
+                "unknown",
+            ]),
+            routing_style: z.enum([
+                "app-router",
+                "pages-router",
+                "react-router",
+                "none",
+                "unknown",
+            ]),
+            preview_route: z.string(),
+            preview_entry_file: z.string(),
+            component_count: z.number(),
+            css_variable_count: z.number(),
+            source_files: z.array(z.string()),
+            warnings: z.array(z.string()),
+            summary: z.string(),
+        },
+    }, async ({ artifactPath = ".capy/design-system.json", mode = "build", changedFiles, userGoal }) => {
+        const artifact = await writeDesignSystemArtifact(projectRoot, {
+            artifactPath,
+            mode,
+            changedFiles,
+            userGoal,
+        });
+        const structuredContent = {
+            artifact_path: artifact.meta.artifactPath,
+            framework: artifact.meta.framework,
+            routing_style: artifact.meta.routingStyle,
+            preview_route: artifact.meta.previewRoute,
+            preview_entry_file: artifact.meta.previewEntryFile,
+            component_count: artifact.components.length,
+            css_variable_count: artifact.tokens.cssVariables.length,
+            source_files: artifact.meta.sourceFiles,
+            warnings: artifact.guidance.warnings,
+            summary: artifact.guidance.summary,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        ...structuredContent,
+                        design_system: artifact,
+                    }, null, 2),
+                },
+            ],
+            structuredContent,
+        };
+    });
     return server;
 }
 export async function main() {

package/dist/types.d.ts

@@ -45,3 +45,58 @@ export interface PreviewBrief {
     warnings: string[];
     instructions: string;
 }
+export interface DesignSystemBuildInput {
+    artifactPath?: string;
+    changedFiles?: string[];
+    mode?: "build" | "update";
+    userGoal?: string;
+}
+export interface CssVariableRecord {
+    name: string;
+    value: string;
+    category: "color" | "typography" | "layout" | "other";
+    file: string;
+    line: number;
+}
+export interface ComponentRecord {
+    name: string;
+    path: string;
+    exports: string[];
+    kind: "primitive" | "component" | "feature" | "unknown";
+}
+export interface DesignSystemArtifact {
+    meta: {
+        generatedAt: string;
+        mode: "build" | "update";
+        artifactPath: string;
+        framework: FrameworkKind;
+        routingStyle: RoutingStyle;
+        previewRoute: string;
+        previewEntryFile: string;
+        packageManager: FrameworkInfo["packageManager"];
+        changedFiles: string[];
+        sourceFiles: string[];
+    };
+    directories: {
+        componentDirs: string[];
+        pageDirs: string[];
+        styleFiles: string[];
+        uiDirs: string[];
+    };
+    tokens: {
+        cssVariables: CssVariableRecord[];
+        styleFiles: string[];
+    };
+    components: ComponentRecord[];
+    preview: {
+        route: string;
+        entryFile: string;
+        sections: string[];
+        updateStrategy: string[];
+    };
+    guidance: {
+        summary: string;
+        warnings: string[];
+        instructions: string[];
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "capy-mcp",
-  "version": "1.0.1",
-  "description": "MCP server that inspects a repo and returns a structured /preview brief for AI coding agents",
+  "version": "1.0.2",
+  "description": "MCP server that inspects a repo, returns a structured /preview brief, and writes a design-system JSON artifact for AI coding agents",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",