@autobest-ui/agent 1.0.0 → 1.0.1

package/mcp/figma-mcp-bridge/src/tools/nodes.js

@@ -0,0 +1,78 @@
+/**
+ * figma_get_nodes tool
+ * Returns detailed information about specific nodes by their IDs
+ */
+
+export const nodesTool = {
+  name: 'figma_get_nodes',
+  description: 'Get detailed information about specific Figma nodes by their IDs. Returns node properties including type, position, size, fills, strokes, auto-layout (including layoutWrap and counterAxisSpacing), clipsContent, node-level boundVariables, explicitVariableModes, and more.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      nodeIds: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Array of Figma node IDs (e.g., ["1:23", "4:56"])'
+      }
+    },
+    required: ['nodeIds']
+  }
+};
+
+export async function handleGetNodes(bridge, args) {
+  if (!bridge.isConnected()) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: {
+            code: 'NOT_CONNECTED',
+            message: 'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
+          }
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+
+  const { nodeIds, depth } = args;
+
+  if (!nodeIds || !Array.isArray(nodeIds) || nodeIds.length === 0) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: {
+            code: 'INVALID_PARAMS',
+            message: 'nodeIds must be a non-empty array of node IDs'
+          }
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+
+  try {
+    const result = await bridge.sendCommand('get_nodes', { nodeIds, depth });
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  } catch (error) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: {
+            code: error.code || 'UNKNOWN_ERROR',
+            message: error.message
+          }
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+}

package/mcp/figma-mcp-bridge/src/tools/pages.js

@@ -0,0 +1,55 @@
+/**
+ * figma_list_pages tool
+ * Returns all pages in the current Figma document
+ */
+
+export const pagesTool = {
+  name: 'figma_list_pages',
+  description: 'List all pages in the current Figma document. Returns page IDs, names, and indicates which page is currently active.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: []
+  }
+};
+
+export async function handleListPages(bridge) {
+  if (!bridge.isConnected()) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: {
+            code: 'NOT_CONNECTED',
+            message: 'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
+          }
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+
+  try {
+    const result = await bridge.sendCommand('list_pages', {});
+
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify(result, null, 2)
+      }]
+    };
+  } catch (error) {
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: {
+            code: error.code || 'UNKNOWN_ERROR',
+            message: error.message
+          }
+        }, null, 2)
+      }],
+      isError: true
+    };
+  }
+}

package/mcp/figma-mcp-bridge/src/websocket.js

