tmd-lkk/tmall-design-wiki-mcp-server

Tmall Design Wiki MCP Server

一个为AI编程工具（如Cursor、Claude Desktop等）提供天猫设计系统组件库访问的MCP服务器。让AI能够像shadcn/ui一样，成为"百科式组件库"。

功能特性

• 设计令牌访问 - 获取颜色、间距、圆角、字重等全局设计变量
• 组件库 - 访问7个完整的React+TypeScript组件
• 页面模板 - 基于实际案例的页面生成
• 智能搜索 - 快速查找设计规范和组件代码
• 工作流自动化 - 集成提示词扩写和代码验证
• 移动优先 - 专为手机天猫App设计的组件体系

快速开始

安装

npm install -g tmall-design-wiki-mcp-server

注意: tmall-design-wiki 知识库会作为依赖自动安装，无需手动安装。

为什么推荐 npx？

• ✅ 兼容所有环境：自动解决 Volta、nvm、n 等版本管理工具的 PATH 问题
• ✅ 无需路径配置：npx 会自动找到正确的包，无论安装在哪里
• ✅ 简单可靠：一个配置适用于所有用户和环境
• ✅ 自动更新：始终使用最新版本

故障排除

如果遇到连接问题，请按以下步骤排查：

# 1. 测试包是否正确安装
npx tmall-design-wiki-mcp-server --help

# 2. 如果步骤1失败，重新安装
npm install -g tmall-design-wiki-mcp-server

# 3. 确认使用npx配置（推荐）
# 复制配置到 .cursor/mcp.json

在Cursor中配置

1. 打开Cursor设置
2. 找到MCP服务器配置
3. 添加以下配置到.cursor/mcp.json：

{
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "npx",
      "args": ["tmall-design-wiki-mcp-server"]
    }
  }
}

使用 npx 方式：自动解决所有 Node.js 版本管理工具的 PATH 问题，无需手动配置路径。一个配置适用于所有环境！

在Claude Desktop中配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "npx",
      "args": ["tmall-design-wiki-mcp-server"]
    }
  }
}

API功能

设计令牌 (Design Tokens)

// 获取所有设计令牌
getDesignToken()

// 获取特定类别的令牌
getDesignToken({ category: "colors" })    // 颜色相关 (33个token)
getDesignToken({ category: "spacing" })   // 间距相关
getDesignToken({ category: "typography" }) // 字体相关
getDesignToken({ category: "borders" })   // 圆角边框相关

组件功能

// 列出所有组件
listComponents()
// 返回: capsuletabbar, price, productcard, productgrid, scrollloading, tabbar, topbar

// 获取组件源码
getComponentCode({ name: "productcard" })
// 返回: ProductCard.tsx, ProductCard.scss, ProductCard.md

// 获取组件演示
getComponentDemo({ name: "productcard" })
// 返回: 完整的HTML演示文件

页面功能

// 列出页面模板
listPages()

// 获取页面代码
getPageCode({ name: "guide-page" })

// 生成页面
generatePage({ 
  type: "guide-page", 
  config: { title: "商品导购", theme: "default" }
})

工作流功能

// 执行组件工作流
runWorkflow({ 
  type: "component", 
  input: { componentName: "productcard" }
})

// 执行页面工作流
runWorkflow({ 
  type: "page", 
  input: { pageType: "guide", config: {...} }
})

// 代码验证工作流
runWorkflow({ 
  type: "validation", 
  input: { code: "...", type: "component" }
})

// 提示词扩写工作流
runWorkflow({ 
  type: "prompt-expansion", 
  input: { userInput: "我需要一个商品列表页面" }
})

搜索功能

// 搜索知识库
search({ query: "商品卡片", limit: 10 })

代码验证

// 验证代码是否符合天猫设计规范
validate({ 
  code: "你的React组件代码",
  type: "component" 
})

使用示例

在Cursor中使用

1. 获取设计令牌：

   请帮我获取天猫设计系统的颜色token
   

2. 获取组件代码：

   我需要ProductCard组件的完整代码，包括TypeScript和样式
   

3. 生成页面：

   基于天猫设计规范，帮我生成一个商品导购页面
   

4. 验证代码：

   请验证我的组件代码是否符合天猫设计规范
   

可用组件列表

1. CapsuleTabBar - 胶囊式标签栏
2. Price - 价格显示组件
3. ProductCard - 商品卡片（支持1:1和3:4比例）
4. ProductGrid - 商品瀑布流布局
5. ScrollLoading - 滚动加载组件
6. TabBar - 底部标签栏
7. TopBar - 顶部导航栏

设计令牌类别

• 颜色系统 (33个token)：品牌色、文本色、背景色等
• 间距系统 (16个token)：基于8px网格的间距变量
• 字体系统 (28个token)：字体家族、大小、行高、字重
• 圆角系统 (10个token)：统一的圆角规范

开发

本地开发

# 克隆项目
git clone https://github.com/tmall-design/tmall-design-wiki-mcp-server.git
cd tmall-design-wiki-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 测试
npm test

目录结构

tmall-design-wiki-mcp-server/
├── src/
│   ├── index.ts        # MCP服务器入口
│   ├── handlers.ts     # API处理器
│   └── utils.ts        # 工具函数
├── dist/               # 编译输出
├── package.json
└── README.md

系统要求

• Node.js >= 18.0.0
• Cursor 或 Claude Desktop 支持MCP协议

贡献

欢迎提交Issue和Pull Request！

开发流程

1. Fork项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启Pull Request

许可证

MIT License - 详见 文件

相关链接

• 天猫设计官网
• MCP协议文档
• Cursor编辑器

故障排除

常见问题

1. MCP红点/连接失败

解决方案：确保使用npx配置

{
  "mcpServers": {
    "tmall-design-wiki": {
      "command": "npx",
      "args": ["tmall-design-wiki-mcp-server"]
    }
  }
}

这个配置自动解决所有PATH问题，适用于任何Node.js环境。

2. 命令找不到

• 确认Node.js版本 >= 18.0.0
• 检查npm全局路径配置
• 重启Cursor/Claude Desktop

3. 权限错误

• macOS/Linux: 使用 sudo npm install -g
• Windows: 以管理员身份运行

支持

如有问题或建议，请提交 GitHub Issues

🎉 更新日志

v1.2.3 (2024-09-15) - 极致简化版

• ✅ 彻底简化：删除环境检测脚本，专注npx方案
• ✅ 一个配置解决所有问题：npx自动处理PATH和环境兼容性
• ✅ 更清晰的帮助信息：直接展示配置方法
• ✅ 减少用户困惑：移除多余选择，专注最佳方案

v1.2.2 (2024-09-15)

• ✅ 单一npx配置方案：删除传统配置，避免用户选择困惑

v1.2.1 (2024-09-15)

• ✅ 推荐使用 npx 方式：完美解决所有 Node.js 版本管理工具的兼容性问题

v1.2.0 (2024-09-15)

• ✅ 环境自动检测：智能诊断 PATH 问题（已在v1.2.3中简化移除）

让AI像shadcn/ui一样，成为你的设计系统百科全书！ ✨