MCP Tailwind Gemini

🚀 MCP Tailwind Gemini Server

MCP Tailwind Gemini Server 是一款先进的模型上下文协议（MCP）服务器，它集成了 Gemini AI，支持 Tailwind CSS。该服务器具备 跨平台支持 能力，能在所有主流开发环境中提供智能设计辅助。

🚀 快速开始

安装

前提条件

• Node.js 18 或更高版本
• npm 或 yarn 包管理器
• Docker（用于容器化部署）
• （可选）用于 AI 功能的 Gemini API 密钥

使用 Docker 快速开始

1. 克隆仓库：

git clone https://github.com/Tai-DT/mcp-tailwind-gemini.git
cd mcp-tailwind-gemini

2. 配置环境：

# 复制环境模板
cp env.example .env

# 使用你的 API 密钥编辑 .env 文件
# GEMINI_API_KEY=your_actual_api_key_here

3. 使用 Docker 部署：

# 构建并运行生产容器
docker-compose -f docker-compose.prod.yml up -d

# 检查状态
docker ps | grep mcp-tailwind-server

本地开发设置

1. 安装依赖：

npm install

2. 构建项目：

npm run build

3. 配置环境：

# 复制环境模板
cp env.example .env

# 使用你的 API 密钥编辑
# GEMINI_API_KEY=your_actual_api_key_here

4. 运行开发服务器：

npm run dev

