@codify-ai/mcp-client

Codify MCP 客户端 - 连接 MasterGo 和 IDE / CLI 的桥梁

通过 MCP 协议连接 Codify 与 MasterGo

快速开始 · 功能特性 · 可用工具 · Codify 仪表盘

功能特性

• 🔌 一键安装：使用 npx 无需手动下载
• 📡 MCP 协议：完美集成 Cursor 等支持 MCP 的 IDE
• 🔐 安全认证：支持 access_key 认证
• 🛠️ 全能工具箱：包含设计稿读取、页面生成、前端代码导出和双向同步等专业工具

快速开始

1. 配置 MCP

例如：编辑 ~/.cursor/mcp.json（如果文件不存在则创建）：

{
  "mcpServers": {
    "codify": {
      "command": "npx",
      "args": [
        "-y",
        "@codify-ai/mcp-client",
        "--url=https://mcp.codify-api.com"
      ],
      "env": {
        "ACCESS_KEY": "sk-your-access-key"
      }
    }
  }
}

2. 重启IDE / CLI

重启Cursor、VSCode、Trae 等 IDE 或者 CLI 工具，或重新加载 MCP 服务器配置。

3. 开始使用

在 IDE / CLI 中，您可以：

方式 1：使用 AI 工具进行设计稿与代码的双向交互

直接在对话框输入指令，AI 会自动识别并调用工具：

• "获取 MasterGo 中选中的设计节点快照" (get_selection_node)
• "获取 MasterGo 中选中的图层代码（兼容旧名）" (get_selection_code)
• "导出可在前端渲染的普通 HTML" (get_frontend_code)
• "使用Codify design 工具设计一个深色模式的统计仪表盘" (design)
• "修改设计稿选中的图层，改为红色背景" (agent_update_node)
• "将我选中的图层删除" (agent_remove_node)
• "请确认后，把本地 HTML 全量同步到设计稿根节点" (agent_sync_design)
• "对比本地代码与设计稿的差异" (get_design_diff)

方式 2：加载核心规范工具

在对话中直接要求调用：

• get_guidelines
  • 推荐用法： 当你需要让 LLM 严格遵守 Codify 的转译规范、组件导入规则和最终硬闸门时，应优先调用该工具加载规则，而不是引用旧的资源 URI。

可用工具

🔍 获取与比对

get_selection_node

获取 MasterGo 中当前选中图层（或指定图层）的图层数据/设计节点快照。保留 d2c 组件语义，支持根节点完整保存，以及子节点自动合并到本地基准 HTML 文件。它不是前端代码导出工具。

• 参数: projectDir (必填), targetNodeId (可选), syncToBase (可选, 默认 true)
• 示例: "获取当前选中图层的设计节点快照"

get_selection_code

兼容旧名，行为与 get_selection_node 完全一致。

get_frontend_code

仅当用户明确要求“获取代码 / 导出前端代码 / 生成可运行 HTML / 保存到前端项目”时调用。调用前必须确认 frontendFramework；若用户未指定格式，先让用户在 html / vue / react / wxml / angular / android / json 中 N 选 1，不要默认 html。frontendFramework=html 落盘后会自动把设计稿截图保存到 projectDir/.codify/design/{documentId}/{rootId}/screenshot，并附带截图路径、前端代码视觉还原规范和 frontendReviewSession 状态块，要求助手直接编排修复流程：读取落盘 HTML/CSS、读取截图路径、对照截图定位不一致、修改本地文件并复核。后续用户反馈还原度不高或要求继续调整时，必须按 frontendReviewSession 基于当前已落盘 HTML 增量修复，禁止重新调用 get_frontend_code 覆盖文件；需要重新看设计稿时只调用 get_screenshot。

• 参数: projectDir (必填), frontendFramework (必选意图: html/vue/react/wxml/angular/android/json；未指定时先询问), targetNodeId (可选), outDir (可选), fileName (可选), writeToFile (可选)
• 示例: "导出当前选中页面的前端 HTML 到 src/pages"

get_design_diff

获取最新设计稿代码与本地 .codify 目录中旧代码的差异 (Diff)。用于全量或局部同步。

• 参数: projectDir (必填), targetNodeId (可选), filePath (可选)
• 示例: "对比最新设计稿，看看有哪些改动"

get_library_list

获取当前文件已订阅的远端团队库列表（名称、ID、组件数、样式数），不包含当前文件本地组件。

• 参数: 无
• 示例: "列出当前可用的订阅团队库"

get_component_info

确认本地组件或指定订阅团队库的可用快照，用于基于组件/变量/图标生成页面。默认按当前文件 ID / 团队库 ID 检查 .codify/library/...：完整快照直接复用，缺失或残缺时才拉取并落盘；只有用户明确要求刷新、重新拉取或获取最新数据时才传 refresh: true 强制覆盖。

