@codify-ai/mcp-client 1.0.27 → 1.0.28

package/README.md

@@ -2,15 +2,15 @@
 
 <div align="center">
 
-![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
+![Version](https://img.shields.io/badge/version-1.0.28-blue.svg)
 ![License](https://img.shields.io/badge/license-MIT-green.svg)
 ![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)
 
-**Codify MCP 客户端 - 连接 Figma 和 Cursor 的桥梁**
+**Codify MCP 客户端 - 连接 MasterGo 和 IDE / CLI 的桥梁**
 
 通过 MCP 协议从远程 Codify 服务器获取代码
 
-[快速开始](#快速开始) · [配置说明](#配置说明) · [功能特性](#功能特性)
+[快速开始](#快速开始) · [功能特性](#功能特性) · [可用工具](#可用工具) · [Codify 仪表盘](https://codify.fun)
 
 </div>
 
@@ -21,33 +21,27 @@
 - 🔌 **一键安装**：使用 `npx` 无需手动下载
 - 📡 **MCP 协议**：完美集成 Cursor 等支持 MCP 的 IDE
 - 🔐 **安全认证**：支持 access_key 认证
-- 🛠️ **工具集成**：提供 `getCode` 和 `agent_create_page` 工具
-- 📦 **资源访问**：通过 URI `Codify://getCode/{content_id}` 访问代码
+- 🛠️ **全能工具箱**：包含代码获取、设计稿生成、双向同步等 10+ 个专业工具
+- 📦 **资源访问**：通过 URI `Codify://get_code/{content_id}` 访问代码
 
-## 架构说明
 
-```
-Figma Plugin (WebSocket)
-         ↓
-  Codify MCP Server (远程)
-         ↓
-   @codify-ai/mcp-client (本包)
-         ↓
-    Cursor IDE (本地)
-```
 
 ## 快速开始
 
-### 1. 配置 Cursor
+### 1. 配置 MCP
 
-编辑 `~/.cursor/mcp.json`（如果文件不存在则创建）：
+例如：编辑 `~/.cursor/mcp.json`（如果文件不存在则创建）：
 
 ```json
 {
   "mcpServers": {
     "codify": {
       "command": "npx",
-      "args": ["-y", "@codify-ai/mcp-client", "--url=https://mcp.codify-api.com"],
+      "args": [
+        "-y",
+        "@codify-ai/mcp-client",
+        "--url=https://mcp.codify-api.com"
+      ],
       "env": {
         "CODIFY_ACCESS_KEY": "sk-your-access-key"
       }
@@ -56,126 +50,121 @@ Figma Plugin (WebSocket)
 }
 ```
 
-### 2. 重启 Cursor
+### 2. 重启IDE / CLI
 
-重启 Cursor 或重新加载 MCP 服务器配置。
+重启Cursor、VSCode、Trae 等 IDE 或者 CLI 工具，或重新加载 MCP 服务器配置。
 
 ### 3. 开始使用
 
-在 Cursor 中，您可以：
-
-#### 方式 1：使用 AI 工具调用
+在IDE / CLI 中，您可以：
 
-对 AI 说：
 
-```
-请使用 getCode 工具获取 code_id 的代码
-```
+### 方式 1：将设计稿给其他人（研发）拉取代码到本地
 
-#### 方式 2：通过资源 URI 访问
+在 Codify 插件中选中一个元素，复制的指令然后给到其他人来获取代码。
 
-在代码或对话中引用：
+无需启动 MasterGo，直接在 IDE 中输入该指令即可获取代码。
 
 ```
-@codify://getCode/code_id
+codify://getCode/{contentId}
 ```
 
-## 配置说明
 
-### 命令行参数
 
-| 参数              | 说明              | 默认值                       |
-| ----------------- | ----------------- | ---------------------------- |
-| `--url=<URL>`     | Codify 服务器地址 | `https://mcp.codify-api.com` |
-| `--help`, `-h`    | 显示帮助信息      | -                            |
-| `--version`, `-v` | 显示版本号        | -                            |
+#### 方式 2：使用 AI 工具进行设计稿与代码的双向交互
 
-### 环境变量
+直接在对话框输入指令，AI 会自动识别并调用工具：
 
-| 变量名              | 说明                          | 必需 |
-| ------------------- | ----------------------------- | ---- |
-| `CODIFY_SERVER_URL` | 服务器地址（可被 --url 覆盖） | 否   |
-| `CODIFY_ACCESS_KEY` | 访问密钥                      | 是\* |
+- "获取 MasterGo 中选中的图层代码" (**get_selection_code**)
+- "使用Codify **design** 工具设计一个深色模式的统计仪表盘" (**design**)
+- "修改设计稿选中的图层，改为红色背景" (**agent_update_node**)
+- "将我选中的图层删除" (**agent_remove_node**)
+- "将我选中的图层，同步到本地代码" (**agent_sync_design**)
+- "对比本地代码与设计稿的差异" (**get_design_diff**)
 
-\*如果服务器启用了认证则必需
+#### 方式 3：引用核心规范资源
 
-## 使用示例
+在对话中通过或直接输入 URI 引用：
 
-### 示例 1：连接远程服务器（带认证）
+- `codify://generation-rules` 
+  - 逆向转译与代码规范：
+  你需要让 LLM 严格遵守转译代码规范才能完美的将它转译为 MasterGo 设计稿。当你需要将你已有的前端项目转换为设计稿的时候，必须让 LLM 读取此文档。
+
+- `codify://design-philosophy` 
+  - 核心设计哲学：
+  Codify为你总结了一套非常实用的UI设计哲学，它能够让LLM在生成页面的时候，保持优秀的设计审美。
+  
 
-```json
-{
-  "mcpServers": {
-    "codify": {
-      "command": "npx",
-      "args": ["-y", "@codify/mcp-client", "--url=https://codify.example.com"],
-      "env": {
-        "CODIFY_ACCESS_KEY": "sk-abc123xyz789"
-      }
-    }
-  }
-}
-```
 
-### 示例 2：使用环境变量
 
-```json
-{
-  "mcpServers": {
-    "codify": {
-      "command": "npx",
-      "args": ["-y", "@codify-api/mcp-client"],
-      "env": {
-        "CODIFY_SERVER_URL": "https://codify.example.com",
-        "CODIFY_ACCESS_KEY": "sk-abc123xyz789"
-      }
-    }
-  }
-}
-```
 
 ## 可用工具
 
-### getCode
+### 🔍 获取与比对
 
-获取指定频道的代码。
+#### **get_selection_code**
+获取 MasterGo 中当前选中图层（或指定图层）的代码。支持根节点完整保存，以及子节点自动合并到本地基准 HTML 文件。
+- **参数**: `projectDir` (必填), `targetNodeId` (可选), `syncToBase` (可选, 默认 true)
+- **示例**: "获取当前选中图层的代码"
 
-**参数：**
+#### **get_design_diff**
+获取最新设计稿代码与本地 `.codify` 目录中旧代码的差异 (Diff)。用于全量或局部同步。
+- **参数**: `projectDir` (必填), `targetNodeId` (可选), `filePath` (可选)
+- **示例**: "对比最新设计稿，看看有哪些改动"
 
-- `content_id` (string, 必需) - 频道 ID
+#### **get_code_list**
+列出所有可用的代码列表。
+- **参数**: 无
+- **示例**: "查看我可以拉取的代码列表"
 
-**示例：**
+#### **get_code**
+通过 `contentId` 获取特定代码并保存到本地。
+- **参数**: `contentId` (必填), `projectDir` (必填), `outDir` (必填), `documentId` (可选)
+- **示例**: "从频道 demo-123 获取代码"
 
-```
-AI，请使用 getCode 工具获取 demo-channel 的代码
-```
+### 🎨 生成与设计
 
-### getCodeList
+#### **design**
+根据自然语言需求生成符合 Codify 规范的 HTML+CSS 代码。
+- **参数**: `requirement` (必填)
+- **示例**: "帮我设计一个深色模式的登录页面"
 
-列出所有可用频道。
+#### **agent_create_page**
+将生成的 HTML 代码发送到 MasterGo 插件并创建新页面。
+- **参数**: `code` (可选), `filePath` (可选), `projectDir` (必填), `saveCodeToLocal` (可选)
+- **示例**: "在 MasterGo 中创建一个新页面，代码在 ./temp.html"
 
-**参数：** 无
+#### **agent_create_component**
+创建一个 MasterGo 母版组件或组件集（变体）。
+- **参数**: `code` (必填)
+- **示例**: "将这段 HTML 创建为 MasterGo 组件"
 
-**示例：**
+### 🛠️ 操作与更新
 
-```
-AI，请使用 getCodeList 工具查看所有频道
-```
+#### **agent_update_node**
+将修改后的 HTML 代码发回 MasterGo 进行局部更新。**注意：必须包含 `data-node-id`。**
+- **参数**: `code` (必填), `targetNodeId` (可选), `documentId` (可选)
+- **示例**: "更新选中的按钮颜色为蓝色"
 
-## 可用资源
+#### **agent_sync_design**
+将本地完整的静态 HTML 文件内容全量同步覆盖到 MasterGo 画布。
+- **参数**: `filePath` (必填), `targetNodeId` (必填, 根节点 ID), `documentId` (可选)
+- **示例**: "同步本地 index.html 到设计稿根节点"
 
-通过资源 URI 直接访问代码：
+#### **agent_remove_node**
+在 MasterGo 中删除指定的或当前选中的图层。
+- **参数**: `targetNodeId` (可选), `documentId` (可选)
+- **示例**: "删除选中的图层"
 
-```
-codify://{content_id}/current
-```
 
-**示例：**
 
-```
-codify://getCode/code_123
-codify://getCode/code_456
-```
+### 👤 系统信息
+
+#### **get_user_info**
+查看当前登录用户信息、团队信息以及配额使用情况。
+- **参数**: 无
+- **示例**: "查看我的配额还剩多少"
+
 
 ## 许可证
 

package/dist/index.js

@@ -140,14 +140,15 @@ async function saveCodeAndResources({
 }
 const zh = {
   createPage: {
-    description: "将代码发送到 Codify 插件转换为设计稿。\n\n【极致性能要求】若纯 HTML 已保存为本地文件，你必须且只能通过 filePath 传入该文件的绝对路径。严禁使用 Read 工具读取文件内容，严禁将大段代码写入 code 参数。工具底层会自动读取并传输，以节省 Token。只有当代码是你在当前对话中临时生成且尚未写入文件时，才允许使用 code 参数。\n\n⚠️ 逆向转译警告：严禁直接发送 Vue/React 等包含动态绑定 ({{}}) 或框架指令的业务代码！若要将业务代码转为设计稿，必须先执行【逆向转译】（参考 codify://generation-rules），将其转换为带静态假数据的纯 HTML 后再发送。",
+    description: `将代码发送到 Codify 插件转换为设计稿。
+    【极致性能要求】若纯 HTML 已保存为本地文件，你必须且只能通过 filePath 传入该文件的绝对路径。严禁使用 Read 工具读取文件内容，严禁将大段代码写入 code 参数。工具底层会自动读取并传输，以节省 Token。`,
     code: "【可选】要发送的 HTML 代码内容。仅当代码是临时生成且未保存为文件时使用。大段代码严禁使用此参数。",
     filePath: "【可选】本地 HTML 文件的绝对路径。若文件已存在本地，必须传此参数，工具会自动读取并执行落盘。",
     projectDir: "【必填】用户当前工作区的根目录绝对路径",
     saveCodeToLocal: "是否将插件返回的渲染结果保存到本地 .codify 目录（落盘机制）"
   },
   updateNode: {
-    description: "将修改后的 HTML 代码发回 MasterGo 画布进行【局部修改】（如改颜色、加文字、改间距等）。完成代码修改后，你必须同步调用此工具。注意：此工具一次只能同步一个节点及其关联子节点，必须传入 code。",
+    description: "将修改后的 HTML 代码发回 MasterGo 画布进行【局部修改】（如改颜色、加文字、改间距等）。⚠️ 【调用前置条件】：你必须且只能在通过 getSelectionCode 拿到该节点的最新代码后进行调用修改！完成代码修改后直接调用此类发送给插件。绝对不要去同步或修改本地基准文件！注意：仅传包含 data-node-id 的那一段 HTML 片段。",
     documentId: "当前 MasterGo 文档 ID。",
     documentPageId: "当前 MasterGo 页面 ID。",
     targetNodeId: "【选填】目标图层 ID (例如 123:456)。如果不传，则默认更新 MasterGo 中当前选中的图层。",
@@ -161,7 +162,7 @@ const zh = {
     filePath: "【必填】本地静态 HTML 文件的绝对路径（通常位于 .codify/... 目录下）。工具会自动读取内容。严禁传入 .vue/.tsx 业务代码路径！"
   },
   getSelectionCode: {
-    description: "获取 MasterGo 中当前选中图层（或指定图层）的代码。如果你获取的是子节点，工具只会将代码作为纯文本返回给你进行局部修改上下文，绝对不会在本地生成烦人的 HTML 碎片文件！若是根节点则会自动将完整页面代码同步保存到 .codify 目录。",
+    description: "获取 MasterGo 中当前选中图层（或指定图层）的代码。⚠️ 【严禁盲改】：用户的每一次修改操作（如改色、改文字等），你都必须首先调用本工具拉取最新的节点代码作为上下文！如果你获取的是子节点，工具只会将代码作为纯文本返回给你进行局部修改上下文，绝对不会在本地生成烦人的 HTML 碎片文件！若是根节点则会自动将完整页面代码同步保存到 .codify 目录。",
     projectDir: "【必填】用户当前工作区的根目录绝对路径",
     targetNodeId: "【选填】MasterGo图层ID (例如 123:456)。如果提供，将直接拉取该ID的代码；如果不提供，将拉取当前选中图层的代码。",
     syncToBase: "【选填】是否将获取到的子图层代码同步回本地 .codify 目录下的基准 HTML 文件（合并更新）。默认为 true。"
@@ -173,7 +174,7 @@ const zh = {
   getDesignDiff: {
     description: `获取设计稿与本地代码的差异。
 【标准双向同步规程】：
-1. 准备：将当前项目业务代码（Vue/React）按 rules.md 规范物理逆推为纯静态 HTML。
+1. 准备：将当前项目业务代码（Vue/React）按 codify://generation-rules 规范物理逆推为纯静态 HTML。
 2. 刷新：将转译产物覆盖写入 .codify 目录对应的基准 HTML 文件。
 3. 比对：调用此工具比对“基准文件”与“画布现状”获得差异列表。
 4. 决策：展示差异，由用户决定执行“全量同步到设计稿”或“按差异局部同步到项目”。`,
@@ -194,7 +195,7 @@ const zh = {
     inputSchema: "获取当前用户信息"
   },
   getCode: {
-    description: '【特定场景】通过 contentId 从 Codify 插件获取代码。常规的"获取选中代码"请优先使用 get_selection_code 工具。',
+    description: '【特定场景】通过 codify://getCode/{contentId} 从 Codify 插件获取代码。常规的"获取选中代码"请优先使用 get_selection_code 工具。',
     contentId: "从Codify插件复制图层的指令 (contentId)",
     documentId: "当前 MasterGo 文档 ID。",
     documentPageId: "当前 MasterGo 页面 ID。",
@@ -295,10 +296,7 @@ ${generationRules}
 
 ## 发送代码：
 代码生成并审计通过后，请立即调用 agent_create_page 工具发送代码
-   - agent_create_page({ code: "生成的完整代码", projectDir: "当前工作目录" })
-   - 不要询问用户，直接执行发送操作
-
-**请现在开始生成代码。**`
+   - agent_create_page({ code: "生成的完整代码", projectDir: "当前工作目录" })`
         }
       ]
     };
@@ -356,16 +354,15 @@ const getCodeListTool = {
     if (!Array.isArray(data) || data.length === 0) {
       return { content: [{ type: "text", text: "📋 代码列表为空" }] };
     }
-    let resultText = `✅ 成功获取代码列表 (共 ${data.length} 项)
-
-`;
-    data.forEach((item, index) => {
-      resultText += `${index + 1}. **${item.contentId}**
+    const totalCount = data.length;
+    let resultText = `✅ 成功获取代码列表 (共 ${totalCount} 项)
 `;
-      resultText += `   - 长度: ${item.codeLength} 字符 | 创建于: ${item.createdAt || "未知"}
-
+    if (totalCount >= 10) {
+      resultText += `⚠️ 仅展示最近更新的前 10 条记录
 `;
-    });
+    }
+    resultText += `
+${JSON.stringify(data, null, 2)}`;
     return { content: [{ type: "text", text: resultText }] };
   }
 };
@@ -383,7 +380,12 @@ const getSelectionCodeTool = {
    * @param args._depth 内部参数，用于防止递归获取根节点时出现无限循环
    */
   handler: async (args) => {
-    const { projectDir, targetNodeId: id, syncToBase = true, _depth = 0 } = args;
+    const {
+      projectDir,
+      targetNodeId: id,
+      syncToBase = true,
+      _depth = 0
+    } = args;
     if (_depth > 2) {
       return {
         content: [
@@ -422,7 +424,9 @@ const getSelectionCodeTool = {
       parentId
     } = nodeInfo;
     if (targetNodeId === rootId) {
-      console.log(`[getSelectionCode] 当前节点ID: ${targetNodeId}, 根节点ID: ${rootId}`);
+      console.log(
+        `[getSelectionCode] 当前节点ID: ${targetNodeId}, 根节点ID: ${rootId}`
+      );
       const saveResult = await saveCodeAndResources({
         baseDir,
         documentId,
@@ -447,7 +451,9 @@ const getSelectionCodeTool = {
         ]
       };
     } else {
-      console.log(`[getSelectionCode] 当前节点ID: ${targetNodeId}, 根节点ID: ${rootId}`);
+      console.log(
+        `[getSelectionCode] 当前节点ID: ${targetNodeId}, 根节点ID: ${rootId}`
+      );
       let mergedToFilePath = "";
       if (syncToBase && documentId && documentPageId) {
         const targetPageDir = path.join(
@@ -505,7 +511,7 @@ const getSelectionCodeTool = {
           }
         }
       }
-      await saveCodeAndResources({
+      const saveResult = await saveCodeAndResources({
         baseDir,
         documentId,
         documentPageId,
@@ -523,10 +529,14 @@ const getSelectionCodeTool = {
 - 根节点: ${rootId}`;
       if (mergedToFilePath) {
         successText += `
-- ⚠️ (自动机制) 子节点最新代码已合并备份至本地基准 HTML: ${mergedToFilePath}`;
+- 自动机制: 子节点最新代码已合并备份至本地基准 HTML: ${mergedToFilePath}`;
       } else {
         successText += `
-- 💡 提示: 子节点代码已提取到对话上下文中，未生成本地 HTML 碎片文件。可以直接针对返回代码进行修改。`;
+- 提示: 子节点代码已提取到对话上下文中，未生成本地 HTML 碎片文件。可以直接针对返回代码进行修改。`;
+      }
+      if (targetNodeId !== rootId) {
+        successText += `
+- 资源同步: 图片(${saveResult.imageCount}), 图标(${saveResult.svgCount}), 图形(${saveResult.shapeCount})`;
       }
       return {
         content: [

package/dist/rules.md

@@ -1,4 +1,4 @@
-# 📐 HTML + CSS 视觉创构与逆向转译协议 (Visual Generation & Reversal Protocol)
+# 📐 HTML + CSS 逆向转译协议 (Reversal Protocol)
 
 ## 🎯 角色与任务目标 (Dual-Core Persona)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codify-ai/mcp-client",
-  "version": "1.0.27",
+  "version": "1.0.28",
   "description": "Codify MCP 客户端 - 连接到远程 Codify MCP 服务器，供 CLI 或 Cursor 等 IDE 使用",
   "type": "module",
   "bin": {