@pandacss/mcp

技能简介

@pandacss/mcp 是 Panda CSS 团队官方维护的 Model Context Protocol（MCP）服务器，作为独立 npm 包发布，让 Claude、Cursor、VS Code Copilot、Windsurf、Codex 等主流 AI 编程助手能够直接读懂并操作你项目里的 Panda CSS 设计系统。它把构建期生成的 token、recipe、pattern、condition、layer style 等元数据通过 MCP 协议暴露成结构化工具，AI 不再靠猜"项目里有哪些色值/断点/按钮变体"，而是通过工具实时查询真实配置，从而生成符合设计系统约束的样式代码。包本身刻意从 @pandacss/dev 中拆出，避免在普通项目里强制拉入 MCP SDK 和 Hono 依赖。

核心能力

• 设计 Token 查询：通过 get_tokens、get_semantic_tokens、get_color_palette 等工具查询 token 名称、CSS 变量值以及响应式/暗色模式下的语义映射，可按 category 过滤。
• 组件 Recipe 查询：get_recipes 暴露所有组件配方及其变体、默认值，支持按名称精确过滤，AI 写按钮/输入框时能直接拿到正确变体。
• 布局 Pattern 查询：get_patterns 返回 stack、hstack、grid 等布局原语的属性与使用示例。
• 运行时条件查询：get_conditions 一次性返回所有 breakpoint、伪类、color mode 条件。
• 动效与样式组合：get_keyframes、get_text_styles、get_layer_styles、get_animation_styles 把主题中的复合样式统一暴露。
• 项目级使用分析：get_usage_report 扫描代码库，统计 token/recipe 在源码中的使用频率，帮助 AI 找到死代码与未引用的 token。
• 配置解析：get_config 返回 Panda 解析后的完整配置对象，方便排查主题与样式冲突。
• 交互式一键接入：init 子命令支持交互选择要配置的 AI 客户端（Claude、Cursor、VS Code、Windsurf、Codex），自动写入对应 .mcp.json 文件。

安装配置

1. 运行 init 向导：npx -y @pandacss/mcp init，交互式选择要启用的 AI 客户端，命令会自动写入对应配置路径（Claude 写入 .mcp.json，Cursor 写入 .cursor/mcp.json，VS Code 写入 .vscode/mcp.json，Windsurf 写入 .windsurf/mcp.json，Codex 写入 .codex/mcp.json）。
2. 指定客户端：npx -y @pandacss/mcp init --client claude,cursor 跳过交互直接配置多个客户端。
3. 指定工作目录：npx -y @pandacss/mcp init --cwd ./my-project 在 monorepo 子包中初始化。
4. 手动启动服务：npx -y @pandacss/mcp，可选 --config ./panda.config.ts 自定义 Panda 配置路径、--cwd ./my-project 指定工作目录。
5. 依赖要求：Panda CSS 项目（已运行 panda init 生成 panda.config.ts 与 styled-system/），Node.js 18+，AI 客户端支持 MCP 协议。

使用步骤

1. 在 Panda CSS 项目根目录运行 npx -y @pandacss/mcp init，按交互提示勾选目标 AI 客户端。
2. 重启 AI 客户端（Claude Code 用 /mcp、Cursor 重启窗口、VS Code 重启扩展等）使其加载新写入的 MCP 配置。
3. 在对话中向 AI 助手提问，例如"列出我的设计系统里所有颜色 token"、"Button recipe 有哪些 variant"、"哪些 token 在代码里没被引用"、"项目里定义了哪些 breakpoint"。
4. AI 助手会调用对应 MCP 工具（如 get_tokens、get_color_palette、get_usage_report）并把结果展示给你。
5. 让 AI 助手基于返回结果生成或重构样式代码，例如新增一个 Button 变体或替换为某个 token。
6. 若主题/Panda 配置发生变更，重启 MCP 客户端即可让 AI 看到最新 schema，无需手动 reload token 缓存。
7. 排查配置问题可运行 npx -y @pandacss/mcp start --config ./panda.config.ts --cwd . 手动启动并查看 stdout 日志。

适用场景

• AI 辅助设计系统迁移：把旧项目从原生 CSS / Tailwind / Stitches 迁移到 Panda CSS 时，让 AI 直接读 token 与 recipe，避免写错 token 名称或漏变体。
• 跨团队设计一致性审查：让 Claude Code 在 PR Review 时通过 get_usage_report 找出偷偷写死色值或绕过 recipe 的代码。
• 设计系统文档自动化：在 Cursor 或 Claude 里问"列出所有未使用的 token"作为清理任务清单。
• 多客户端团队：同一 Panda 配置同时服务于 Claude Code、Cursor、VS Code、Windsurf、Codex 五种 AI 客户端，无需重复配置。
• Panda 新人 onboarding：让 AI 充当"项目内的 Panda 文档问答机"，新人问"项目里有哪些 layout pattern"立刻拿到答案。

适用人群

• 维护中型以上 Panda CSS 设计系统的前端工程师与设计系统 Owner。
• 使用 Claude Code / Cursor / VS Code Copilot 等 AI 工具进行日常开发、但希望 AI 输出严格符合现有 token / recipe 的开发者。
• 多人团队的设计系统治理负责人，希望通过 AI 自动化发现 token 滥用、未使用组件与不一致样式。
• Panda CSS 生态贡献者与文档维护者。

工作原理

@pandacss/mcp 在启动时读取 Panda CSS 项目的 panda.config.ts，通过 Panda 内置的 Node API（@pandacss/node）拿到合并后的主题对象，包括 tokens、semanticTokens、recipes、patterns、conditions、keyframes、textStyles、layerStyles、animationStyles 等。MCP 服务用 stdio 与 AI 客户端通信，把这些数据按需暴露为 MCP tools（如 get_tokens、get_recipes、get_conditions）。get_usage_report 通过 Panda 的 source scanner 在源码上做 AST 级扫描，统计 token/recipe 的实际引用次数。包结构上 @pandacss/mcp 与 @pandacss/dev 物理解耦，从而保证普通 Panda 用户不会被强制安装 MCP SDK 与 Hono 等大体积依赖。

官方链接

• npm 包：https://www.npmjs.com/package/@pandacss/mcp
• 官方文档：https://panda-css.com/docs/ai/mcp-server
• GitHub 仓库：https://github.com/chakra-ui/panda
• Panda 主站：https://panda-css.com
• Model Context Protocol 规范：https://modelcontextprotocol.io/