npm package: @particle-network/mcp-ui
Description: MCP server for using UniversalX UI components in your projects
Latest version: 0.0.3

# UniversalX UI MCP Server

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

## 概述

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

## 核心价值

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

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

## 工作原理

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

## 快速开始

### 1. 在用户项目中安装

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

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

### 2. 配置 Cursor/VS Code

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

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

### 3. 开始使用

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

#### 示例对话

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

**AI 助手** (通过 MCP):

```tsx
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` - 安装组件库

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

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

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

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

```typescript
{
  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` - 搜索可用组件

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

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

### 4. `getComponentDocs` - 获取组件文档

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

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

### 5. `generateExample` - 生成使用示例

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

// 生成完整的示例代码
```

### 6. `configureTheme` - 配置主题

```typescript
{
  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 响应**:

```tsx
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 响应**:

```tsx
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 版本兼容性
- 依赖冲突

## 配置选项

```javascript
// 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 服务器无法启动**

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

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

**Q: 组件导入错误**

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

**Q: TypeScript 类型错误**

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

## 贡献指南

欢迎贡献！请查看 [CONTRIBUTING.md](./CONTRIBUTING.md)

## 许可证

MIT License