Mozaic MCP 服务器

npm version npm downloads License: MIT Documentation

为 ADEO 的 Mozaic 设计系统提供的独立 Claude Code 技能和 MCP 服务器。

📚 文档 • 🎮 MCP 演练场

概览

此包为在 AI 助手中使用 Mozaic 设计系统提供了两种互补的工具：

🤖 Claude Code 技能 - 7 种交互式技能，用于指导组件构建和设计令牌使用
🔌 MCP 服务器 - 包含 17 种工具的模型上下文协议服务器，用于以编程方式访问 Mozaic 资源

包含内容

资源类型	数量	描述
设计令牌	586	颜色、排版、间距、阴影、边框、断点
组件	131+	Vue 3、React、Web Components 和 Freemarker 宏，附带完整文档
图标	1,473	15 个类别的 SVG 图标
CSS 工具类	6	Flexy 网格、容器、外边距、内边距、比例、滚动
文档	281	可搜索的使用指南和最佳实践
MCP 工具	17	对所有资源的编程访问
Claude 技能	7	适用于 Vue、React、Web Components、Freemarker 及通用场景的交互式工作流

快速入门

交互式安装（推荐）

npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools

使用箭头键和空格键选择组件，然后按回车键进行安装。

一键安装

# Install everything (skills + MCP server)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools all

# Install only skills (for Claude Code)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills

# Install only MCP server (for Claude Desktop)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools mcp

检查安装状态

npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools list

安装前试用

无需安装，直接在浏览器中测试 MCP 工具：

🎮 打开 MCP 演练场

演练场允许您：

交互式测试所有 11 种 MCP 工具
浏览组件、令牌和图标
生成代码片段
搜索文档

Claude Code 技能

6 种独立技能，为使用 Mozaic 构建项目提供交互式工作流。

可用技能

技能	描述	使用场景
mozaic-vue-builder	交互式 Vue 3 组件生成器	使用 Mozaic 构建 Vue 应用
mozaic-react-builder	交互式 React/TSX 组件生成器	使用 Mozaic 构建 React 应用
mozaic-webcomponents-builder	交互式 Web Components 生成器	使用原生 Web Components 构建框架无关应用
mozaic-freemarker-builder	交互式 Freemarker 宏生成器	使用 Freemarker 构建服务端模板
mozaic-design-tokens	设计令牌和样式专家	访问颜色、排版、间距
mozaic-css-utilities	CSS 工具类和布局	构建响应式布局
mozaic-icons	图标搜索和集成	查找并使用 Mozaic 图标

技能工作原理

技能会根据上下文在 Claude Code 中自动激活，或者您可以手动调用它们：

User: "I need a login form with Mozaic"

Claude Code 将自动激活相应的技能（Vue 或 React 生成器）并引导您完成：

组件选择
Props 配置
代码生成
安装说明

详细文档请参阅 SKILLS.md。

MCP 服务器工具

14 种通过模型上下文协议访问 Mozaic 资源的编程工具。

可用工具

工具	类别	描述
`get_design_tokens`	令牌	按类别（颜色、排版、间距等）查询令牌
`get_component_info`	组件	获取组件的 props、slots、事件和文档
`list_components`	组件	按类别或框架列出组件
`generate_vue_component`	代码生成	生成带 props 的 Vue 3 SFC 代码
`generate_react_component`	代码生成	生成带 TypeScript 的 React/TSX 代码
`generate_webcomponent`	代码生成	生成带导入的原生 Web Component HTML
`get_webcomponent_info`	Web Components	获取属性、slots、事件、CSS 属性
`list_webcomponents`	Web Components	按类别列出 Web 组件
`generate_freemarker`	代码生成	生成带配置的 Freemarker 宏代码
`get_freemarker_info`	Freemarker	获取宏配置选项和用法
`list_freemarker`	Freemarker	按类别列出 Freemarker 宏
`search_documentation`	文档	在 281 个文档页面中进行全文搜索
`get_css_utility`	CSS	获取 CSS 工具类和示例
`list_css_utilities`	CSS	列出可用的 CSS 工具类
`search_icons`	图标	按名称、类型或类别搜索 1,473 个图标
`get_icon`	图标	获取图标 SVG 和框架代码
`get_install_info`	安装	获取 npm/yarn/pnpm 安装命令

配置

添加到您的 Claude Code 或 Claude Desktop 设置中：

针对 Claude Code (在 .claude/settings.json 中)：

{
  "mcpServers": {
    "mozaic": {
      "command": "npx",
      "args": ["-y", "mozaic-mcp-server"]
    }
  }
}

针对 Claude Desktop (在 ~/Library/Application Support/Claude/claude_desktop_config.json 中)：

{
  "mcpServers": {
    "mozaic": {
      "command": "npx",
      "args": ["-y", "mozaic-mcp-server"]
    }
  }
}

使用示例

在 Claude Code 中使用技能

技能会根据您的请求自动激活：

You: "I need a responsive grid with 3 columns"
Claude: [activates mozaic-css-utilities skill]
        Here's the Flexy grid solution...

