JinDaGe - superdesign-mcp-claude-code MCP Details

article

README

🚀 超级设计MCP服务器

超级设计MCP服务器是一个基于模型上下文协议（MCP）的服务器，它能将Superdesign——由@jasonzhou1993和@jackjack_eth开发的开源AI设计代理——以原生工具的形式集成到Claude Code中。该服务器就像一个“设计编排器”，能为你的集成开发环境（IDE）中的大语言模型（LLM）提供结构化的设计规范，让你无需Anthropic API密钥就能使用Superdesign强大的设计能力。

🚀 快速开始

安装依赖

npm install

构建服务器

npm run build

集成到Claude Code

将MCP服务器添加到Claude Code的配置中：

# 创建或编辑Claude Code的MCP设置文件
# 在macOS系统上：
mkdir -p ~/.claude-code
cp claude-mcp-config.json ~/.claude-code/mcp-settings.json

# 或者手动添加到现有的mcp-settings.json文件中：

示例 ~/.claude-code/mcp-settings.json 文件内容如下：

{
  "mcpServers": {
    "superdesign": {
      "command": "node",
      "args": ["/path/to/superdesign/dist/index.js"],
      "env": {}
    }
  }
}

重启Claude Code。
MCP服务器将在Claude Code中提供以下Superdesign编排工具：
- superdesign_generate - 为Claude提供生成设计的规范。
- superdesign_iterate - 为Claude提供改进现有设计的指令。
- superdesign_extract_system - 为Claude提供从截图中提取设计系统的指令。
- superdesign_list - 列出工作区中所有已创建的设计。

开发模式运行

npm run dev

✨ 主要特性

无需API密钥：直接利用Claude Code内置的大语言模型连接。
本地执行：作为MCP服务器完全在本地机器上运行。
IDE集成：可无缝集成到Claude Code中（也可能与Cursor、Windsurf或其他支持MCP的IDE集成，但未经过测试）。
基于开源：基于Superdesign.dev这个开源AI设计系统构建。

📦 安装指南

依赖安装

npm install

服务器构建

npm run build

💻 使用示例

基础用法

在Claude Code中配置好后，你可以使用自然语言调用Superdesign的功能，例如：

"生成一个现代仪表盘的用户界面设计"
"创建3种不同版本的登录页面线框图"
"设计一个用于产品卡片的React组件"
"为一家科技初创公司设计一个简约的标志"
"改进仪表盘设计，使其间距更合理"
"展示我所有设计的图库"

高级用法

`superdesign_generate`

返回供Claude Code生成设计的结构化规范：

用户界面设计：完整的响应式界面。
线框图：简约的黑白布局。
组件：单个的用户界面组件（HTML/React/Vue）。
标志：SVG格式的标志设计。
图标：SVG格式的图标设计。

参数：

prompt：要创建内容的描述。
design_type：设计类型（ui、wireframe、component、logo、icon）。
variations：要生成的不同版本数量（1 - 5，默认值为3）。
framework：组件使用的框架（html、react、vue）。

输出：详细的规范，包括Superdesign系统提示、文件命名模式和设计准则，供Claude Code执行。

`superdesign_iterate`

返回供Claude Code改进现有设计的迭代指令：

读取现有的设计文件。
提供结构化的反馈应用指南。
通过Superdesign原则保持设计的一致性。

参数：

design_file：现有设计文件的路径。
feedback：改进说明。
variations：要创建的不同版本数量。

输出：迭代规范，包括原始设计内容、要应用的反馈和Superdesign准则，供Claude Code执行。

`superdesign_extract_system`

返回供Claude Code从截图中提取设计系统的指令：

为视觉设计模式提供分析框架。
指导提取调色板、排版和间距。
指定可重用设计系统的JSON结构。

输出：提取规范和JSON模式，供Claude Code分析图像并创建设计系统文件。

`superdesign_list`

列出工作区中所有Superdesign创建的设计：

显示设计的不同版本。
显示提取的设计系统。
展示文件组织情况。

`superdesign_gallery`

生成一个交互式的HTML图库，用于查看所有设计：

基于浏览器的图库 - 在默认浏览器中打开。
视觉预览 - 在响应式网格中查看设计缩略图。
交互式功能 - 点击可全屏查看、复制文件路径。
移动设备响应式 - 在桌面、平板和移动设备上均可使用。
自动发现 - 查找 design_iterations/ 目录下的所有HTML/SVG文件。

参数：

workspace_path：工作区目录（可选，默认为当前目录）。

输出：包含嵌入式预览和JavaScript交互的图库HTML文件。图库会自动在浏览器中打开，提供类似Superdesign画布的体验。

📚 详细文档

编排器的工作原理

这个MCP服务器作为一个“设计编排器”，而不是直接的生成器，其工作流程如下：

用户请求：例如“生成一个现代仪表盘的用户界面”。
MCP服务器：返回详细的规范，包括：
- 完整的Superdesign系统提示和准则。
- 确切的文件路径和命名约定。
- 特定设计类型的指令。
- 要创建的不同版本数量。
Claude Code：接收规范并执行：
- 生成实际的HTML/SVG/React代码。
- 将文件保存到指定位置。
- 遵循所有Superdesign的设计原则。

文件组织

设计文件会自动保存到 superdesign/ 目录（可见文件夹）中：

design_iterations/ - 生成的设计文件（HTML/SVG文件）。
design_system/ - 提取的设计系统文件（JSON文件）。

优点

无需配置API密钥。
利用Claude Code现有的大语言模型能力。
保留Superdesign所有复杂的设计方法。
有合理的文件组织和命名约定。
支持完整的设计迭代工作流程。

🔧 技术细节

编排器的角色

该MCP服务器作为设计编排器，为Claude Code提供详细的设计规范，Claude Code根据这些规范生成实际的设计代码。

与Superdesign的关系

此MCP服务器是对Superdesign的补充集成。虽然Superdesign提供了一个可在多个编辑器中使用的IDE扩展，但这个MCP服务器通过以下方式特别增强了Claude Code的功能：

无需API密钥：使用Claude Code内置的大语言模型连接。
提供原生工具集成：无需手动复制提示。
支持直接调用工具：实现无缝工作流程，无需复制粘贴。

与Superdesign扩展的区别

| 方面 | Superdesign扩展 | 此MCP服务器 | |------|----------------------|-----------------| | 集成类型 | IDE扩展 | 原生MCP工具 | | Claude Code访问方式 | 手动复制提示 | 直接调用工具 | | API要求 | 需要单独的API密钥 | 使用Claude Code现有的连接 | | 用户体验 | 复制粘贴工作流程 | 自动编排 |

🔧 常见问题与解决方法

文件权限错误

如果你在运行MCP服务器时遇到权限错误，可以执行以下命令：

# 为构建后的文件添加执行权限
chmod +x dist/index.js

MCP工具未显示

如果安装后Superdesign工具未在Claude Code中显示，可以按以下步骤操作：

确保你已完全退出Claude Code（不仅仅是关闭窗口）。
从终端重启Claude Code。
验证服务器是否已注册：claude mcp list。
通过询问Claude "你有哪些可用的工具？" 来检查工具是否可用。

服务器注册问题

如果服务器注册失败，可以执行以下命令：

# 移除并重新添加服务器
claude mcp remove superdesign -s user
claude mcp add --scope user superdesign /path/to/superdesign/dist/index.js

构建错误

确保你安装了Node.js 16及以上版本：

node --version  # 版本号应不低于v16.0.0

📄 许可证

本项目遵循与原始Superdesign项目相同的许可证。有关许可证的详细信息，请参考Superdesign仓库。

superdesign-mcp-claude-code