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 文件。