Claude 桌面端配置

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "tailwind-gemini": {
      "command": "npx",
      "args": ["mcp-gemini-cli", "--allow-npx"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\\Claude\\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

替代配置（使用 npm）：

{
  "mcpServers": {
    "mcp-tailwind-gemini": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/your/mcp-tailwind-gemini",
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

对于 Cursor IDE

将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mcp-tailwind-gemini": {
      "command": "node",
      "args": ["/path/to/your/mcp-tailwind-gemini/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

✨ 主要特性

🤖 人工智能驱动的设计

• 智能组件生成：使用 Gemini AI 创建复杂的 Tailwind 组件
• 智能优化：由 AI 驱动的类优化和冲突解决
• 设计分析：全面的设计质量评估并提供改进建议
• 主题创建：在 AI 辅助下生成连贯的设计系统

🎨 Tailwind CSS 工具

• 组件生成器：创建按钮、卡片、表单、导航、模态框和自定义组件
• 类优化器：清理冗余类并解决冲突
• CSS 转换器：将现有的 CSS/SCSS 转换为 Tailwind 类
• 布局生成器：为仪表盘、着陆页、博客等构建响应式布局
• 主题创建器：生成自定义调色板、排版和设计令牌
• 预览生成器：具有截图功能的可视化组件预览

🌐 跨平台集成

• 多框架支持：支持 React、Vue、Svelte、Angular，并可自动转换组件
• 构建工具集成：支持 Vite、Webpack、Next.js、Nuxt、SvelteKit 项目生成
• IDE 扩展：VS Code、WebStorm 插件提供实时协助
• 设计工具同步：Figma 插件实现设计到代码的转换
• 通用部署：支持 CLI 工具、浏览器扩展和 API 集成

🚀 高级功能

• 框架适配器：自动在框架之间转换组件
• 通用项目生成：使用任何技术栈创建全栈应用程序
• 多平台部署：可部署到开发环境、生产环境和设计工具
• 外部 API 集成：集成 Gemini、OpenAI、Claude、Figma 以增强 AI 功能
• 响应式设计：采用移动优先方法并优化断点
• 可访问性：检查 WCAG 合规性并提供增强建议
• 性能：优化捆绑包大小并分析渲染性能
• 可视化预览：生成组件截图以进行可视化展示

📦 安装指南

前提条件

• Node.js 18 或更高版本
• npm 或 yarn 包管理器
• Docker（用于容器化部署）
• （可选）用于 AI 功能的 Gemini API 密钥

使用 Docker 快速开始

1. 克隆仓库：

git clone https://github.com/Tai-DT/mcp-tailwind-gemini.git
cd mcp-tailwind-gemini

2. 配置环境：

# 复制环境模板
cp env.example .env

# 使用你的 API 密钥编辑 .env 文件
# GEMINI_API_KEY=your_actual_api_key_here

3. 使用 Docker 部署：

# 构建并运行生产容器
docker-compose -f docker-compose.prod.yml up -d

# 检查状态
docker ps | grep mcp-tailwind-server

本地开发设置

1. 安装依赖：

npm install

2. 构建项目：

npm run build

3. 配置环境：

# 复制环境模板
cp env.example .env

# 使用你的 API 密钥编辑
# GEMINI_API_KEY=your_actual_api_key_here

4. 运行开发服务器：

npm run dev

Claude 桌面端配置

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "tailwind-gemini": {
      "command": "npx",
      "args": ["mcp-gemini-cli", "--allow-npx"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\\Claude\\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

替代配置（使用 npm）：

{
  "mcpServers": {
    "mcp-tailwind-gemini": {
      "command": "npm",
      "args": ["run", "start"],
      "cwd": "/path/to/your/mcp-tailwind-gemini",
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

对于 Cursor IDE

将以下内容添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mcp-tailwind-gemini": {
      "command": "node",
      "args": ["/path/to/your/mcp-tailwind-gemini/dist/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_gemini_api_key_here"
      }
    }
  }
}

💻 使用示例

组件生成

{
  "tool": "generate_component",
  "description": "Create a responsive button component",
  "type": "button",
  "variant": "primary",
  "size": "lg",
  "framework": "react",
  "responsive": true,
  "accessibility": true
}

类优化

{
  "tool": "optimize_classes", 
  "html": "<div class=\"p-4 px-4 py-4 text-blue-500 text-blue-600\">Content</div>",
  "removeRedundant": true,
  "mergeConflicts": true
}

主题创建

{
  "tool": "create_theme",
  "brandColor": "#3B82F6",
  "style": "modern",
  "colorCount": 9,
  "includeConfig": true
}

设计分析

{
  "tool": "analyze_design",
  "html": "<div>...</div>",
  "checkAccessibility": true,
  "checkResponsive": true,
  "checkPerformance": true
}

预览生成

{
  "tool": "generate_preview",
  "html": "<button class=\"bg-blue-500 text-white px-4 py-2 rounded\">Button</button>",
  "width": 800,
  "height": 600
}

CSS 转换

{
  "tool": "convert_to_tailwind",
  "code": ".button { padding: 1rem; background: #3B82F6; }",
  "format": "css",
  "optimize": true
}

AI 建议

{
  "tool": "suggest_improvements",
  "html": "<div>...</div>",
  "context": "E-commerce product card",
  "focusAreas": ["accessibility", "performance", "ux"]
}

布局生成

{
  "tool": "create_layout",
  "type": "dashboard",
  "sections": ["header", "sidebar", "main", "footer"],
  "complexity": "medium",
  "framework": "react"
}

📚 详细文档

使用场景

创建组件

在 AI 辅助下生成生产就绪的组件：

• 具有可访问性特性的现代按钮变体
• 具有适当间距的响应式卡片布局
• 带有验证样式的表单组件
• 采用移动优先设计的导航菜单

设计优化

通过智能分析改进现有设计：

• 移除冗余的 Tailwind 类
• 解决冲突的实用类
• 优化性能和可维护性
• 增强可访问性合规性

主题开发

构建全面的设计系统：

• 生成连贯的调色板
• 创建排版比例
• 设计间距系统
• 导出 Tailwind 配置文件

跨平台使用

多框架开发

// Convert HTML component to any framework
{
  "tool": "generate_component",
  "description": "Modern button component",
  "framework": "react", // or "vue", "svelte", "angular"
  "typescript": true,
  "features": ["loading-state", "variant-support"]
}

通用项目生成

// Create full-stack project with any tech stack
{
  "tool": "create_project",
  "name": "My App",
  "framework": "react",
  "buildTool": "vite", // or "webpack", "nextjs", "nuxt"
  "features": ["typescript", "tailwind", "testing", "deployment"]
}

平台集成

# VS Code 扩展
code --install-extension tailwind-mcp-assistant

# WebStorm 插件  
# 从 JetBrains 市场安装："Tailwind MCP Assistant"

# Figma 插件
# 在 Figma 社区搜索 "Tailwind MCP"

# CLI 工具
npm install -g tailwind-mcp-cli
tmcp generate --framework react --description "Product card"

# 浏览器扩展
# 从 Chrome 网上应用店安装："Tailwind MCP Assistant"

跨平台工作流

# 1. 在 Figma 中设计 → 使用插件提取
# 2. 转换为多个框架  
tmcp convert --from figma --to react,vue,svelte

# 3. 生成优化项目
tmcp create-project --framework react --build vite
tmcp create-project --framework vue --build nuxt

# 4. 部署到多个平台
tmcp deploy --platforms vercel,netlify,aws

代码迁移

将现有 CSS 转换为 Tailwind：

• 将旧版 CSS 转换为实用类
• 从其他框架迁移
• 优化类使用模式
• 保持视觉一致性

开发

本地运行

# 开发模式，支持热重载
npm run dev

# 为生产环境构建
npm run build

# 启动生产服务器
npm start

测试 MCP 服务器

1. 使用 echo 命令测试：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

2. 使用简单工具调用测试：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "generate_component", "arguments": {"description": "A simple button", "type": "button"}}}' | node dist/index.js

3. 使用环境变量测试：

GEMINI_API_KEY="your_key" node dist/index.js

环境变量

• GEMINI_API_KEY：你的 Google Gemini API 密钥（可选）
• NODE_ENV：环境模式（开发/生产）

项目结构

src/
├── index.ts              # 主 MCP 服务器
├── tools/                # MCP 工具实现
│   ├── component-generator.ts
│   ├── class-optimizer.ts
│   ├── theme-creator.ts
│   ├── design-analyzer.ts
│   ├── preview-generator.ts
│   ├── css-converter.ts
│   ├── ai-suggestions.ts
│   └── layout-generator.ts
└── utils/
    └── gemini.ts          # Gemini AI 集成

贡献

我们欢迎贡献！请查看我们的贡献指南以获取详细信息。

开发设置

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如有必要添加测试
5. 提交拉取请求

Docker 部署

快速 Docker 设置

# 构建生产镜像
docker build -f Dockerfile.runtime -t mcp-tailwind-runtime:latest .

# 运行容器
docker run -d \
  --name mcp-tailwind-server \
  --env-file .env \
  --restart unless-stopped \
  mcp-tailwind-runtime:latest

Docker Compose（推荐）

# 启动生产栈
docker-compose -f docker-compose.prod.yml up -d

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f

# 停止服务
docker-compose -f docker-compose.prod.yml down

安全最佳实践

1. 环境变量：

# 使用 .env 文件（切勿提交到 Git）
cp env.example .env
# 使用你实际的 API 密钥编辑 .env

2. 容器安全：

# 运行时设置资源限制
docker run -d \
  --name mcp-tailwind-server \
  --env-file .env \
  --memory=512m \
  --cpus=1.0 \
  --restart unless-stopped \
  mcp-tailwind-runtime:latest

3. 网络隔离：

# 创建隔离网络
docker network create mcp-network

# 使用自定义网络运行
docker run -d \
  --name mcp-tailwind-server \
  --network mcp-network \
  --env-file .env \
  --restart unless-stopped \
  mcp-tailwind-runtime:latest

有关详细的 Docker 和安全指南，请参阅 DOCKER-SECURITY-GUIDE.md。

故障排除

常见问题

1. MCP 服务器无法启动：

• 确保你首先运行了 npm run build
• 检查 dist/index.js 是否存在
• 验证 Node.js 版本是否为 18 或更高

2. Gemini API 错误：

• 设置 GEMINI_API_KEY 环境变量
• 验证 API 密钥是否有效并具有适当的权限
• 检查你的互联网连接

3. Docker 容器问题：

# 检查容器日志
docker logs mcp-tailwind-server

# 验证环境
docker exec mcp-tailwind-server env | grep GEMINI

# 重启容器
docker restart mcp-tailwind-server

4. Claude 桌面端无法连接：

• 更新配置后重启 Claude 桌面端
• 检查配置文件路径是否正确
• 验证 JSON 语法是否有效

5. 构建错误：

# 清理并重新构建
rm -rf dist/ node_modules/
npm install
npm run build

调试模式

# 运行时启用调试日志
DEBUG=mcp:* node dist/index.js

# Docker 调试
docker run -it --rm \
  --env-file .env \
  mcp-tailwind-runtime:latest npm run dev

支持

• 问题反馈：GitHub Issues
• 文档：查看本 README 中的示例
• 讨论：GitHub Discussions

Built with ❤️ for the Tailwind CSS and AI community

🔧 技术细节

运行本地服务

# 开发模式，支持热重载
npm run dev

# 为生产环境构建
npm run build

# 启动生产服务器
npm start

测试 MCP 服务器

1. 使用 echo 命令测试：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js

2. 使用简单工具调用测试：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "generate_component", "arguments": {"description": "A simple button", "type": "button"}}}' | node dist/index.js

3. 使用环境变量测试：

GEMINI_API_KEY="your_key" node dist/index.js

环境变量

• GEMINI_API_KEY：你的 Google Gemini API 密钥（可选）
• NODE_ENV：环境模式（开发/生产）

项目结构

src/
├── index.ts              # 主 MCP 服务器
├── tools/                # MCP 工具实现
│   ├── component-generator.ts
│   ├── class-optimizer.ts
│   ├── theme-creator.ts
│   ├── design-analyzer.ts
│   ├── preview-generator.ts
│   ├── css-converter.ts
│   ├── ai-suggestions.ts
│   └── layout-generator.ts
└── utils/
    └── gemini.ts          # Gemini AI 集成

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。