capy-mcp 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anant Singhal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# capy-mcp
+
+`capy-mcp` is a stdio MCP server that inspects a React or Next.js repo and returns a structured brief for building or updating a local `/preview` route.
+
+It does not generate the preview page itself. It gives an AI coding agent the repo map, inspection order, constraints, warnings, and target preview file so the agent can implement `/preview` in the host app.
+
+## What it exposes
+
+The server currently registers two MCP tools:
+
+- `get_preview_brief`
+- `get_design_system`
+
+The tool accepts:
+
+- `task`: `"build_preview"` or `"update_preview"`
+- `changedFiles?`: a list of changed files to bias incremental updates
+- `userGoal?`: the end-user request so the brief stays aligned with the task
+
+The tool returns structured content with:
+
+- `project_facts`
+- `inspection_plan`
+- `constraints`
+- `deliverable_spec`
+- `update_strategy`
+- `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
+npm install capy-mcp
+```
+
+Run it directly:
+
+```bash
+npx capy-mcp
+```
+
+## MCP config
+
+Example stdio MCP config:
+
+```json
+{
+  "mcpServers": {
+    "capy": {
+      "command": "npx",
+      "args": ["-y", "capy-mcp"]
+    }
+  }
+}
+```
+
+## Library usage
+
+```ts
+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
+
+```bash
+npm install
+npm test
+npx capy-mcp
+```
+
+## Publish checklist
+
+```bash
+npm test
+npm publish
+```
+
+If `capy-mcp` is not owned by your npm account, rename the package before publishing.

package/dist/brief.d.ts

@@ -0,0 +1,6 @@
+import type { PreviewBrief } from "./types.js";
+export declare function buildPreviewBrief(projectRoot: string, input: {
+    task: "build_preview" | "update_preview";
+    changedFiles?: string[];
+    userGoal?: string;
+}): Promise<PreviewBrief>;

package/dist/brief.js

@@ -0,0 +1,129 @@
+import { detectFramework } from "./framework.js";
+import { buildProjectFacts } from "./project.js";
+const SECTION_ORDER = [
+    "Foundations",
+    "Colors",
+    "Typography",
+    "Spacing",
+    "Inputs",
+    "Actions",
+    "Navigation",
+    "Data Display",
+    "Feedback",
+    "Overlays",
+    "Feature or Page Sections",
+];
+export async function buildPreviewBrief(projectRoot, input) {
+    const framework = await detectFramework(projectRoot);
+    const projectFacts = await buildProjectFacts(projectRoot, framework);
+    const warnings = buildWarnings(framework, input.changedFiles);
+    return {
+        projectFacts,
+        inspectionPlan: buildInspectionPlan(projectFacts),
+        constraints: buildConstraints(framework),
+        deliverableSpec: {
+            goal: input.task === "update_preview"
+                ? "Update the existing /preview surface incrementally based on the files or areas that changed."
+                : "Create a local /preview route that helps humans and agents inspect the app's real UI system quickly.",
+            layout: "vertical-scroll",
+            allowHorizontalRows: true,
+            previewRoute: projectFacts.previewRoute,
+            previewEntryFile: projectFacts.previewEntryFile,
+            sections: SECTION_ORDER,
+            useExistingComponentsFirst: true,
+        },
+        updateStrategy: buildUpdateStrategy(input.changedFiles),
+        warnings,
+        instructions: buildInstructions(projectFacts, input),
+    };
+}
+function buildInspectionPlan(projectFacts) {
+    const appShellTargets = uniqueCompact([
+        firstMatching(projectFacts.likelyPageDirs, "src/app")
+            ? "src/app/layout.tsx"
+            : undefined,
+        firstMatching(projectFacts.likelyPageDirs, "src/app")
+            ? "src/app/page.tsx"
+            : undefined,
+        firstMatching(projectFacts.likelyPageDirs, "app") ? "app/layout.tsx" : undefined,
+        firstMatching(projectFacts.likelyPageDirs, "app") ? "app/page.tsx" : undefined,
+        firstMatching(projectFacts.likelyPageDirs, "src/pages") ? "src/pages/_app.tsx" : undefined,
+        firstMatching(projectFacts.likelyPageDirs, "pages") ? "pages/_app.tsx" : undefined,
+    ]);
+    return [
+        {
+            step: 1,
+            action: "Read the app shell and routing entry points first",
+            targets: appShellTargets.length > 0 ? appShellTargets : projectFacts.likelyPageDirs,
+            reason: "Understand the project structure, routing style, and baseline visual language.",
+        },
+        {
+            step: 2,
+            action: "Read global styles and theme sources",
+            targets: projectFacts.likelyStyleFiles.slice(0, 8),
+            reason: "Extract colors, spacing, typography, layout rules, and theme conventions from the real repo.",
+        },
+        {
+            step: 3,
+            action: "Inspect UI/component directories",
+            targets: projectFacts.likelyComponentDirs.length > 0 ? projectFacts.likelyComponentDirs : projectFacts.likelyUiDirs,
+            reason: "Find existing primitives, composites, and sections before inventing new preview-only UI.",
+        },
+        {
+            step: 4,
+            action: "Implement or update the preview route",
+            targets: [projectFacts.previewEntryFile],
+            reason: "Build a neat, scrollable /preview page that reflects the real app structure.",
+        },
+    ];
+}
+function buildConstraints(framework) {
+    const constraints = [
+        "Do not invent colors, spacing, typography, or component APIs before inspecting the repo files listed in inspection_plan.",
+        "Build a vertically scrollable preview page.",
+        "Use horizontal specimen rows only when they make scanning easier.",
+        "Prefer existing components over creating preview-only components.",
+        "Keep the page neat, easy to scan, and aligned with the app's current design language.",
+    ];
+    if (framework.needsConfirmation && framework.confirmationMessage) {
+        constraints.push(framework.confirmationMessage);
+    }
+    return constraints;
+}
+function buildUpdateStrategy(changedFiles) {
+    const strategies = [
+        "When updating, inspect changed files first and revise only affected preview sections where possible.",
+        "If a changed file affects shared foundations, then update every preview section that depends on those foundations.",
+        "Do not rebuild the entire preview page unless the current structure is no longer representative of the app.",
+    ];
+    if (changedFiles && changedFiles.length > 0) {
+        strategies.unshift(`Prioritize these changed files: ${changedFiles.join(", ")}`);
+    }
+    else {
+        strategies.unshift("If changed files are not provided, inspect git diff or the user's latest edits before deciding what to update.");
+    }
+    return strategies;
+}
+function buildWarnings(framework, changedFiles) {
+    const warnings = [];
+    if (framework.confirmationMessage) {
+        warnings.push(framework.confirmationMessage);
+    }
+    if (!changedFiles || changedFiles.length === 0) {
+        warnings.push("No changedFiles were provided. The agent should inspect git diff or recent edits when performing update_preview.");
+    }
+    return warnings;
+}
+function buildInstructions(projectFacts, input) {
+    const lead = input.task === "update_preview"
+        ? "Update the existing /preview route incrementally."
+        : "Create the /preview route from scratch.";
+    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.`;
+}
+function uniqueCompact(values) {
+    return Array.from(new Set(values.filter(Boolean)));
+}
+function firstMatching(values, needle) {
+    return values.find((value) => value === needle);
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { main } from "./server.js";
+main().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

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

@@ -0,0 +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

@@ -0,0 +1,26 @@
+import { mkdir, readFile, stat, writeFile } from "fs/promises";
+import { dirname } from "path";
+export async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readText(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        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/framework.d.ts

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

package/dist/framework.js

@@ -0,0 +1,115 @@
+import { join } from "path";
+import { fileExists, readText } from "./files.js";
+export async function detectFramework(projectRoot) {
+    const packageJson = await loadPackageJson(projectRoot);
+    const deps = {
+        ...packageJson?.dependencies,
+        ...packageJson?.devDependencies,
+    };
+    const hasNext = Boolean(deps.next);
+    const hasReact = Boolean(deps.react);
+    const hasReactRouter = Boolean(deps["react-router-dom"]);
+    const srcAppDir = join(projectRoot, "src/app");
+    const appDir = join(projectRoot, "app");
+    const srcPagesDir = join(projectRoot, "src/pages");
+    const pagesDir = join(projectRoot, "pages");
+    if (hasNext && (await fileExists(srcAppDir))) {
+        return {
+            kind: "next-app-router",
+            label: "Next.js App Router",
+            routingStyle: "app-router",
+            previewRoute: "/preview",
+            previewEntryFile: "src/app/preview/page.tsx",
+            packageManager: detectPackageManager(packageJson?.packageManager),
+            needsConfirmation: false,
+        };
+    }
+    if (hasNext && (await fileExists(appDir))) {
+        return {
+            kind: "next-app-router",
+            label: "Next.js App Router",
+            routingStyle: "app-router",
+            previewRoute: "/preview",
+            previewEntryFile: "app/preview/page.tsx",
+            packageManager: detectPackageManager(packageJson?.packageManager),
+            needsConfirmation: false,
+        };
+    }
+    if (hasNext && (await fileExists(srcPagesDir))) {
+        return {
+            kind: "next-pages-router",
+            label: "Next.js Pages Router",
+            routingStyle: "pages-router",
+            previewRoute: "/preview",
+            previewEntryFile: "src/pages/preview.tsx",
+            packageManager: detectPackageManager(packageJson?.packageManager),
+            needsConfirmation: false,
+        };
+    }
+    if (hasNext && (await fileExists(pagesDir))) {
+        return {
+            kind: "next-pages-router",
+            label: "Next.js Pages Router",
+            routingStyle: "pages-router",
+            previewRoute: "/preview",
+            previewEntryFile: "pages/preview.tsx",
+            packageManager: detectPackageManager(packageJson?.packageManager),
+            needsConfirmation: false,
+        };
+    }
+    if (hasReact && hasReactRouter) {
+        return {
+            kind: "react-router",
+            label: "React + React Router",
+            routingStyle: "react-router",
+            previewRoute: "/preview",
+            previewEntryFile: "src/routes/preview.tsx",
+            packageManager: detectPackageManager(packageJson?.packageManager),
+            needsConfirmation: false,
+        };
+    }
+    if (hasReact) {
+        return {
+            kind: "react-no-router",
+            label: "React without router",
+            routingStyle: "none",
+            previewRoute: "/preview",
+            previewEntryFile: "src/routes/preview.tsx",
+            packageManager: detectPackageManager(packageJson?.packageManager),
+            needsConfirmation: true,
+            confirmationMessage: "This repo looks like React without react-router-dom. The agent should confirm router setup before implementing /preview.",
+        };
+    }
+    return {
+        kind: "unknown",
+        label: "Unknown framework",
+        routingStyle: "unknown",
+        previewRoute: "/preview",
+        previewEntryFile: "preview-entry-file-unknown",
+        packageManager: detectPackageManager(packageJson?.packageManager),
+        needsConfirmation: true,
+        confirmationMessage: "Framework detection was inconclusive. The agent should inspect routing manually before building /preview.",
+    };
+}
+async function loadPackageJson(projectRoot) {
+    const raw = await readText(join(projectRoot, "package.json"));
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function detectPackageManager(packageManager) {
+    if (!packageManager)
+        return "npm";
+    if (packageManager.startsWith("pnpm"))
+        return "pnpm";
+    if (packageManager.startsWith("yarn"))
+        return "yarn";
+    if (packageManager.startsWith("bun"))
+        return "bun";
+    return "npm";
+}

package/dist/index.d.ts

@@ -0,0 +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 { ComponentRecord, CssVariableRecord, DesignSystemArtifact, DesignSystemBuildInput, DeliverableSpec, FrameworkInfo, FrameworkKind, InspectionStep, PreviewBrief, ProjectFacts, RoutingStyle, } from "./types.js";

package/dist/index.js

@@ -0,0 +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.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(projectRoot?: string): McpServer;
+export declare function main(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+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: "1.0.2",
+    });
+    server.registerTool("get_preview_brief", {
+        title: "Get Preview Brief",
+        description: "Call this first for any UI preview, design-system, component-catalog, or style-audit task. Returns the repo map, inspection plan, constraints, and exact /preview spec the agent should follow before writing code.",
+        inputSchema: {
+            task: z
+                .enum(["build_preview", "update_preview"])
+                .default("build_preview")
+                .describe("Whether the agent is creating /preview from scratch or updating it."),
+            changedFiles: z
+                .array(z.string())
+                .optional()
+                .describe("Files changed since the previous preview pass, when known."),
+            userGoal: z
+                .string()
+                .optional()
+                .describe("The user's request, so the returned instructions can stay aligned."),
+        },
+        outputSchema: {
+            project_facts: z.object({
+                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(),
+                package_manager: z.enum(["npm", "pnpm", "yarn", "bun"]),
+                likely_component_dirs: z.array(z.string()),
+                likely_style_files: z.array(z.string()),
+                likely_page_dirs: z.array(z.string()),
+                likely_ui_dirs: z.array(z.string()),
+            }),
+            inspection_plan: z.array(z.object({
+                step: z.number(),
+                action: z.string(),
+                targets: z.array(z.string()),
+                reason: z.string(),
+            })),
+            constraints: z.array(z.string()),
+            deliverable_spec: z.object({
+                goal: z.string(),
+                layout: z.literal("vertical-scroll"),
+                allow_horizontal_rows: z.boolean(),
+                preview_route: z.string(),
+                preview_entry_file: z.string(),
+                sections: z.array(z.string()),
+                use_existing_components_first: z.boolean(),
+            }),
+            update_strategy: z.array(z.string()),
+            warnings: z.array(z.string()),
+            instructions: z.string(),
+        },
+    }, async ({ task = "build_preview", changedFiles, userGoal }) => {
+        const brief = await buildPreviewBrief(projectRoot, {
+            task,
+            changedFiles,
+            userGoal,
+        });
+        const structuredContent = {
+            project_facts: {
+                framework: brief.projectFacts.framework,
+                routing_style: brief.projectFacts.routingStyle,
+                preview_route: brief.projectFacts.previewRoute,
+                preview_entry_file: brief.projectFacts.previewEntryFile,
+                package_manager: brief.projectFacts.packageManager,
+                likely_component_dirs: brief.projectFacts.likelyComponentDirs,
+                likely_style_files: brief.projectFacts.likelyStyleFiles,
+                likely_page_dirs: brief.projectFacts.likelyPageDirs,
+                likely_ui_dirs: brief.projectFacts.likelyUiDirs,
+            },
+            inspection_plan: brief.inspectionPlan.map((item) => ({
+                step: item.step,
+                action: item.action,
+                targets: item.targets,
+                reason: item.reason,
+            })),
+            constraints: brief.constraints,
+            deliverable_spec: {
+                goal: brief.deliverableSpec.goal,
+                layout: brief.deliverableSpec.layout,
+                allow_horizontal_rows: brief.deliverableSpec.allowHorizontalRows,
+                preview_route: brief.deliverableSpec.previewRoute,
+                preview_entry_file: brief.deliverableSpec.previewEntryFile,
+                sections: brief.deliverableSpec.sections,
+                use_existing_components_first: brief.deliverableSpec.useExistingComponentsFirst,
+            },
+            update_strategy: brief.updateStrategy,
+            warnings: brief.warnings,
+            instructions: brief.instructions,
+        };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(structuredContent, null, 2),
+                },
+            ],
+            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() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+export type FrameworkKind = "next-app-router" | "next-pages-router" | "react-router" | "react-no-router" | "unknown";
+export type RoutingStyle = "app-router" | "pages-router" | "react-router" | "none" | "unknown";
+export interface FrameworkInfo {
+    kind: FrameworkKind;
+    label: string;
+    routingStyle: RoutingStyle;
+    previewRoute: string;
+    previewEntryFile: string;
+    packageManager: "npm" | "pnpm" | "yarn" | "bun";
+    needsConfirmation: boolean;
+    confirmationMessage?: string;
+}
+export interface ProjectFacts {
+    framework: FrameworkKind;
+    routingStyle: RoutingStyle;
+    previewRoute: string;
+    previewEntryFile: string;
+    packageManager: FrameworkInfo["packageManager"];
+    likelyComponentDirs: string[];
+    likelyStyleFiles: string[];
+    likelyPageDirs: string[];
+    likelyUiDirs: string[];
+}
+export interface InspectionStep {
+    step: number;
+    action: string;
+    targets: string[];
+    reason: string;
+}
+export interface DeliverableSpec {
+    goal: string;
+    layout: "vertical-scroll";
+    allowHorizontalRows: boolean;
+    previewRoute: string;
+    previewEntryFile: string;
+    sections: string[];
+    useExistingComponentsFirst: boolean;
+}
+export interface PreviewBrief {
+    projectFacts: ProjectFacts;
+    inspectionPlan: InspectionStep[];
+    constraints: string[];
+    deliverableSpec: DeliverableSpec;
+    updateStrategy: string[];
+    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/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,11 +1,61 @@
 {
   "name": "capy-mcp",
-  "version": "1.0.0",
-  "description": "Capy MCP - Coming soon",
+  "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",
   "bin": {
-    "capy": "./bin/cli.js"
+    "capy-mcp": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
   },
   "engines": {
     "node": ">=18"
-  }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "nextjs",
+    "react",
+    "preview"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GithubAnant/capy.git",
+    "directory": "capy-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/GithubAnant/capy/issues"
+  },
+  "homepage": "https://github.com/GithubAnant/capy/tree/main/capy-mcp",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "glob": "^11.0.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "typescript": "^5.8.2"
+  },
+  "license": "MIT"
 }

package/bin/cli.js

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-console.log("capy-cli coming soon!");