Cursor 配置 Figma Command MCP 时插件无法识别 Figma API？

Question

在 Cursor 中配置 Figma Command MCP 插件时，常见问题为插件无法识别或调用 Figma API（如 `figma.currentPage`、`figma.ui` 等），表现为运行时抛出 `ReferenceError: figma is not defined` 或 `Cannot read properties of undefined`。根本原因在于：MCP（Model Control Protocol）插件默认运行于 Node.js 沙箱环境，而 Figma API 仅在 Figma 插件主上下文（plugin context）中可用，需通过 `figma.showUI()` 加载的 HTML/TS 前端脚本执行；Cursor 的 MCP 集成目前不自动注入 Figma 运行时上下文，也未桥接 `figma` 全局对象。此外，若未在 `manifest.json` 中正确声明 `permissions: ["figma"]` 或 `api: ["figma"]`，或未启用开发者模式与本地插件调试，也会导致 API 不可见。该问题非代码错误，而是环境隔离与协议兼容性缺失所致，需结合 Figma CLI 开发流程与 MCP 的 bridge 机制进行手动适配。

Answer 1

一、现象层：典型错误表现与日志特征

• ReferenceError: figma is not defined —— 在 Cursor 的 MCP 插件脚本中直接调用 figma.currentPage 时立即崩溃；
• TypeError: Cannot read properties of undefined (reading 'ui') —— 即使引入了 @figma/plugin-typings，TS 编译通过但运行时仍失败；
• Cursor 控制台显示 MCP server started，但 Figma 桌面客户端无任何插件响应或 UI 弹出；
• Figma 开发者控制台（Cmd/Ctrl+Shift+I → Console）中无 figma 全局对象注入痕迹；
• 本地调试时 figma show 命令成功，但 Cursor 触发的 MCP action 未触发 figma.showUI() 调用。

二、环境层：运行时隔离模型与协议边界

理解问题本质需厘清三层执行域：

执行环境	JS 运行时	可访问 API	是否支持 figma.*
Cursor MCP 插件主进程	Node.js v18+（V8 沙箱）	fs, path, child_process, MCP SDK	❌ 完全不可见
Figma 插件主上下文（plugin context）	Figma 自研 JS 引擎（基于 V8 扩展）	figma.currentPage, figma.clientStorage, figma.notify	✅ 原生可用
Figma UI 上下文（HTML iframe）	标准浏览器渲染引擎（Chromium）	window, document, figma.ui（仅限 postMessage 通信）	⚠️ 仅通过 parent.figma（受限）或 postMessage 桥接

三、配置层：Manifest 与权限链路校验

以下为 manifest.json 必须满足的最小合规项（Figma CLI v4.0+）：

{
  "name": "Cursor-Figma MCP Bridge",
  "id": "com.example.cursor-figma-mcp",
  "api": ["figma"],
  "permissions": ["figma"],
  "main": "code/plugin.ts",
  "ui": "ui.html",
  "capabilities": ["api"]
}

⚠️ 注意："api" 字段在 v3.x 中为 "required-api"；若缺失 "capabilities": ["api"]，Figma 将拒绝加载插件上下文，导致 figma 对象永不挂载。

四、架构层：MCP ↔ Figma 的双向桥接机制

由于 Cursor 的 MCP Server 不具备 Figma 运行时，必须构建显式桥接通道。推荐采用「双进程信令 + IPC 回调」模式：

graph LR A[Cursor MCP Plugin] -->|MCP Action Call| B(MCP Server Node Process) B -->|spawn() + stdio| C[Figma CLI Plugin Host] C -->|figma.showUI()| D[UI iframe] D -->|postMessage| E[Figma Plugin Context] E -->|figma.currentPage.getSelection()| F[Data] F -->|postMessage| D D -->|window.parent.postMessage| B B -->|MCP Response| A

五、实现层：最小可行桥接代码模板

在 code/plugin.ts 中启用 Figma CLI 监听：

import { serve } from '@cursor/mcp-server';
import { exec } from 'child_process';

// 启动 Figma CLI 插件宿主（非阻塞）
exec('npx @figma/cli plugin run --dev', (err) => {
  if (err) console.error('Figma CLI host failed:', err);
});

// MCP action 注册：触发 Figma 上下文操作
serve({
  tools: [{
    name: 'get-current-page-name',
    description: 'Fetch current Figma page name via bridge',
    inputSchema: { type: 'object', properties: {} },
    execute: async () => {
      return new Promise((resolve) => {
        // 通过 IPC 或文件监听接收来自 Figma 插件的响应
        const responseFile = '/tmp/figma-bridge-response.json';
        const interval = setInterval(() => {
          try {
            const data = require(responseFile);
            resolve({ name: data.pageName });
            clearInterval(interval);
          } catch (e) { /* ignore */ }
        }, 300);
      });
    }
  }]
});

六、调试层：验证路径与可观测性检查清单

1. ✅ 运行 figma dev 并确认右上角出现「Developer Mode」徽章；
2. ✅ 在 Figma 文件中执行 Plugins → Development → Your Plugin，验证 UI 是否弹出；
3. ✅ 打开 Figma DevTools → Console，输入 figma 应返回对象；
4. ✅ 检查 figma show 输出中是否含 Plugin context loaded；
5. ✅ 使用 curl -X POST http://localhost:5000/mcp/action/get-current-page-name 测试 MCP 端点连通性；
6. ✅ 查看 ~/.figma/plugins/your-plugin-id/logs/ 下 runtime 日志是否有 postMessage received。