You: "Add a shopping cart icon"
Claude: [activates mozaic-icons skill]
        I found these cart icons...

以编程方式使用 MCP 工具

配置完成后，Claude 可以直接使用 MCP 工具：

You: "What design tokens are available?"
Claude: [calls get_design_tokens tool]
        Found 586 tokens across 7 categories...

You: "Generate a React button component"
Claude: [calls get_component_info, then generate_react_component]
        Here's your Button component with TypeScript...

CLI 命令

adeo-mozaic-install-tools CLI 提供以下命令：

# Interactive mode (default)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools

# Install all components
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools all

# Install skills only
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills

# Install MCP server only
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools mcp

# Check status
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools list

# Remove components
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools remove skills
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools remove mcp
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools remove all

# Show help
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools --help

架构

┌─────────────────────────────────────┐
│   Claude Code / Claude Desktop      │
│                                     │
│   ┌─────────────┐  ┌─────────────┐ │
│   │   Skills    │  │ MCP Server  │ │
│   │  (5 total)  │  │ (11 tools)  │ │
│   └─────────────┘  └─────────────┘ │
│          │                │         │
└──────────┼────────────────┼─────────┘
           │                │
           ▼                ▼
    ┌──────────────────────────┐
    │  Shell Scripts (14)      │
    │  ↓ sqlite3 queries       │
    └──────────────────────────┘
               ▼
    ┌──────────────────────────┐
    │  SQLite Database         │
    │  ~/.claude/mozaic.db     │
    │                          │
    │  • 586 tokens            │
    │  • 91 components         │
    │  • 1,473 icons           │
    │  • 281 docs              │
    └──────────────────────────┘

文件位置

安装后：

~/.claude/
├── mozaic.db                      # SQLite database (all Mozaic data)
├── skills/                        # Claude Code skills
│   ├── mozaic-vue-builder/
│   ├── mozaic-react-builder/
│   ├── mozaic-design-tokens/
│   ├── mozaic-css-utilities/
│   └── mozaic-icons/
└── (Claude Code settings.json)    # MCP server config

~/Library/Application Support/Claude/
└── claude_desktop_config.json     # Claude Desktop MCP config

开发

先决条件

Node.js ≥25.2.0
pnpm (推荐)

设置

# Clone the repository
git clone https://github.com/MerzoukeMansouri/adeo-mozaic-mcp.git
cd mozaic-mcp-server

# Install dependencies
pnpm install

# Build the project (compiles TypeScript + builds database)
pnpm build

# Run tests
pnpm test

# Start MCP server in debug mode
pnpm start:debug

项目结构

mozaic-mcp-server/
├── src/                    # TypeScript source code
│   ├── index.ts           # MCP server entry point
│   ├── tools/             # MCP tool implementations
│   └── database/          # Database utilities
├── skills/                # Claude Code skills
│   ├── mozaic-vue-builder/
│   │   ├── skill.md       # Skill instructions
│   │   └── scripts/       # Shell scripts (4)
│   └── ...                # Other skills
├── scripts/               # Build and utility scripts
│   ├── build-index.ts     # Database builder
│   └── generate-docs.ts   # Documentation generator
├── data/                  # Generated database
│   └── mozaic.db
├── repos/                 # Mozaic Design System repositories (git submodules)
│   ├── mozaic-design-system/
│   ├── mozaic-vue/
│   └── mozaic-react/
├── bin/                   # CLI entry points
│   └── install.js         # Installation CLI
└── website/               # Documentation website

构建数据库

SQLite 数据库是从 Mozaic 设计系统仓库构建的：

# Update submodules
git submodule update --init --recursive

# Build database
pnpm build

它索引了：

来自 mozaic-design-system/packages/tokens 的设计令牌
来自 mozaic-vue 和 mozaic-react 的组件
来自 mozaic-design-system/packages/icons 的图标
来自所有仓库的文档

贡献

欢迎贡献！请遵循以下准则：

Fork 本仓库
创建功能分支 (git checkout -b feature/amazing-feature)
使用 Conventional Commits 提交更改
推送到分支 (git push origin feature/amazing-feature)
提交 Pull Request

提交规范

我们使用带有常规提交的语义化版本控制：

feat: - 新功能（次要版本升级）
fix: - 错误修复（补丁版本升级）
feat!: 或 BREAKING CHANGE: - 重大更改（主版本升级）
chore:, docs:, style:, refactor:, test: - 无版本升级

资源

文档与工具

📚 文档: https://merzoukemansouri.github.io/adeo-mozaic-mcp/
🎮 MCP 演练场: https://merzoukemansouri.github.io/adeo-mozaic-mcp/#/playground
GitHub: https://github.com/MerzoukeMansouri/adeo-mozaic-mcp
npm: https://www.npmjs.com/package/mozaic-mcp-server

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

如有问题或疑问：

📚 阅读在线文档
🎮 尝试 MCP 演练场
🐛 在 GitHub 上提交问题
📖 查看技能文档
🎨 查看 Mozaic 设计系统文档

为 ADEO 社区倾心打造 ❤️

Mozaic 设计系统由 ADEO 维护

Mozaic MCP Server