prototype-mapper-mcp

v0.1.0

Published

a month ago

MCP server for mapping prototype to project components using Gemini AI

0High
0Medium
0Low

ruanguangguang

mcp prototype component-mapping gemini ai

Prototype Mapper MCP

原型组件映射 MCP 服务器 - 通过 Google Gemini 3 Pro 分析原型页面，自动映射到项目公共组件库。

功能特性

🔍 原型分析：使用 Google Gemini 3 Pro 深度分析原型页面
🎯 组件映射：自动将原型元素映射到项目公共组件库
📊 智能报告：生成详细的组件映射报告（JSON/Markdown）
🔗 MCP 集成：与 Chrome DevTools MCP 无缝配合
⚡ 规范检查：自动检测违反项目规范的设计

安装

cd package/prototype-mapper-mcp
npm install
npm run build

配置

1. 设置 Gemini API Key

方式一：环境变量

export GEMINI_API_KEY=your_api_key_here

方式二：运行时配置

通过 MCP 工具 set_gemini_api_key 动态设置。

2. 配置 MCP 服务器

在 Kiro 的 MCP 配置文件中添加：

{
  "mcpServers": {
    "prototype-mapper": {
      "command": "node",
      "args": ["/path/to/package/prototype-mapper-mcp/build/index.js"],
      "env": {
        "GEMINI_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

使用流程

步骤 1: 使用 Chrome DevTools MCP 获取原型信息

// 1. 导航到原型页面
mcp_chrome_devtools_navigate_page({ 
  url: "https://lanhu.com/your-prototype-url" 
})

// 2. 获取页面快照（DOM 结构）
const snapshot = mcp_chrome_devtools_take_snapshot()

// 3. 获取页面截图（可选）
const screenshot = mcp_chrome_devtools_take_screenshot()

步骤 2: 调用 analyze_prototype 分析原型

const report = mcp_prototype_mapper_analyze_prototype({
  url: "https://lanhu.com/your-prototype-url",
  snapshot: snapshot.content,
  screenshot: screenshot.content // 可选
})

步骤 3: 获取映射报告

// JSON 格式
const jsonReport = mcp_prototype_mapper_get_cached_report({ 
  format: "json" 
})

// Markdown 格式（更易读）
const markdownReport = mcp_prototype_mapper_get_cached_report({ 
  format: "markdown" 
})

可用工具

1. analyze_prototype

分析原型页面并生成组件映射报告。

参数：

url (string, 必需): 原型页面 URL
snapshot (string, 必需): 页面快照（DOM 结构）
screenshot (string, 可选): 页面截图

返回：组件映射报告（JSON 格式）

2. get_cached_report

获取缓存的组件映射报告（最近一次分析结果）。

参数：

format (string, 可选): 输出格式（json 或 markdown），默认 json

返回：组件映射报告

3. get_component_library

获取项目组件库清单。

参数：

category (string, 可选): 组件分类
- all: 全部组件（默认）
- tables: 表格组件
- forms: 表单组件
- dialogs: 弹窗组件
- buttons: 按钮组件
- navigation: 导航组件
- business: 业务组件
- others: 其他组件

返回：组件库信息

4. set_gemini_api_key

设置 Gemini API Key（运行时配置）。

参数：

api_key (string, 必需): Gemini API Key

返回：设置成功确认

5. get_usage_guide

获取使用指南。

返回：详细的使用指南文档

输出格式

JSON 格式报告

{
  "prototypeUrl": "原型地址",
  "analyzedAt": "2026-01-31T12:00:00.000Z",
  "summary": {
    "totalElements": 10,
    "mappedElements": 8,
    "unmappedElements": 2
  },
  "layoutAnalysis": {
    "structure": "页面采用上下布局，顶部为搜索栏，中部为数据表格",
    "containers": ["Tab", "TabPane"],
    "spacing": "标准间距 16px"
  },
  "mappings": [
    {
      "prototypeElement": {
        "type": "表格",
        "description": "用户列表表格",
        "location": "页面中部",
        "features": ["分页", "排序", "筛选", "行选择"]
      },
      "projectComponent": {
        "name": "BaseTable",
        "path": "@/components/Table/Table",
        "reason": "标准 CRUD 列表，支持分页、排序、筛选、行选择",
        "props": {
          "url": "/api/v1/users/list",
          "columns": "...",
          "isDrag": true,
          "isChecked": true
        },
        "example": "<BaseTable ref={tableRef} url=\"/api/v1/users/list\" ... />"
      },
      "confidence": 0.95
    }
  ],
  "warnings": [
    "⚠️ 原型使用了 Container 组件作为页面容器，这已被废弃，应使用 Tab + TabPane"
  ],
  "suggestions": [
    "💡 建议使用 TableFilter 组件包裹筛选按钮，提升用户体验"
  ]
}

Markdown 格式报告

生成可读性更强的 Markdown 文档，包含：

📊 分析摘要
🏗️ 布局分析
🎯 组件映射清单（含使用示例）
⚠️ 警告信息
💡 优化建议

组件映射规则

表格场景

标准 CRUD 列表 → BaseTable

表单场景

字段数量 < 4 → 单独组件（BaseInput、Select）
字段数量 4-10 → 考虑 DyForm
字段数量 > 10 → 强烈推荐 DyForm
有动态显隐逻辑 → DyForm

弹窗场景

简单确认/取消 → ConfirmBox
表单编辑、详情查看 → BaseDrawer
图表、图片预览 → DialogPreView 或 PreviewDialog
其他通用弹窗 → BaseDialog

导航场景

2-5 个选项的简单切换 → Segment
超过 5 个选项或内容复杂 → Tab + TabPane
页面容器 → 必须使用 Tab + TabPane

注意事项

API Key 安全：不要在代码中硬编码 API Key
快照质量：确保 Chrome DevTools MCP 获取的快照完整
映射置信度：confidence < 0.5 的映射需要人工审核
规范检查：注意 warnings 中的规范违反提示

常见问题

Q: 如何提高映射准确度？

提供完整的页面快照
提供页面截图（可选）
确保原型设计符合项目规范

Q: 如何处理未映射的元素？

检查是否有类似的业务组件
考虑扩展现有组件
必要时开发新组件

Q: 如何使用映射报告？

作为开发任务的输入
作为代码审查的参考
作为组件选型的依据

开发

# 安装依赖
npm install

# 构建
npm run build

# 监听模式
npm run watch

# 开发模式
npm run dev

技术栈

MCP SDK: @modelcontextprotocol/sdk
AI 模型: Google Gemini 3 Pro
语言: TypeScript
运行时: Node.js >= 18.0.0

License

MIT