@jacob-z/zz-ui-brigde-mcp 1.0.0

package/README.md

@@ -0,0 +1,119 @@
+# @zz-mcp/ui-diff-mcp
+
+AI 驱动的 MasterGo 设计稿节点查询 MCP 服务。将 MasterGo 插件中的节点数据通过 MCP protocol 暴露给 Claude Code 等 AI 工具。
+
+## 功能
+
+- **实时选中快照**：MasterGo 中选中任意节点，AI 可立即获取其属性
+- **按需节点查询**：通过 nodeId 精确查询任意节点的详细信息
+- **双通道通信**：MCP stdio 通道 + HTTP 本地服务（port 18765）
+
+## 可用函数
+
+### `get_selected_node`
+
+获取 MasterGo 当前选中节点的属性快照。无需等待，直接返回缓存数据。
+
+**参数**：无
+
+**返回值示例**：
+
+```json
+{
+  "selected": {
+    "id": "11:809",
+    "name": "容器 1117",
+    "type": "FRAME",
+    "x": 488,
+    "y": 24,
+    "width": 236,
+    "height": 232,
+    "fills": [{ "type": "SOLID", "color": { "r": 0.91, "g": 0.79, "b": 0.79, "a": 1 } }],
+    "opacity": 1,
+    "childrenIds": ["11:0010", "11:0019", "11:0028", "11:0037"]
+  },
+  "freshAt": 1778263424580
+}
+```
+
+### `get_node_by_id`
+
+按 nodeId 精确查询 MasterGo 节点属性。同步阻塞等待插件响应，超时 25 秒。
+
+**参数**：
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| nodeId | string | 是 | MasterGo 节点 ID |
+
+**返回值**：节点属性 JSON，包含 id、name、type、x、y、width、height、opacity、fills、fontSize、characters、fontName 等字段
+
+## MCP 配置
+
+### Claude Code
+
+在 `.claude/settings.json` 中添加：
+
+```json
+{
+  "mcpServers": {
+    "ui-diff-mcp": {
+      "command": "npx",
+      "args": ["-y", "@zz-mcp/ui-diff-mcp"]
+    }
+  }
+}
+```
+
+重启 Claude Code 后，在对话中执行 `/mcp` 确认状态为 `connected`。
+
+### 本地开发（源码运行）
+
+```bash
+# 进入包目录
+cd packages/ui-diff-mcp
+
+# 源码运行（需 tsx）
+pnpm mcp:server
+
+# 或构建后运行
+pnpm build
+node dist/index.js
+```
+
+## 架构
+
+```
+Claude Code (MCP Client)
+    |
+    | stdio protocol
+    v
+MCP Server (@zz-mcp/ui-diff-mcp)
+    |
+    | HTTP localhost:18765
+    v
+UI iframe (mcp-bridge.ts)
+    |
+    | postMessage
+    v
+MasterGo Sandbox (lib/main.ts)
+    |
+    v
+MasterGo Plugin API (mg.*)
+```
+
+## 配套插件
+
+本 MCP 服务需要配合 MasterGo 插件使用。插件负责：
+
+- 监听选择变化，推送节点快照
+- 响应 `GET_NODE_INFO` 消息，查询指定节点
+
+插件发布地址：MasterGo 插件广场（待补充）
+
+## 环境要求
+
+- Node.js >= 18.0.0
+
+## 版本
+
+当前版本：1.0.0

