UniversalX UI MCP Server

让开发者通过 AI 助手快速集成和使用 UniversalX Design System 组件库

概述

UniversalX UI MCP Server 是一个模型上下文协议服务，帮助开发者在他们的项目中通过 AI 助手（如 Cursor、Claude）快速集成和使用 UniversalX 组件库。

核心价值

当开发者在他们的项目中使用这个 MCP 服务后，可以：

1. 自然语言使用组件 - "添加一个主按钮到我的登录页面"
2. 智能代码生成 - 自动生成正确的导入语句和组件代码
3. 实时文档查询 - "UXButton 组件有哪些属性？"
4. 最佳实践指导 - 获取组件使用的最佳实践和示例
5. 主题配置助手 - 快速配置和定制主题

工作原理

graph LR
    A[开发者项目] --> B[AI 助手<br/>Cursor/Claude]
    B --> C[MCP Server]
    C --> D[UniversalX 组件库]
    C --> E[组件文档]
    C --> F[使用示例]
    B --> G[生成代码]
    G --> A

快速开始

1. 在用户项目中安装

# 安装 MCP 服务器
npm install -D @particle-network/mcp-ui

# 或使用全局安装
npm install -g @particle-network/mcp-ui

2. 配置 Cursor/VS Code

在项目根目录的 .cursorrules 或 .vscode/settings.json 中添加：

{
  "mcpServers": {
    "universalx-ui": {
      "command": "npx",
      "args": ["@particle-network/mcp-ui", "serve"],
      "env": {
        "PROJECT_PATH": "${workspaceFolder}"
      }
    }
  }
}

3. 开始使用

现在可以通过自然语言与 AI 助手交互：

示例对话

用户: "我需要创建一个登录表单"

AI 助手 (通过 MCP):

import { UXButton, UXInput, VStack, UXCard } from '@particle-network/ui-react';
import { useState } from 'react';

export function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');

  return (
    <UXCard className='w-full max-w-md mx-auto p-6'>
      <VStack spacing='lg'>
        <h2 className='text-2xl font-bold'>登录</h2>

        <UXInput type='email' placeholder='邮箱' value={email} onChange={(e) => setEmail(e.target.value)} />

        <UXInput type='password' placeholder='密码' value={password} onChange={(e) => setPassword(e.target.value)} />

        <UXButton color='primary' size='md' className='w-full'>
          登录
        </UXButton>
      </VStack>
    </UXCard>
  );
}

MCP 工具列表

1. installComponent - 安装组件库

自动检测项目类型并安装合适的包：

// 工具调用示例
{
  tool: "installComponent",
  params: {
    platform: "web" // 或 "native"
  }
}

// 执行结果
// - 安装 @particle-network/ui-react (Web)
// - 或安装 @particle-network/ui-native (React Native)
// - 配置 Tailwind (如果需要)
// - 添加主题提供者

2. useComponent - 生成组件使用代码

{
  tool: "useComponent",
  params: {
    component: "UXButton",
    props: {
      color: "primary",
      size: "lg",
      children: "点击我"
    }
  }
}

// 生成代码
import { UXButton } from '@particle-network/ui-react';

<UXButton color="primary" size="lg">
  点击我
</UXButton>

3. searchComponents - 搜索可用组件

{
  tool: "searchComponents",
  params: {
    query: "form input",
    platform: "web"
  }
}

// 返回匹配的组件列表及其文档

4. getComponentDocs - 获取组件文档

{
  tool: "getComponentDocs",
  params: {
    component: "UXButton"
  }
}

// 返回完整的组件文档、Props、示例

5. generateExample - 生成使用示例

{
  tool: "generateExample",
  params: {
    useCase: "contact form",
    components: ["UXInput", "UXTextarea", "UXButton"]
  }
}

// 生成完整的示例代码

6. configureTheme - 配置主题

{
  tool: "configureTheme",
  params: {
    colors: {
      primary: "#1890ff"
    }
  }
}

// 生成主题配置代码

资源 (Resources)

MCP 服务器提供以下资源供 AI 查询：

