@pandacss/mcp 1.11.4 → 1.12.0

package/README.md

@@ -0,0 +1,10 @@
+# @pandacss/mcp
+
+MCP server for Panda CSS AI assistants.
+
+```bash
+npx -y @pandacss/mcp
+npx -y @pandacss/mcp init --client cursor
+```
+
+MCP lives in this package on purpose so `@pandacss/dev` installs do not pull the MCP SDK (and Hono) into every project.

package/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { main } = require('./dist/cli.js')
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+})

package/dist/chunk-IBM3OGUU.mjs

@@ -0,0 +1,320 @@
+// src/clients.ts
+var MCP_CLIENTS = {
+  claude: {
+    name: "claude",
+    label: "Claude (.mcp.json)",
+    configPath: ".mcp.json",
+    configKey: "mcpServers"
+  },
+  cursor: {
+    name: "cursor",
+    label: "Cursor (.cursor/mcp.json)",
+    configPath: ".cursor/mcp.json",
+    configKey: "mcpServers"
+  },
+  vscode: {
+    name: "vscode",
+    label: "VS Code (.vscode/mcp.json)",
+    configPath: ".vscode/mcp.json",
+    configKey: "servers"
+  },
+  windsurf: {
+    name: "windsurf",
+    label: "Windsurf (.windsurf/mcp.json)",
+    configPath: ".windsurf/mcp.json",
+    configKey: "mcpServers"
+  },
+  codex: {
+    name: "codex",
+    label: "Codex (.codex/mcp.json)",
+    configPath: ".codex/mcp.json",
+    configKey: "mcpServers"
+  }
+};
+var CLIENT_NAMES = Object.keys(MCP_CLIENTS);
+function isValidClient(client) {
+  return CLIENT_NAMES.includes(client);
+}
+function getClientConfig(client) {
+  return MCP_CLIENTS[client];
+}
+function generateMcpConfig(clientConfig) {
+  const serverConfig = {
+    command: "npx",
+    args: ["-y", "@pandacss/mcp"]
+  };
+  return {
+    [clientConfig.configKey]: {
+      panda: serverConfig
+    }
+  };
+}
+
+// src/init.ts
+import * as p from "@clack/prompts";
+import { logger } from "@pandacss/logger";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+async function initMcpConfig(options = {}) {
+  const { cwd = process.cwd() } = options;
+  let { clients } = options;
+  p.intro("Panda MCP Setup");
+  if (!clients || clients.length === 0) {
+    const selected = await p.multiselect({
+      message: "Select AI clients to configure:",
+      options: CLIENT_NAMES.map((client) => ({
+        value: client,
+        label: MCP_CLIENTS[client].label
+      })),
+      required: true
+    });
+    if (p.isCancel(selected)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    clients = selected;
+  }
+  const validClients = clients.filter((client) => {
+    if (!isValidClient(client)) {
+      logger.warn("mcp:init", `Unknown client: ${client}`);
+      return false;
+    }
+    return true;
+  });
+  if (validClients.length === 0) {
+    p.cancel("No valid clients selected.");
+    process.exit(1);
+  }
+  const results = [];
+  for (const client of validClients) {
+    const clientConfig = getClientConfig(client);
+    const configPath = resolve(cwd, clientConfig.configPath);
+    const configDir = dirname(configPath);
+    if (!existsSync(configDir)) {
+      mkdirSync(configDir, { recursive: true });
+    }
+    const newConfig = generateMcpConfig(clientConfig);
+    let finalConfig = newConfig;
+    if (existsSync(configPath)) {
+      try {
+        const existingContent = readFileSync(configPath, "utf-8");
+        const existingConfig = JSON.parse(existingContent);
+        finalConfig = {
+          ...existingConfig,
+          [clientConfig.configKey]: {
+            ...existingConfig[clientConfig.configKey],
+            ...newConfig[clientConfig.configKey]
+          }
+        };
+      } catch {
+      }
+    }
+    writeFileSync(configPath, JSON.stringify(finalConfig, null, 2));
+    results.push({
+      client,
+      path: clientConfig.configPath,
+      created: true
+    });
+  }
+  p.note(results.map((r) => `${r.client}: ${r.path}`).join("\n"), "Created MCP configurations");
+  p.outro("MCP setup complete! Your AI assistants can now use Panda CSS tools.");
+  return results;
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { logger as logger2 } from "@pandacss/logger";
+import { analyze, loadConfigAndCreateContext } from "@pandacss/node";
+import { TOKEN_CATEGORIES } from "@pandacss/token-dictionary";
+import { resolve as resolve2 } from "path";
+import * as z from "zod/v4";
+var tokenCategorySchema = z.enum(TOKEN_CATEGORIES).optional().describe("Filter by token category");
+var json = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(data) }]
+});
+function createMcpServer(options) {
+  const { ctx } = options;
+  const server = new McpServer({
+    name: "@pandacss/mcp",
+    version: "1.0.0"
+  });
+  const recipeNames = ctx.recipes.keys;
+  const patternNames = ctx.patterns.keys;
+  const recipeNameSchema = recipeNames.length ? z.enum(recipeNames).optional().describe("Filter by recipe name") : z.string().optional().describe("Filter by recipe name");
+  const patternNameSchema = patternNames.length ? z.enum(patternNames).optional().describe("Filter by pattern name") : z.string().optional().describe("Filter by pattern name");
+  server.registerTool(
+    "get_tokens",
+    {
+      description: "Get all design tokens with their values, CSS variables, and usage examples",
+      inputSchema: { category: tokenCategorySchema }
+    },
+    async ({ category }) => {
+      const spec = ctx.getSpecOfType("tokens");
+      const data = category ? spec.data.filter((group) => group.type === category) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_semantic_tokens",
+    {
+      description: "Get semantic tokens with their conditional values (responsive, color modes)",
+      inputSchema: { category: tokenCategorySchema }
+    },
+    async ({ category }) => {
+      const spec = ctx.getSpecOfType("semantic-tokens");
+      const data = category ? spec.data.filter((group) => group.type === category) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_recipes",
+    {
+      description: "Get component recipes with their variants, default values, and usage examples",
+      inputSchema: { name: recipeNameSchema }
+    },
+    async ({ name }) => {
+      const spec = ctx.getSpecOfType("recipes");
+      const data = name ? spec.data.filter((item) => item.name === name) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_patterns",
+    {
+      description: "Get layout patterns with their properties and usage examples",
+      inputSchema: { name: patternNameSchema }
+    },
+    async ({ name }) => {
+      const spec = ctx.getSpecOfType("patterns");
+      const data = name ? spec.data.filter((item) => item.name === name) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_conditions",
+    { description: "Get all conditions (breakpoints, pseudo-classes, color modes) and their CSS values" },
+    async () => json(ctx.getSpecOfType("conditions"))
+  );
+  server.registerTool(
+    "get_keyframes",
+    { description: "Get keyframe animations defined in the theme" },
+    async () => json(ctx.getSpecOfType("keyframes"))
+  );
+  server.registerTool(
+    "get_text_styles",
+    { description: "Get text style compositions for typography" },
+    async () => json(ctx.getSpecOfType("text-styles"))
+  );
+  server.registerTool(
+    "get_layer_styles",
+    { description: "Get layer style compositions for visual styling" },
+    async () => json(ctx.getSpecOfType("layer-styles"))
+  );
+  server.registerTool(
+    "get_animation_styles",
+    { description: "Get animation style compositions" },
+    async () => json(ctx.getSpecOfType("animation-styles"))
+  );
+  server.registerTool(
+    "get_color_palette",
+    { description: "Get the color palette with all color values" },
+    async () => json(ctx.getSpecOfType("color-palette"))
+  );
+  server.registerTool(
+    "get_config",
+    { description: "Get the resolved Panda CSS configuration including paths, JSX settings, and output options" },
+    async () => json(ctx.config)
+  );
+  server.registerTool(
+    "get_usage_report",
+    {
+      description: "Get a usage report of design tokens and recipes across the codebase. Shows which tokens/recipes are used, unused, or missing. Useful for auditing, cleanup, and identifying dead code.",
+      inputSchema: {
+        scope: z.enum(["all", "token", "recipe"]).optional().describe("Analysis scope: token, recipe, or all (default)")
+      }
+    },
+    async ({ scope }) => {
+      const result = analyze(ctx);
+      const includeTokens = !scope || scope === "all" || scope === "token";
+      const includeRecipes = !scope || scope === "all" || scope === "recipe";
+      const report = {};
+      if (includeTokens && !ctx.tokens.isEmpty) {
+        const tokenReport = result.getTokenReport();
+        report.tokens = tokenReport.report.getSummary();
+      }
+      if (includeRecipes && !ctx.recipes.isEmpty()) {
+        const recipeReport = result.getRecipeReport();
+        report.recipes = recipeReport.report;
+      }
+      return json(report);
+    }
+  );
+  return server;
+}
+async function startMcpServer(options = {}) {
+  const { cwd = process.cwd(), config: configPath, silent = false, transport } = options;
+  if (silent) {
+    logger2.level = "silent";
+  }
+  const resolvedCwd = resolve2(cwd);
+  const resolvedConfigPath = configPath ? resolve2(configPath) : void 0;
+  const ctx = await loadConfigAndCreateContext({
+    cwd: resolvedCwd,
+    configPath: resolvedConfigPath
+  });
+  const server = createMcpServer({ ctx });
+  const serverTransport = transport ?? new StdioServerTransport();
+  await server.connect(serverTransport);
+  if (!transport) {
+    watchProcessLifecycle(server);
+  }
+  console.error("Panda CSS MCP server started");
+  console.error(`Working directory: ${resolvedCwd}`);
+  if (resolvedConfigPath) {
+    console.error(`Config path: ${resolvedConfigPath}`);
+  }
+  return server;
+}
+function watchProcessLifecycle(server, options = {}) {
+  const proc = options.process ?? process;
+  const exit = options.exit ?? ((code) => process.exit(code));
+  let exiting = false;
+  const shutdown = (code) => {
+    if (exiting) return;
+    exiting = true;
+    void Promise.resolve(server.close()).catch(() => void 0);
+    exit(code);
+  };
+  proc.stdin.on("end", () => shutdown(0));
+  proc.stdin.on("close", () => shutdown(0));
+  proc.on("SIGINT", () => shutdown(0));
+  proc.on("SIGTERM", () => shutdown(0));
+  for (const stream of [proc.stdout, proc.stderr]) {
+    stream.on("error", (err) => {
+      if (err?.code === "EPIPE") shutdown(0);
+    });
+  }
+  const onFatal = (label) => (err) => {
+    try {
+      proc.stderr.write(`[panda mcp] ${label}, exiting: ${formatError(err)}
+`);
+    } catch {
+    }
+    shutdown(1);
+  };
+  proc.on("uncaughtException", onFatal("uncaught exception"));
+  proc.on("unhandledRejection", onFatal("unhandled rejection"));
+  return shutdown;
+}
+function formatError(err) {
+  return err instanceof Error ? err.stack ?? err.message : String(err);
+}
+
+export {
+  MCP_CLIENTS,
+  generateMcpConfig,
+  initMcpConfig,
+  createMcpServer,
+  startMcpServer
+};

package/dist/cli.js

@@ -0,0 +1,390 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  main: () => main
+});
+module.exports = __toCommonJS(cli_exports);
+var import_cac = require("cac");
+var import_path3 = require("path");
+
+// package.json
+var version = "1.12.0";
+
+// src/init.ts
+var p = __toESM(require("@clack/prompts"));
+var import_logger = require("@pandacss/logger");
+var import_fs = require("fs");
+var import_path = require("path");
+
+// src/clients.ts
+var MCP_CLIENTS = {
+  claude: {
+    name: "claude",
+    label: "Claude (.mcp.json)",
+    configPath: ".mcp.json",
+    configKey: "mcpServers"
+  },
+  cursor: {
+    name: "cursor",
+    label: "Cursor (.cursor/mcp.json)",
+    configPath: ".cursor/mcp.json",
+    configKey: "mcpServers"
+  },
+  vscode: {
+    name: "vscode",
+    label: "VS Code (.vscode/mcp.json)",
+    configPath: ".vscode/mcp.json",
+    configKey: "servers"
+  },
+  windsurf: {
+    name: "windsurf",
+    label: "Windsurf (.windsurf/mcp.json)",
+    configPath: ".windsurf/mcp.json",
+    configKey: "mcpServers"
+  },
+  codex: {
+    name: "codex",
+    label: "Codex (.codex/mcp.json)",
+    configPath: ".codex/mcp.json",
+    configKey: "mcpServers"
+  }
+};
+var CLIENT_NAMES = Object.keys(MCP_CLIENTS);
+function isValidClient(client) {
+  return CLIENT_NAMES.includes(client);
+}
+function getClientConfig(client) {
+  return MCP_CLIENTS[client];
+}
+function generateMcpConfig(clientConfig) {
+  const serverConfig = {
+    command: "npx",
+    args: ["-y", "@pandacss/mcp"]
+  };
+  return {
+    [clientConfig.configKey]: {
+      panda: serverConfig
+    }
+  };
+}
+
+// src/init.ts
+async function initMcpConfig(options = {}) {
+  const { cwd = process.cwd() } = options;
+  let { clients } = options;
+  p.intro("Panda MCP Setup");
+  if (!clients || clients.length === 0) {
+    const selected = await p.multiselect({
+      message: "Select AI clients to configure:",
+      options: CLIENT_NAMES.map((client) => ({
+        value: client,
+        label: MCP_CLIENTS[client].label
+      })),
+      required: true
+    });
+    if (p.isCancel(selected)) {
+      p.cancel("Setup cancelled.");
+      process.exit(0);
+    }
+    clients = selected;
+  }
+  const validClients = clients.filter((client) => {
+    if (!isValidClient(client)) {
+      import_logger.logger.warn("mcp:init", `Unknown client: ${client}`);
+      return false;
+    }
+    return true;
+  });
+  if (validClients.length === 0) {
+    p.cancel("No valid clients selected.");
+    process.exit(1);
+  }
+  const results = [];
+  for (const client of validClients) {
+    const clientConfig = getClientConfig(client);
+    const configPath = (0, import_path.resolve)(cwd, clientConfig.configPath);
+    const configDir = (0, import_path.dirname)(configPath);
+    if (!(0, import_fs.existsSync)(configDir)) {
+      (0, import_fs.mkdirSync)(configDir, { recursive: true });
+    }
+    const newConfig = generateMcpConfig(clientConfig);
+    let finalConfig = newConfig;
+    if ((0, import_fs.existsSync)(configPath)) {
+      try {
+        const existingContent = (0, import_fs.readFileSync)(configPath, "utf-8");
+        const existingConfig = JSON.parse(existingContent);
+        finalConfig = {
+          ...existingConfig,
+          [clientConfig.configKey]: {
+            ...existingConfig[clientConfig.configKey],
+            ...newConfig[clientConfig.configKey]
+          }
+        };
+      } catch {
+      }
+    }
+    (0, import_fs.writeFileSync)(configPath, JSON.stringify(finalConfig, null, 2));
+    results.push({
+      client,
+      path: clientConfig.configPath,
+      created: true
+    });
+  }
+  p.note(results.map((r) => `${r.client}: ${r.path}`).join("\n"), "Created MCP configurations");
+  p.outro("MCP setup complete! Your AI assistants can now use Panda CSS tools.");
+  return results;
+}
+
+// src/server.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_logger2 = require("@pandacss/logger");
+var import_node = require("@pandacss/node");
+var import_token_dictionary = require("@pandacss/token-dictionary");
+var import_path2 = require("path");
+var z = __toESM(require("zod/v4"));
+var tokenCategorySchema = z.enum(import_token_dictionary.TOKEN_CATEGORIES).optional().describe("Filter by token category");
+var json = (data) => ({
+  content: [{ type: "text", text: JSON.stringify(data) }]
+});
+function createMcpServer(options) {
+  const { ctx } = options;
+  const server = new import_mcp.McpServer({
+    name: "@pandacss/mcp",
+    version: "1.0.0"
+  });
+  const recipeNames = ctx.recipes.keys;
+  const patternNames = ctx.patterns.keys;
+  const recipeNameSchema = recipeNames.length ? z.enum(recipeNames).optional().describe("Filter by recipe name") : z.string().optional().describe("Filter by recipe name");
+  const patternNameSchema = patternNames.length ? z.enum(patternNames).optional().describe("Filter by pattern name") : z.string().optional().describe("Filter by pattern name");
+  server.registerTool(
+    "get_tokens",
+    {
+      description: "Get all design tokens with their values, CSS variables, and usage examples",
+      inputSchema: { category: tokenCategorySchema }
+    },
+    async ({ category }) => {
+      const spec = ctx.getSpecOfType("tokens");
+      const data = category ? spec.data.filter((group) => group.type === category) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_semantic_tokens",
+    {
+      description: "Get semantic tokens with their conditional values (responsive, color modes)",
+      inputSchema: { category: tokenCategorySchema }
+    },
+    async ({ category }) => {
+      const spec = ctx.getSpecOfType("semantic-tokens");
+      const data = category ? spec.data.filter((group) => group.type === category) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_recipes",
+    {
+      description: "Get component recipes with their variants, default values, and usage examples",
+      inputSchema: { name: recipeNameSchema }
+    },
+    async ({ name }) => {
+      const spec = ctx.getSpecOfType("recipes");
+      const data = name ? spec.data.filter((item) => item.name === name) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_patterns",
+    {
+      description: "Get layout patterns with their properties and usage examples",
+      inputSchema: { name: patternNameSchema }
+    },
+    async ({ name }) => {
+      const spec = ctx.getSpecOfType("patterns");
+      const data = name ? spec.data.filter((item) => item.name === name) : spec.data;
+      return json({ type: spec.type, data });
+    }
+  );
+  server.registerTool(
+    "get_conditions",
+    { description: "Get all conditions (breakpoints, pseudo-classes, color modes) and their CSS values" },
+    async () => json(ctx.getSpecOfType("conditions"))
+  );
+  server.registerTool(
+    "get_keyframes",
+    { description: "Get keyframe animations defined in the theme" },
+    async () => json(ctx.getSpecOfType("keyframes"))
+  );
+  server.registerTool(
+    "get_text_styles",
+    { description: "Get text style compositions for typography" },
+    async () => json(ctx.getSpecOfType("text-styles"))
+  );
+  server.registerTool(
+    "get_layer_styles",
+    { description: "Get layer style compositions for visual styling" },
+    async () => json(ctx.getSpecOfType("layer-styles"))
+  );
+  server.registerTool(
+    "get_animation_styles",
+    { description: "Get animation style compositions" },
+    async () => json(ctx.getSpecOfType("animation-styles"))
+  );
+  server.registerTool(
+    "get_color_palette",
+    { description: "Get the color palette with all color values" },
+    async () => json(ctx.getSpecOfType("color-palette"))
+  );
+  server.registerTool(
+    "get_config",
+    { description: "Get the resolved Panda CSS configuration including paths, JSX settings, and output options" },
+    async () => json(ctx.config)
+  );
+  server.registerTool(
+    "get_usage_report",
+    {
+      description: "Get a usage report of design tokens and recipes across the codebase. Shows which tokens/recipes are used, unused, or missing. Useful for auditing, cleanup, and identifying dead code.",
+      inputSchema: {
+        scope: z.enum(["all", "token", "recipe"]).optional().describe("Analysis scope: token, recipe, or all (default)")
+      }
+    },
+    async ({ scope }) => {
+      const result = (0, import_node.analyze)(ctx);
+      const includeTokens = !scope || scope === "all" || scope === "token";
+      const includeRecipes = !scope || scope === "all" || scope === "recipe";
+      const report = {};
+      if (includeTokens && !ctx.tokens.isEmpty) {
+        const tokenReport = result.getTokenReport();
+        report.tokens = tokenReport.report.getSummary();
+      }
+      if (includeRecipes && !ctx.recipes.isEmpty()) {
+        const recipeReport = result.getRecipeReport();
+        report.recipes = recipeReport.report;
+      }
+      return json(report);
+    }
+  );
+  return server;
+}
+async function startMcpServer(options = {}) {
+  const { cwd = process.cwd(), config: configPath, silent = false, transport } = options;
+  if (silent) {
+    import_logger2.logger.level = "silent";
+  }
+  const resolvedCwd = (0, import_path2.resolve)(cwd);
+  const resolvedConfigPath = configPath ? (0, import_path2.resolve)(configPath) : void 0;
+  const ctx = await (0, import_node.loadConfigAndCreateContext)({
+    cwd: resolvedCwd,
+    configPath: resolvedConfigPath
+  });
+  const server = createMcpServer({ ctx });
+  const serverTransport = transport ?? new import_stdio.StdioServerTransport();
+  await server.connect(serverTransport);
+  if (!transport) {
+    watchProcessLifecycle(server);
+  }
+  console.error("Panda CSS MCP server started");
+  console.error(`Working directory: ${resolvedCwd}`);
+  if (resolvedConfigPath) {
+    console.error(`Config path: ${resolvedConfigPath}`);
+  }
+  return server;
+}
+function watchProcessLifecycle(server, options = {}) {
+  const proc = options.process ?? process;
+  const exit = options.exit ?? ((code) => process.exit(code));
+  let exiting = false;
+  const shutdown = (code) => {
+    if (exiting) return;
+    exiting = true;
+    void Promise.resolve(server.close()).catch(() => void 0);
+    exit(code);
+  };
+  proc.stdin.on("end", () => shutdown(0));
+  proc.stdin.on("close", () => shutdown(0));
+  proc.on("SIGINT", () => shutdown(0));
+  proc.on("SIGTERM", () => shutdown(0));
+  for (const stream of [proc.stdout, proc.stderr]) {
+    stream.on("error", (err) => {
+      if (err?.code === "EPIPE") shutdown(0);
+    });
+  }
+  const onFatal = (label) => (err) => {
+    try {
+      proc.stderr.write(`[panda mcp] ${label}, exiting: ${formatError(err)}
+`);
+    } catch {
+    }
+    shutdown(1);
+  };
+  proc.on("uncaughtException", onFatal("uncaught exception"));
+  proc.on("unhandledRejection", onFatal("unhandled rejection"));
+  return shutdown;
+}
+function formatError(err) {
+  return err instanceof Error ? err.stack ?? err.message : String(err);
+}
+
+// src/cli.ts
+function parseClients(value) {
+  if (!value) return void 0;
+  const values = Array.isArray(value) ? value : [value];
+  return values.flatMap((client) => client.split(",")).map((client) => client.trim()).filter(Boolean);
+}
+async function main(argv = process.argv.slice(2)) {
+  const cli = (0, import_cac.cac)("panda-mcp");
+  const cwd = process.cwd();
+  cli.command("[command]", "Start MCP server for AI assistants").option("-c, --config <path>", "Path to panda config file").option("--cwd <cwd>", "Current working directory", { default: cwd }).option("--silent", "Suppress startup logs").action(async (command, flags) => {
+    if (command) {
+      throw new Error(`Unknown command: ${command}`);
+    }
+    await startMcpServer({
+      cwd: (0, import_path3.resolve)(flags.cwd ?? cwd),
+      config: flags.config,
+      silent: flags.silent
+    });
+  });
+  cli.command("init", "Initialize MCP configuration for AI clients").option("--cwd <cwd>", "Current working directory", { default: cwd }).option("--client <clients>", "AI clients to configure (claude, cursor, vscode, windsurf, codex)").action(async (flags) => {
+    await initMcpConfig({
+      cwd: (0, import_path3.resolve)(flags.cwd ?? cwd),
+      clients: parseClients(flags.client)
+    });
+  });
+  cli.help();
+  cli.version(version);
+  cli.parse(["node", "panda-mcp", ...argv], { run: false });
+  await cli.runMatchedCommand();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  main
+});

package/dist/cli.mjs

@@ -0,0 +1,45 @@
+import {
+  initMcpConfig,
+  startMcpServer
+} from "./chunk-IBM3OGUU.mjs";
+
+// src/cli.ts
+import { cac } from "cac";
+import { resolve } from "path";
+
+// package.json
+var version = "1.12.0";
+
+// src/cli.ts
+function parseClients(value) {
+  if (!value) return void 0;
+  const values = Array.isArray(value) ? value : [value];
+  return values.flatMap((client) => client.split(",")).map((client) => client.trim()).filter(Boolean);
+}
+async function main(argv = process.argv.slice(2)) {
+  const cli = cac("panda-mcp");
+  const cwd = process.cwd();
+  cli.command("[command]", "Start MCP server for AI assistants").option("-c, --config <path>", "Path to panda config file").option("--cwd <cwd>", "Current working directory", { default: cwd }).option("--silent", "Suppress startup logs").action(async (command, flags) => {
+    if (command) {
+      throw new Error(`Unknown command: ${command}`);
+    }
+    await startMcpServer({
+      cwd: resolve(flags.cwd ?? cwd),
+      config: flags.config,
+      silent: flags.silent
+    });
+  });
+  cli.command("init", "Initialize MCP configuration for AI clients").option("--cwd <cwd>", "Current working directory", { default: cwd }).option("--client <clients>", "AI clients to configure (claude, cursor, vscode, windsurf, codex)").action(async (flags) => {
+    await initMcpConfig({
+      cwd: resolve(flags.cwd ?? cwd),
+      clients: parseClients(flags.client)
+    });
+  });
+  cli.help();
+  cli.version(version);
+  cli.parse(["node", "panda-mcp", ...argv], { run: false });
+  await cli.runMatchedCommand();
+}
+export {
+  main
+};

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   MCP_CLIENTS: () => MCP_CLIENTS,
   createMcpServer: () => createMcpServer,
+  generateMcpConfig: () => generateMcpConfig,
   initMcpConfig: () => initMcpConfig,
   startMcpServer: () => startMcpServer
 });
@@ -276,7 +277,7 @@ function getClientConfig(client) {
 function generateMcpConfig(clientConfig) {
   const serverConfig = {
     command: "npx",
-    args: ["panda", "mcp"]
+    args: ["-y", "@pandacss/mcp"]
   };
   return {
     [clientConfig.configKey]: {
@@ -355,6 +356,7 @@ async function initMcpConfig(options = {}) {
 0 && (module.exports = {
   MCP_CLIENTS,
   createMcpServer,
+  generateMcpConfig,
   initMcpConfig,
   startMcpServer
 });

package/dist/index.mjs

@@ -1,320 +1,14 @@
-// src/server.ts
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { logger } from "@pandacss/logger";
-import { analyze, loadConfigAndCreateContext } from "@pandacss/node";
-import { TOKEN_CATEGORIES } from "@pandacss/token-dictionary";
-import { resolve } from "path";
-import * as z from "zod/v4";
-var tokenCategorySchema = z.enum(TOKEN_CATEGORIES).optional().describe("Filter by token category");
-var json = (data) => ({
-  content: [{ type: "text", text: JSON.stringify(data) }]
-});
-function createMcpServer(options) {
-  const { ctx } = options;
-  const server = new McpServer({
-    name: "@pandacss/mcp",
-    version: "1.0.0"
-  });
-  const recipeNames = ctx.recipes.keys;
-  const patternNames = ctx.patterns.keys;
-  const recipeNameSchema = recipeNames.length ? z.enum(recipeNames).optional().describe("Filter by recipe name") : z.string().optional().describe("Filter by recipe name");
-  const patternNameSchema = patternNames.length ? z.enum(patternNames).optional().describe("Filter by pattern name") : z.string().optional().describe("Filter by pattern name");
-  server.registerTool(
-    "get_tokens",
-    {
-      description: "Get all design tokens with their values, CSS variables, and usage examples",
-      inputSchema: { category: tokenCategorySchema }
-    },
-    async ({ category }) => {
-      const spec = ctx.getSpecOfType("tokens");
-      const data = category ? spec.data.filter((group) => group.type === category) : spec.data;
-      return json({ type: spec.type, data });
-    }
-  );
-  server.registerTool(
-    "get_semantic_tokens",
-    {
-      description: "Get semantic tokens with their conditional values (responsive, color modes)",
-      inputSchema: { category: tokenCategorySchema }
-    },
-    async ({ category }) => {
-      const spec = ctx.getSpecOfType("semantic-tokens");
-      const data = category ? spec.data.filter((group) => group.type === category) : spec.data;
-      return json({ type: spec.type, data });
-    }
-  );
-  server.registerTool(
-    "get_recipes",
-    {
-      description: "Get component recipes with their variants, default values, and usage examples",
-      inputSchema: { name: recipeNameSchema }
-    },
-    async ({ name }) => {
-      const spec = ctx.getSpecOfType("recipes");
-      const data = name ? spec.data.filter((item) => item.name === name) : spec.data;
-      return json({ type: spec.type, data });
-    }
-  );
-  server.registerTool(
-    "get_patterns",
-    {
-      description: "Get layout patterns with their properties and usage examples",
-      inputSchema: { name: patternNameSchema }
-    },
-    async ({ name }) => {
-      const spec = ctx.getSpecOfType("patterns");
-      const data = name ? spec.data.filter((item) => item.name === name) : spec.data;
-      return json({ type: spec.type, data });
-    }
-  );
-  server.registerTool(
-    "get_conditions",
-    { description: "Get all conditions (breakpoints, pseudo-classes, color modes) and their CSS values" },
-    async () => json(ctx.getSpecOfType("conditions"))
-  );
-  server.registerTool(
-    "get_keyframes",
-    { description: "Get keyframe animations defined in the theme" },
-    async () => json(ctx.getSpecOfType("keyframes"))
-  );
-  server.registerTool(
-    "get_text_styles",
-    { description: "Get text style compositions for typography" },
-    async () => json(ctx.getSpecOfType("text-styles"))
-  );
-  server.registerTool(
-    "get_layer_styles",
-    { description: "Get layer style compositions for visual styling" },
-    async () => json(ctx.getSpecOfType("layer-styles"))
-  );
-  server.registerTool(
-    "get_animation_styles",
-    { description: "Get animation style compositions" },
-    async () => json(ctx.getSpecOfType("animation-styles"))
-  );
-  server.registerTool(
-    "get_color_palette",
-    { description: "Get the color palette with all color values" },
-    async () => json(ctx.getSpecOfType("color-palette"))
-  );
-  server.registerTool(
-    "get_config",
-    { description: "Get the resolved Panda CSS configuration including paths, JSX settings, and output options" },
-    async () => json(ctx.config)
-  );
-  server.registerTool(
-    "get_usage_report",
-    {
-      description: "Get a usage report of design tokens and recipes across the codebase. Shows which tokens/recipes are used, unused, or missing. Useful for auditing, cleanup, and identifying dead code.",
-      inputSchema: {
-        scope: z.enum(["all", "token", "recipe"]).optional().describe("Analysis scope: token, recipe, or all (default)")
-      }
-    },
-    async ({ scope }) => {
-      const result = analyze(ctx);
-      const includeTokens = !scope || scope === "all" || scope === "token";
-      const includeRecipes = !scope || scope === "all" || scope === "recipe";
-      const report = {};
-      if (includeTokens && !ctx.tokens.isEmpty) {
-        const tokenReport = result.getTokenReport();
-        report.tokens = tokenReport.report.getSummary();
-      }
-      if (includeRecipes && !ctx.recipes.isEmpty()) {
-        const recipeReport = result.getRecipeReport();
-        report.recipes = recipeReport.report;
-      }
-      return json(report);
-    }
-  );
-  return server;
-}
-async function startMcpServer(options = {}) {
-  const { cwd = process.cwd(), config: configPath, silent = false, transport } = options;
-  if (silent) {
-    logger.level = "silent";
-  }
-  const resolvedCwd = resolve(cwd);
-  const resolvedConfigPath = configPath ? resolve(configPath) : void 0;
-  const ctx = await loadConfigAndCreateContext({
-    cwd: resolvedCwd,
-    configPath: resolvedConfigPath
-  });
-  const server = createMcpServer({ ctx });
-  const serverTransport = transport ?? new StdioServerTransport();
-  await server.connect(serverTransport);
-  if (!transport) {
-    watchProcessLifecycle(server);
-  }
-  console.error("Panda CSS MCP server started");
-  console.error(`Working directory: ${resolvedCwd}`);
-  if (resolvedConfigPath) {
-    console.error(`Config path: ${resolvedConfigPath}`);
-  }
-  return server;
-}
-function watchProcessLifecycle(server, options = {}) {
-  const proc = options.process ?? process;
-  const exit = options.exit ?? ((code) => process.exit(code));
-  let exiting = false;
-  const shutdown = (code) => {
-    if (exiting) return;
-    exiting = true;
-    void Promise.resolve(server.close()).catch(() => void 0);
-    exit(code);
-  };
-  proc.stdin.on("end", () => shutdown(0));
-  proc.stdin.on("close", () => shutdown(0));
-  proc.on("SIGINT", () => shutdown(0));
-  proc.on("SIGTERM", () => shutdown(0));
-  for (const stream of [proc.stdout, proc.stderr]) {
-    stream.on("error", (err) => {
-      if (err?.code === "EPIPE") shutdown(0);
-    });
-  }
-  const onFatal = (label) => (err) => {
-    try {
-      proc.stderr.write(`[panda mcp] ${label}, exiting: ${formatError(err)}
-`);
-    } catch {
-    }
-    shutdown(1);
-  };
-  proc.on("uncaughtException", onFatal("uncaught exception"));
-  proc.on("unhandledRejection", onFatal("unhandled rejection"));
-  return shutdown;
-}
-function formatError(err) {
-  return err instanceof Error ? err.stack ?? err.message : String(err);
-}
-
-// src/init.ts
-import * as p from "@clack/prompts";
-import { logger as logger2 } from "@pandacss/logger";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { dirname, resolve as resolve2 } from "path";
-
-// src/clients.ts
-var MCP_CLIENTS = {
-  claude: {
-    name: "claude",
-    label: "Claude (.mcp.json)",
-    configPath: ".mcp.json",
-    configKey: "mcpServers"
-  },
-  cursor: {
-    name: "cursor",
-    label: "Cursor (.cursor/mcp.json)",
-    configPath: ".cursor/mcp.json",
-    configKey: "mcpServers"
-  },
-  vscode: {
-    name: "vscode",
-    label: "VS Code (.vscode/mcp.json)",
-    configPath: ".vscode/mcp.json",
-    configKey: "servers"
-  },
-  windsurf: {
-    name: "windsurf",
-    label: "Windsurf (.windsurf/mcp.json)",
-    configPath: ".windsurf/mcp.json",
-    configKey: "mcpServers"
-  },
-  codex: {
-    name: "codex",
-    label: "Codex (.codex/mcp.json)",
-    configPath: ".codex/mcp.json",
-    configKey: "mcpServers"
-  }
-};
-var CLIENT_NAMES = Object.keys(MCP_CLIENTS);
-function isValidClient(client) {
-  return CLIENT_NAMES.includes(client);
-}
-function getClientConfig(client) {
-  return MCP_CLIENTS[client];
-}
-function generateMcpConfig(clientConfig) {
-  const serverConfig = {
-    command: "npx",
-    args: ["panda", "mcp"]
-  };
-  return {
-    [clientConfig.configKey]: {
-      panda: serverConfig
-    }
-  };
-}
-
-// src/init.ts
-async function initMcpConfig(options = {}) {
-  const { cwd = process.cwd() } = options;
-  let { clients } = options;
-  p.intro("Panda MCP Setup");
-  if (!clients || clients.length === 0) {
-    const selected = await p.multiselect({
-      message: "Select AI clients to configure:",
-      options: CLIENT_NAMES.map((client) => ({
-        value: client,
-        label: MCP_CLIENTS[client].label
-      })),
-      required: true
-    });
-    if (p.isCancel(selected)) {
-      p.cancel("Setup cancelled.");
-      process.exit(0);
-    }
-    clients = selected;
-  }
-  const validClients = clients.filter((client) => {
-    if (!isValidClient(client)) {
-      logger2.warn("mcp:init", `Unknown client: ${client}`);
-      return false;
-    }
-    return true;
-  });
-  if (validClients.length === 0) {
-    p.cancel("No valid clients selected.");
-    process.exit(1);
-  }
-  const results = [];
-  for (const client of validClients) {
-    const clientConfig = getClientConfig(client);
-    const configPath = resolve2(cwd, clientConfig.configPath);
-    const configDir = dirname(configPath);
-    if (!existsSync(configDir)) {
-      mkdirSync(configDir, { recursive: true });
-    }
-    const newConfig = generateMcpConfig(clientConfig);
-    let finalConfig = newConfig;
-    if (existsSync(configPath)) {
-      try {
-        const existingContent = readFileSync(configPath, "utf-8");
-        const existingConfig = JSON.parse(existingContent);
-        finalConfig = {
-          ...existingConfig,
-          [clientConfig.configKey]: {
-            ...existingConfig[clientConfig.configKey],
-            ...newConfig[clientConfig.configKey]
-          }
-        };
-      } catch {
-      }
-    }
-    writeFileSync(configPath, JSON.stringify(finalConfig, null, 2));
-    results.push({
-      client,
-      path: clientConfig.configPath,
-      created: true
-    });
-  }
-  p.note(results.map((r) => `${r.client}: ${r.path}`).join("\n"), "Created MCP configurations");
-  p.outro("MCP setup complete! Your AI assistants can now use Panda CSS tools.");
-  return results;
-}
+import {
+  MCP_CLIENTS,
+  createMcpServer,
+  generateMcpConfig,
+  initMcpConfig,
+  startMcpServer
+} from "./chunk-IBM3OGUU.mjs";
 export {
   MCP_CLIENTS,
   createMcpServer,
+  generateMcpConfig,
   initMcpConfig,
   startMcpServer
 };

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@pandacss/mcp",
-  "version": "1.11.4",
+  "version": "1.12.0",
   "description": "MCP server for Panda CSS AI assistants",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "bin": {
+    "panda-mcp": "bin.js"
+  },
   "author": "Segun Adebayo <joseshegs@gmail.com>",
   "license": "MIT",
   "exports": {
@@ -30,23 +33,25 @@
     "access": "public"
   },
   "files": [
-    "dist"
+    "dist",
+    "bin.js"
   ],
   "dependencies": {
-    "@clack/prompts": "0.11.0",
+    "@clack/prompts": "1.6.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "cac": "6.7.14",
     "zod": "^4.0.0",
-    "@pandacss/logger": "1.11.4",
-    "@pandacss/node": "1.11.4",
-    "@pandacss/token-dictionary": "1.11.4",
-    "@pandacss/types": "1.11.4"
+    "@pandacss/logger": "1.12.0",
+    "@pandacss/node": "1.12.0",
+    "@pandacss/token-dictionary": "1.12.0",
+    "@pandacss/types": "1.12.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=20.12.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format=esm,cjs",
-    "build-fast": "tsup src/index.ts --format=esm,cjs",
+    "build": "tsup src/index.ts src/cli.ts --format=esm,cjs",
+    "build-fast": "tsup src/index.ts src/cli.ts --format=esm,cjs",
     "dev": "pnpm build-fast --watch"
   }
 }