package/dist/index.js

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+import * as http from "node:http";
+import { v4 } from "uuid";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+const PENDING_TTL_MS = 3e4;
+class PendingRequestManager {
+  pending = /* @__PURE__ */ new Map();
+  queue = [];
+  create(nodeId, fields) {
+    return new Promise((resolve, reject) => {
+      const requestId = v4();
+      const timeoutHandle = setTimeout(() => {
+        this.reject(requestId, new Error("Timeout: plugin did not respond within 30s"));
+      }, PENDING_TTL_MS);
+      this.pending.set(requestId, { requestId, nodeId, fields, resolve, reject, timeoutHandle });
+      this.queue.push(requestId);
+    });
+  }
+  resolve(requestId, data) {
+    const req = this.pending.get(requestId);
+    if (!req)
+      return;
+    clearTimeout(req.timeoutHandle);
+    this.pending.delete(requestId);
+    this.removeFromQueue(requestId);
+    req.resolve(data);
+  }
+  reject(requestId, reason) {
+    const req = this.pending.get(requestId);
+    if (!req)
+      return;
+    clearTimeout(req.timeoutHandle);
+    this.pending.delete(requestId);
+    this.removeFromQueue(requestId);
+    req.reject(reason);
+  }
+  getPending() {
+    const id = this.queue[0];
+    if (!id)
+      return void 0;
+    const req = this.pending.get(id);
+    if (!req)
+      return void 0;
+    return { requestId: req.requestId, nodeId: req.nodeId, fields: req.fields };
+  }
+  removeFromQueue(requestId) {
+    const idx = this.queue.indexOf(requestId);
+    if (idx !== -1)
+      this.queue.splice(idx, 1);
+  }
+}
+const pendingRequests = new PendingRequestManager();
+class SelectionCacheManager {
+  snapshot = { selected: null, reason: "no_plugin_connected" };
+  lastSeq = -1;
+  update(data, seq) {
+    if (seq <= this.lastSeq)
+      return;
+    this.lastSeq = seq;
+    if (data === null) {
+      this.snapshot = { selected: null, reason: "no_selection", freshAt: Date.now() };
+    } else {
+      this.snapshot = { selected: data, freshAt: Date.now() };
+    }
+  }
+  get() {
+    return this.snapshot;
+  }
+}
+const selectionCache = new SelectionCacheManager();
+const PORT = 18765;
+const LONG_POLL_TIMEOUT_MS = 25e3;
+const CORS_HEADERS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+  "Access-Control-Allow-Headers": "Content-Type",
+  "Access-Control-Allow-Private-Network": "true"
+};
+function setCorsHeaders(res) {
+  for (const [key, value] of Object.entries(CORS_HEADERS)) {
+    res.setHeader(key, value);
+  }
+}
+function readBody(req) {
+  return new Promise((resolve) => {
+    let body = "";
+    req.on("data", (chunk) => {
+      body += chunk.toString();
+    });
+    req.on("end", () => resolve(body));
+  });
+}
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+function isNodeOrError(val) {
+  if (typeof val !== "object" || val === null)
+    return false;
+  const obj = val;
+  if (typeof obj.error === "string" && typeof obj.nodeId === "string")
+    return true;
+  return typeof obj.id === "string";
+}
+function isNodeQueryResponse(val) {
+  if (typeof val !== "object" || val === null)
+    return false;
+  const obj = val;
+  return typeof obj.requestId === "string" && isNodeOrError(obj.data);
+}
+function isSelectionBody(val) {
+  if (typeof val !== "object" || val === null)
+    return false;
+  const obj = val;
+  return typeof obj.seq === "number" && "data" in obj;
+}
+async function handleRequest(req, res) {
+  setCorsHeaders(res);
+  if (req.method === "OPTIONS") {
+    res.writeHead(200);
+    res.end();
+    return;
+  }
+  const url = req.url ?? "/";
+  if (url === "/health" && req.method === "GET") {
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ status: "ok", pid: process.pid }));
+    return;
+  }
+  if (url === "/selection" && req.method === "POST") {
+    const raw = await readBody(req);
+    const body = parseJson(raw);
+    if (isSelectionBody(body)) {
+      selectionCache.update(body.data, body.seq);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true }));
+    } else {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "invalid body" }));
+    }
+    return;
+  }
+  if (url === "/pending-requests" && req.method === "GET") {
+    const pending = pendingRequests.getPending();
+    if (pending) {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(pending));
+      return;
+    }
+    let resolved = false;
+    const timer = setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        res.writeHead(204);
+        res.end();
+      }
+    }, LONG_POLL_TIMEOUT_MS);
+    const poll = setInterval(() => {
+      if (resolved) {
+        clearInterval(poll);
+        return;
+      }
+      const p = pendingRequests.getPending();
+      if (p) {
+        resolved = true;
+        clearInterval(poll);
+        clearTimeout(timer);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(p));
+      }
+    }, 200);
+    req.on("close", () => {
+      if (!resolved) {
+        resolved = true;
+        clearInterval(poll);
+        clearTimeout(timer);
+      }
+    });
+    return;
+  }
+  if (url === "/node-result" && req.method === "POST") {
+    const raw = await readBody(req);
+    const body = parseJson(raw);
+    if (isNodeQueryResponse(body)) {
+      pendingRequests.resolve(body.requestId, body.data);
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true }));
+    } else {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "invalid body" }));
+    }
+    return;
+  }
+  res.writeHead(404, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ error: "not found" }));
+}
+function killStaleServer() {
+  return new Promise((resolve) => {
+    const req = http.get(`http://localhost:${PORT}/health`, (res) => {
+      let body = "";
+      res.on("data", (c) => {
+        body += c.toString();
+      });
+      res.on("end", () => {
+        try {
+          const parsed = JSON.parse(body);
+          if (typeof parsed.pid === "number" && parsed.pid !== process.pid) {
+            console.error(`[ai-tools] Killing stale server process (pid=${parsed.pid})`);
+            try {
+              process.kill(parsed.pid, "SIGTERM");
+            } catch {
+            }
+          }
+        } catch {
+        }
+        setTimeout(resolve, 500);
+      });
+    });
+    req.on("error", () => setTimeout(resolve, 200));
+  });
+}
+function createHttpServer(resolve, reject, retries = 2) {
+  const server = http.createServer((req, res) => {
+    handleRequest(req, res).catch((err) => {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error("[ai-tools] Request handler error:", msg);
+      if (!res.headersSent) {
+        res.writeHead(500);
+        res.end();
+      }
+    });
+  });
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE" && retries > 0) {
+      killStaleServer().then(() => createHttpServer(resolve, reject, retries - 1));
+    } else {
+      reject(err);
+    }
+  });
+  server.listen(PORT, () => {
+    console.error(`[ai-tools] HTTP server listening on port ${PORT}`);
+    resolve();
+  });
+}
+function startHttpServer() {
+  return new Promise((resolve, reject) => {
+    createHttpServer(resolve, reject);
+  });
+}
+const BASE_FIELDS = /* @__PURE__ */ new Set(["id", "name", "type", "childrenIds"]);
+function filterFields(data, fields) {
+  if (!fields || fields.length === 0)
+    return data;
+  const result = {};
+  const fieldSet = /* @__PURE__ */ new Set([...BASE_FIELDS, ...fields]);
+  for (const [key, value] of Object.entries(data)) {
+    if (fieldSet.has(key))
+      result[key] = value;
+  }
+  return result;
+}
+async function startMcpServer() {
+  const server = new Server(
+    { name: "ui-differ-ai-tools", version: "0.2.0" },
+    { capabilities: { tools: {} } }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "get_selected_node",
+        description: "获取 MasterGo 当前选中节点的属性（快照语义，无需 round-trip）",
+        inputSchema: {
+          type: "object",
+          properties: {
+            fields: {
+              type: "array",
+              items: { type: "string" },
+              description: "要获取的字段名列表。不传则返回全部字段。常用场景见 skill 指导。始终包含基础字段：id, name, type, childrenIds。"
+            }
+          }
+        }
+      },
+      {
+        name: "get_node_by_id",
+        description: "按 nodeId 从 MasterGo 插件查询节点属性（同步阻塞，等待插件响应）",
+        inputSchema: {
+          type: "object",
+          properties: {
+            nodeId: {
+              type: "string",
+              description: "MasterGo 节点 ID"
+            },
+            fields: {
+              type: "array",
+              items: { type: "string" },
+              description: "要获取的字段名列表。不传则返回全部字段。常用场景见 skill 指导。始终包含基础字段：id, name, type, childrenIds。"
+            }
+          },
+          required: ["nodeId"]
+        }
+      }
+    ]
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const rawFields = args ? args.fields : void 0;
+    const fields = Array.isArray(rawFields) ? rawFields : void 0;
+    if (name === "get_selected_node") {
+      const snapshot = selectionCache.get();
+      const selected = snapshot.selected;
+      const filtered = selected ? { ...snapshot, selected: filterFields(selected, fields) } : snapshot;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(filtered, null, 2)
+          }
+        ]
+      };
+    }
+    if (name === "get_node_by_id") {
+      if (!args || typeof args.nodeId !== "string") {
+        throw new McpError(ErrorCode.InvalidParams, "nodeId is required and must be a string");
+      }
+      const nodeId = args.nodeId;
+      try {
+        const result = await pendingRequests.create(nodeId, fields);
+        const filtered = filterFields(result, fields);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(filtered, null, 2)
+            }
+          ]
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new McpError(ErrorCode.InternalError, msg);
+      }
+    }
+    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+  });
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[ai-tools] MCP server connected via stdio");
+}
+async function main() {
+  await startHttpServer();
+  await startMcpServer();
+}
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error("[ai-tools] Fatal error:", msg);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@jacob-z/zz-ui-brigde-mcp",
+  "type": "module",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "bin": {
+    "zz-ui-brigde-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "prepublishOnly": "pnpm build",
+    "mcp:server": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.0",
+    "uuid": "^11.1.0"
+  },
+  "devDependencies": {
+    "vite": "^6.4.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}