1. 组件目录

resource://components/catalog

返回所有可用组件的列表和简要说明

2. 组件文档

resource://components/{componentName}/docs

返回特定组件的完整文档

3. 设计令牌

resource://design/tokens

返回设计系统的颜色、间距、字体等令牌

4. 使用示例

resource://examples/{category}

返回特定类别的使用示例（表单、布局、导航等）

5. 最佳实践

resource://guides/best-practices

返回组件使用的最佳实践指南

智能提示 (Prompts)

MCP 服务器提供的智能提示模板：

1. 组件选择助手

"根据用户需求推荐最合适的组件"

2. 代码优化建议

"优化组件使用方式，提升性能和可维护性"

3. 无障碍性检查

"确保生成的代码符合无障碍标准"

4. 响应式设计

"自动添加响应式类名和断点"

使用场景示例

场景 1: 创建数据表格

用户: "我需要展示用户列表，包含姓名、邮箱和操作按钮"

MCP 响应:

import { UXTable, UXButton, HStack } from '@particle-network/ui-react';

const columns = [
  { key: 'name', title: '姓名' },
  { key: 'email', title: '邮箱' },
  {
    key: 'actions',
    title: '操作',
    render: (row) => (
      <HStack spacing='sm'>
        <UXButton size='sm' variant='ghost'>
          编辑
        </UXButton>
        <UXButton size='sm' variant='ghost' color='danger'>
          删除
        </UXButton>
      </HStack>
    ),
  },
];

export function UserTable({ users }) {
  return <UXTable columns={columns} data={users} />;
}

场景 2: 创建响应式导航栏

用户: "创建一个响应式导航栏，包含 logo 和菜单"

MCP 响应:

import { UXNavbar, UXNavItem, UXLogo, Flex } from '@particle-network/ui-react';

export function Navigation() {
  return (
    <UXNavbar>
      <Flex justify='between' align='center'>
        <UXLogo src='/logo.svg' alt='Company' />
        <Flex gap='lg' className='hidden md:flex'>
          <UXNavItem href='/'>首页</UXNavItem>
          <UXNavItem href='/products'>产品</UXNavItem>
          <UXNavItem href='/about'>关于</UXNavItem>
          <UXNavItem href='/contact'>联系</UXNavItem>
        </Flex>
        <UXMobileMenu className='md:hidden'>{/* 移动端菜单内容 */}</UXMobileMenu>
      </Flex>
    </UXNavbar>
  );
}

高级功能

1. 项目感知

MCP 服务器会自动检测：

• 项目类型（React/Next.js/React Native）
• 已安装的 UniversalX 包
• TypeScript 配置
• 样式方案（Tailwind/CSS Modules）

2. 智能导入

自动管理导入语句：

• 检测已有导入
• 合并新的组件导入
• 优化导入顺序

3. 代码风格适配

根据项目配置生成符合风格的代码：

• ESLint 规则
• Prettier 配置
• 命名约定

4. 版本兼容性

自动检查并提示：

• 组件库版本
• React 版本兼容性
• 依赖冲突

配置选项

// mcp-ui.config.js
module.exports = {
  // 默认平台
  platform: 'web', // 'web' | 'native'

  // 组件库版本
  version: 'latest',

  // 代码风格
  codeStyle: {
    quotes: 'single',
    semi: true,
    indent: 2,
  },

  // 自定义模板
  templates: {
    component: './templates/component.hbs',
  },

  // 启用的功能
  features: {
    autoImport: true,
    typescript: true,
    tailwind: true,
    storybook: false,
  },
};

故障排除

常见问题

Q: MCP 服务器无法启动

# 检查是否正确安装
npm list @particle-network/mcp-ui

# 手动测试
npx @particle-network/mcp-ui test

Q: 组件导入错误

# 确保组件库已安装
npm install @particle-network/ui-react

Q: TypeScript 类型错误

# 安装类型定义
npm install -D @types/react

贡献指南

欢迎贡献！请查看 CONTRIBUTING.md

许可证

MIT License