Gemini UI MCP

面向所有人的 UI 设计 MCP：调用 Gemini 生成结构化设计规范（JSON），再由你的编码工具实现与优化。

特性

• 输出可验证的 JSON 设计规范（tokens、布局、组件树、交互、可访问性）
• 框架无关，适配任意前端栈
• 支持自动读取项目文件上下文，复用现有风格
• 可选输出 HTML/CSS/SVG artifacts（仍在 JSON 内）

目录结构

• server/ MCP 服务器（Node）
• schemas/ 输入/输出 JSON Schema
• prompts/ Gemini 3 提示词模板
• plan.md 设计定义与实现路径

环境要求

• Node.js 18+（内置 fetch）

配置

仅使用 .env 配置（可用 .env.example 复制）：

cp .env.example .env

.env 示例：

GEMINI_API_KEY="your_key"
GEMINI_MODEL="gemini-3-flash-preview"
# 可选：避免 MCP 工具调用超时
# GEMINI_TIMEOUT_MS=20000
# GEMINI_RETRIES=0
# 可选：禁用二次修复请求
# GEMINI_REPAIR_ENABLED=false

说明：

• .env 会自动加载
• .env 含密钥，请勿提交到版本库（已在 .gitignore 中忽略）

本地运行（调试用）

npm install
npm run start

npm run start 等价于 node server/index.js。

MCP 工具

工具名仅包含字母/数字/下划线：

• ui_design_generate 生成 UI 设计规范
• ui_design_validate 校验设计规范是否符合 schema
• context_discover 自动发现项目中与样式/组件相关的文件
• context_read_files 读取文件内容（受限于 root 与大小限制）

在 Codex CLI 中使用

编辑 ~/.codex/config.toml，新增 MCP server：

[mcp_servers.gemini_ui]
command = "node"
args = ["/path/to/gemini_ui_mcp/server/index.js"]
startup_timeout_sec = 60

请把 /path/to/gemini_ui_mcp 替换为你的实际路径。配置完成后重启 Codex CLI。

说明：Codex CLI 启动 MCP 进程，不需要手动运行 npm run start。

请求示例（最小）

{
  "goal": "Design a pricing page for a B2B SaaS",
  "platform": { "targets": ["web"] },
  "context": {
    "project_summary": "We offer an AI workflow tool for teams.",
    "file_context": { "strategy": "manual" }
  },
  "content": {
    "sections": [
      { "id": "hero", "purpose": "Summarize value and CTA" },
      { "id": "tiers", "purpose": "Show three pricing tiers" }
    ]
  },
  "output_preferences": {
    "json_only": true,
    "allow_artifacts": true,
    "language": "en"
  }
}

自动读取项目文件（增强风格一致性）

"context": {
  "project_summary": "...",
  "file_context": {
    "strategy": "auto",
    "include": ["**/*.{css,ts,tsx}", "**/styles/**"],
    "exclude": ["**/node_modules/**"],
    "max_files": 20,
    "max_total_bytes": 300000
  }
}

hybrid 模式可手动提供部分文件内容：

"file_context": {
  "strategy": "hybrid",
  "files": [
    { "path": "src/styles/theme.css", "content": "..." }
  ]
}

安全与限制

• 文件读取仅限 root 目录，默认是 MCP 运行目录
• 读取上限受 max_files、max_bytes_per_file、max_total_bytes 控制
• 二进制文件会自动跳过

常见问题

Q: 为什么强制 JSON 输出？ A: 便于工具稳定解析、验证与版本化。

Q: 默认语言是什么？ A: 默认英文，设置 output_preferences.language 可改为任意语言。

Q: 报错 “This operation was aborted” 是什么原因？ A: 通常是 Gemini 请求超时。可在 .env 中提高 GEMINI_TIMEOUT_MS（例如 45000），并重启 Codex CLI。

Q: 报错 “schema validation failed” 怎么办？ A: MCP 会自动清洗与修复输出；如仍失败，可降低请求复杂度或缩短上下文。

Q: 报错 “Invalid request” 怎么办？ A: 输入不符合 request schema。建议至少提供 goal/platform/context/content/output_preferences。