• 参数: projectDir (必填), teamLibraryId (可选), teamLibraryName (可选), refresh (可选，默认 false)
• 示例: "使用当前文件本地组件，拉取组件信息" / "使用 Ant Design UIKit 团队库，拉取组件信息"

组件页面生成标准流程：

1. 每个页面流程仍先通过 design_page 让用户确认设计来源三选一，本地已有快照不能跳过；
2. 本地组件：调用 get_component_info({ teamLibraryName: "当前文件" })；订阅团队库：先调用 get_library_list 确认目标，再调用 get_component_info；两者都默认复用完整快照；
3. 调用 get_component_catalog 选择候选，再按功能区分批调用 get_component_details 读取实际使用组件；
4. 用户明确要求刷新，或 agent_create_component 后需要纳入新组件时，调用 get_component_info({ ..., refresh: true })。

get_variables

获取当前 MasterGo 文件中的全部本地变量。只读取当前文件，不读取远程团队库。

• 参数: projectDir (必填)
• 示例: "获取当前文件的全部变量"
• 返回: documentName、documentId、variables
• 落盘: 将 variables 字段内容写入 .codify/library/local-{documentId}/variable.json

agent_update_variables

创建、修改或排序当前 MasterGo 文件变量。

• 固定流程: 先调用 get_variables 落盘；创建一套变量时先 agent_update_variables 提交基础变量，工具成功后会自动刷新并落盘最新 variable.json，再 agent_update_variables 提交语义/引用变量；若自动刷新失败，再手动调用 get_variables
• 兼容别名: update_variables 保留给旧配置使用；新流程请始终使用 agent_update_variables
• 参数: projectDir (必填), filePath / variables / operations (可选；均未提供时读取最近一次 get_variables 落盘的 variable.json)
• 规则: 首次调用会自动加载 variable-generate 规则；已有变量修改必须保留 id
• 示例: "把当前变量文件提交到 MasterGo"

🎨 生成与设计

design_page

根据自然语言需求生成符合 Codify 规范的 HTML+CSS 代码。

• 参数: requirement (必填)
• 示例: "帮我设计一个深色模式的登录页面"

submit_page_to_canvas

将生成的 HTML 代码发送到 MasterGo 并创建新页面。

• 参数: code (可选), filePath (可选), projectDir (必填), saveCodeToLocal (可选)
• 示例: "在 MasterGo 中创建一个新页面，代码在 ./temp.html"

agent_generate_image

模型生图资产入口。仅当用户明确要求“用 AI/模型生成图片、生成原创图片资产、模型绘制插画或图像、画一张图片”时使用。普通页面生成、普通配图、英雄图、头像、背景图、产品图默认使用 <img src="{{keyword}}" />。

• 参数: projectDir (必填), sourcePath (必填), outputDir (可选), fileName (可选), mimeType (可选)
• 输入语义: sourcePath 是生图工具已经落盘的本地图片路径；如果上游模型返回 base64 或 URL，应由上游适配层先写成文件，再把路径传给本工具
• 失败兜底: 如果生图模型失败，或没有可读的 sourcePath，不要调用本工具；直接回退使用 <img src="{{keyword}}" />
• 默认目录: .codify/generated-images
• 安全策略: 不覆盖已有文件，重名时自动追加 -2、-3
• 画布换图: 如果生成图要替换到 MasterGo 的图片节点，保存成功后继续调用 agent_replace_node，在 code 中使用返回的相对 <img src>，并传入 projectDir
• 示例: "把这张生成图保存到 .codify/generated-images/cat.png"

agent_create_component

创建一个 MasterGo 母版组件或组件集（变体）。

• 参数: code (必填)
• 示例: "将这段 HTML 创建为 MasterGo 组件"

🛠️ 操作与更新

agent_update_node

将修改后的 HTML 代码发回 MasterGo 进行局部更新。这是默认修改工具。只要是在现有节点上做修改，就优先使用它。注意：必须包含 data-node-id。

• 参数: code (必填), targetNodeId (可选)
• 图片换图: 替换图片内容、换图、修改 <img src> 必须使用 agent_replace_node；agent_update_node 只用于图片尺寸、圆角、边框、阴影、布局等样式调整
• 示例: "更新选中的按钮颜色为蓝色"

agent_sync_design

将本地完整的静态 HTML 文件内容全量同步覆盖到 MasterGo 画布。每次调用前都必须获得用户对本次同步的明确确认；历史确认不能复用，也不能在每次本地修改后自动同步。

• 参数: filePath (必填), targetNodeId (推荐, 根节点 ID；不传时仅尝试从基准 HTML 文件名反推), userConfirmed (必填), userConfirmationText (必填, 用户本次确认原文)
• 示例: "请同步本地 index.html 到设计稿根节点"

agent_remove_node

在 MasterGo 中删除指定的或当前选中的图层。

• 参数: targetNodeId (可选)
• 示例: "删除选中的图层"

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！

Made with ❤️ by Codify Team