@@ -0,0 +1,255 @@
+import { EventEmitter } from 'events';
+import { WebSocketServer } from 'ws';
+
+const DEFAULT_PORT = 3055;
+const REQUEST_TIMEOUT = 30000; // 30 seconds
+const HEARTBEAT_INTERVAL = 30000; // 30 seconds
+
+export class FigmaBridge extends EventEmitter {
+  constructor(port = DEFAULT_PORT) {
+    super();
+    this.port = port;
+    this.wss = null;
+    this.connection = null;
+    this.connectionState = 'disconnected';
+    this.documentInfo = null;
+    this.pendingRequests = new Map();
+    this.requestIdCounter = 0;
+    this.heartbeatInterval = null;
+  }
+
+  async start() {
+    const maxPort = DEFAULT_PORT + 15;
+
+    const tryPort = port => {
+      return new Promise((resolve, reject) => {
+        const wss = new WebSocketServer({ port });
+
+        wss.on('listening', () => {
+          // eslint-disable-next-line no-console
+          console.error(`[FigmaBridge] WebSocket server listening on port ${port}`);
+          this.wss = wss;
+          this.port = port;
+          resolve();
+        });
+
+        wss.on('error', error => {
+          if (error.code === 'EADDRINUSE') {
+            // eslint-disable-next-line no-console
+            console.error(`[FigmaBridge] Port ${port} in use, trying ${port + 1}`);
+            wss.close();
+            if (port < maxPort) {
+              tryPort(port + 1).then(resolve, reject);
+            } else {
+              reject(new Error(`Could not find available port (tried ${DEFAULT_PORT}-${maxPort})`));
+            }
+          } else {
+            reject(error);
+          }
+        });
+
+        wss.on('connection', ws => this._handleConnection(ws));
+      });
+    };
+
+    return tryPort(this.port);
+  }
+
+  _handleConnection(ws) {
+    // eslint-disable-next-line no-console
+    console.error('[FigmaBridge] Plugin connected');
+
+    // Replace existing connection if any
+    if (this.connection) {
+      // eslint-disable-next-line no-console
+      console.error('[FigmaBridge] Replacing existing connection');
+      this.connection.close(1000, 'New connection');
+    }
+
+    this.connection = ws;
+    this.connectionState = 'connecting';
+
+    ws.on('message', data => this._handleMessage(data));
+    ws.on('close', () => this._handleClose());
+    ws.on('error', error => this._handleError(error));
+  }
+
+  _handleMessage(data) {
+    let message;
+    try {
+      message = JSON.parse(data.toString());
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error('[FigmaBridge] Failed to parse message:', error);
+      return;
+    }
+
+    // Handle handshake from plugin
+    if (message.type === 'handshake') {
+      this.documentInfo = message.payload;
+      this.connectionState = 'connected';
+      // eslint-disable-next-line no-console
+      console.error(`[FigmaBridge] Handshake complete: ${message.payload.fileName}`);
+
+      // Send handshake acknowledgment
+      this.connection.send(
+        JSON.stringify({
+          type: 'handshake_ack',
+          payload: {
+            serverVersion: '0.1.0',
+            sessionId: `sess_${Date.now()}`
+          }
+        })
+      );
+
+      this._startHeartbeat();
+      this.emit('connected', this.documentInfo);
+      return;
+    }
+
+    // Handle pong (heartbeat response)
+    if (message.type === 'pong') {
+      return;
+    }
+
+    // Handle command response
+    if (message.responseTo) {
+      const pending = this.pendingRequests.get(message.responseTo);
+      if (pending) {
+        this.pendingRequests.delete(message.responseTo);
+        clearTimeout(pending.timeout);
+
+        if (message.payload?.error) {
+          pending.reject(
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            new BridgeError(
+              message.payload.error.code || 'UNKNOWN_ERROR',
+              message.payload.error.message || 'Unknown error',
+              message.payload.error.details
+            )
+          );
+        } else {
+          pending.resolve(message.payload);
+        }
+      }
+    }
+  }
+
+  _handleClose() {
+    // eslint-disable-next-line no-console
+    console.error('[FigmaBridge] Connection closed');
+    this.connectionState = 'disconnected';
+    this.connection = null;
+    this.documentInfo = null;
+    this._stopHeartbeat();
+
+    // Reject all pending requests
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    for (const [id, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeout);
+      // eslint-disable-next-line @typescript-eslint/no-use-before-define
+      pending.reject(new BridgeError('CONNECTION_CLOSED', 'Connection closed'));
+    }
+    this.pendingRequests.clear();
+
+    this.emit('disconnected');
+  }
+
+  _handleError(error) {
+    // eslint-disable-next-line no-console
+    console.error('[FigmaBridge] WebSocket error:', error.message);
+    this.emit('error', error);
+  }
+
+  _startHeartbeat() {
+    this._stopHeartbeat();
+    this.heartbeatInterval = setInterval(() => {
+      if (this.connection && this.connectionState === 'connected') {
+        this.connection.send(
+          JSON.stringify({
+            type: 'ping',
+            timestamp: Date.now()
+          })
+        );
+      }
+    }, HEARTBEAT_INTERVAL);
+  }
+
+  _stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+
+  /**
+   * Send a command to the Figma plugin and wait for response
+   * @param {string} command - Command name
+   * @param {object} payload - Command payload
+   * @returns {Promise<object>} Response payload
+   */
+  async sendCommand(command, payload = {}) {
+    if (this.connectionState !== 'connected') {
+      // eslint-disable-next-line @typescript-eslint/no-use-before-define
+      throw new BridgeError(
+        'NOT_CONNECTED',
+        'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
+      );
+    }
+
+    const requestId = `req_${++this.requestIdCounter}`;
+
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        this.pendingRequests.delete(requestId);
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        reject(new BridgeError('TIMEOUT', `Command "${command}" timed out after ${REQUEST_TIMEOUT}ms`));
+      }, REQUEST_TIMEOUT);
+
+      this.pendingRequests.set(requestId, { resolve, reject, timeout });
+
+      this.connection.send(
+        JSON.stringify({
+          requestId,
+          command,
+          payload
+        })
+      );
+    });
+  }
+
+  isConnected() {
+    return this.connectionState === 'connected';
+  }
+
+  getDocumentInfo() {
+    return this.documentInfo;
+  }
+
+  async stop() {
+    this._stopHeartbeat();
+
+    if (this.connection) {
+      this.connection.close(1000, 'Server shutdown');
+    }
+
+    if (this.wss) {
+      return new Promise(resolve => {
+        this.wss.close(() => {
+          // eslint-disable-next-line no-console
+          console.error('[FigmaBridge] WebSocket server stopped');
+          resolve();
+        });
+      });
+    }
+  }
+}
+
+export class BridgeError extends Error {
+  constructor(code, message, details = null) {
+    super(message);
+    this.name = 'BridgeError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/mcp/rag-mcp-bridge/README.md

@@ -4,30 +4,42 @@
 
 ## 启动
 
-先启动 PRD Knowledge HTTP API，并在 Codex 的 `config.toml` 中加入 [config.toml.example](config.toml.example) 的配置。Codex 将通过 npm 安装并启动发布包中的 MCP：
+先启动 PRD Knowledge HTTP API。直接在终端验证时，必须在同一条命令中提供 API 根地址：
 
 ```bash
-npx --yes --package=@autobest-ui/agent@latest autobest-rag-mcp
+RAG_API_BASE_URL="http://127.0.0.1:3000/api/knowledge" \
+npx --yes \
+  --package=@autobest-ui/agent@latest \
+  autobest-rag-mcp
 ```
 
-`@latest` 可以替换为明确版本，例如 `@1.0.0`。STDIO 用于 MCP 协议通信，服务不会向标准输出写日志。
+`@latest` 可以替换为明确版本，例如 `@1.0.0`。启动成功后，服务会通过 stdio 持续等待 MCP 客户端请求，并且不会向标准输出写日志；终端看起来没有响应属于正常状态，可按 `Ctrl+C` 停止。
 
-## 环境变量
-
-| 变量 | 默认值 | 说明 |
-| --- | --- | --- |
-| `RAG_API_BASE_URL` | 无，必填 | PRD Knowledge HTTP API 根地址，必须通过 `config.toml` 的 `[mcp_servers.rag-mcp-bridge.env]` 配置 |
-| `RAG_MCP_HTTP_TIMEOUT_MS` | `120000` | 单次 HTTP 请求超时，单位为毫秒 |
-
-示例：
+供 Codex 长期使用时，将下面的完整配置加入 `~/.codex/config.toml`，然后重启 Codex：
 
 ```toml
+[mcp_servers.rag-mcp-bridge]
+command = "npx"
+args = ["--yes", "--package=@autobest-ui/agent@latest", "autobest-rag-mcp"]
+startup_timeout_sec = 30
+tool_timeout_sec = 120
+enabled = true
+
 [mcp_servers.rag-mcp-bridge.env]
 RAG_API_BASE_URL = "http://127.0.0.1:3000/api/knowledge"
 RAG_MCP_HTTP_TIMEOUT_MS = "120000"
 ```
 
-`RAG_API_BASE_URL` 仅在 MCP 客户端配置中提供，服务代码不包含默认 API 地址。完整配置见 [config.toml.example](config.toml.example)。
+完整配置文件也可直接参考 [config.toml.example](config.toml.example)。
+
+## 环境变量
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `RAG_API_BASE_URL` | 无，必填 | PRD Knowledge HTTP API 根地址，必须通过 `config.toml` 的 `[mcp_servers.rag-mcp-bridge.env]` 配置 |
+| `RAG_MCP_HTTP_TIMEOUT_MS` | `120000` | 单次 HTTP 请求超时，单位为毫秒 |
+
+`RAG_API_BASE_URL` 仅在 MCP 客户端配置中提供，服务代码不包含默认 API 地址。
 
 ## 工具
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobest-ui/agent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "description": "Autobest Agent skills/plugins/mcp assets + sync cli",
   "files": [
@@ -19,22 +19,27 @@
     "autobest-agent-sync": "./bin/sync-assets.mjs",
     "autobest-azurepr-mcp": "./mcp/azurepr-mcp-bridge/index.js",
     "autobest-delivery-setup": "./plugins/autobest-delivery/scripts/setup.mjs",
-    "autobest-rag-mcp": "./mcp/rag-mcp-bridge/index.js"
+    "autobest-rag-mcp": "./mcp/rag-mcp-bridge/index.js",
+    "figma-mcp-bridge": "./mcp/figma-mcp-bridge/src/index.js",
+    "figma-plugin": "./plugins/figma-plugin/scripts/setup.mjs"
   },
   "scripts": {
     "mcp:azurepr": "node ./mcp/azurepr-mcp-bridge/index.js",
+    "mcp:figma": "node ./mcp/figma-mcp-bridge/src/index.js",
     "mcp:rag": "node ./mcp/rag-mcp-bridge/index.js",
     "test": "npm run test:skills && npm run test:mcp && npm run test:plugin",
     "test:skills": "node --test ./bin/sync-assets.test.mjs",
     "test:mcp:azurepr": "node --test ./mcp/azurepr-mcp-bridge/index.test.js",
+    "test:mcp:figma": "node --test ./mcp/figma-mcp-bridge/index.test.js",
     "test:mcp:rag": "node --test ./mcp/rag-mcp-bridge/index.test.js",
-    "test:mcp": "npm run test:mcp:azurepr && npm run test:mcp:rag",
-    "test:plugin": "node --test ./plugins/autobest-delivery/scripts/setup.test.mjs"
+    "test:mcp": "npm run test:mcp:azurepr && npm run test:mcp:figma && npm run test:mcp:rag",
+    "test:plugin": "node --test ./plugins/autobest-delivery/scripts/setup.test.mjs ./plugins/figma-plugin/scripts/setup.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "diff": "9.0.0",
     "fs-extra": "11.3.0",
+    "ws": "8.18.3",
     "zod": "4.4.3"
   },
   "publishConfig": {

package/plugins/figma-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Magic Spells
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/figma-plugin/README.md

@@ -0,0 +1,25 @@
+# figma-plugin
+
+`figma-plugin` 是与 `figma-mcp-bridge` 配套的 Figma Development Plugin。它在 Figma 内运行，并通过本机 WebSocket 与 MCP 通信。
+
+## 安装
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-plugin
+```
+
+安装器会将插件文件同步到稳定目录：
+
+```text
+~/.autobest-agent/figma-plugins/figma-plugin
+```
+
+随后在 Figma 中执行 **Plugins -> Development -> Import plugin from manifest**，选择命令输出路径中的 `manifest.json`。再次执行安装命令会更新同一目录，无需重新导入。
+
+卸载本地文件：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-plugin uninstall
+```
+
+卸载后，Figma Development Plugins 列表中的记录需要在 Figma 内移除。