@autobest-ui/agent 1.0.0 → 1.0.1

package/README.md

@@ -20,30 +20,63 @@ npx --yes --package=@autobest-ui/agent@latest autobest-agent-sync react
 
 ## MCP
 
-安装 Node.js 20 或更高版本后，无需在业务项目中安装依赖，可以直接通过 `npx` 启动 MCP：
+安装 Node.js 20 或更高版本后，无需在业务项目中安装依赖。直接在终端验证 MCP 时，必须同时提供对应的环境变量。
+
+先启动 PRD Knowledge HTTP API，再验证 RAG MCP：
+
+```bash
+RAG_API_BASE_URL="http://127.0.0.1:3000/api/knowledge" \
+npx --yes \
+  --package=@autobest-ui/agent@latest \
+  autobest-rag-mcp
+```
+
+验证 Azure PR MCP：
 
 ```bash
-npx --yes --package=@autobest-ui/agent@latest autobest-rag-mcp
-npx --yes --package=@autobest-ui/agent@latest autobest-azurepr-mcp
+AZURE_DEVOPS_PAT="your-personal-access-token" \
+npx --yes \
+  --package=@autobest-ui/agent@latest \
+  autobest-azurepr-mcp
 ```
 
-同一个 npm 包暴露两个独立命令：
+启动成功后，MCP 会通过 stdio 持续等待客户端请求，终端没有输出属于正常状态，可按 `Ctrl+C` 停止。供 Codex 长期使用时，不要只执行上述临时命令，应将完整配置加入 `~/.codex/config.toml` 后重启 Codex。
+
+同一个 npm 包暴露三个独立命令：
 
 | 命令                   | 用途                           | 必需配置           |
 | ---------------------- | ------------------------------ | ------------------ |
 | `autobest-rag-mcp`     | 连接 PRD Knowledge RAG API     | `RAG_API_BASE_URL` |
 | `autobest-azurepr-mcp` | 读取 Azure DevOps Pull Request | `AZURE_DEVOPS_PAT` |
+| `figma-mcp-bridge`     | 连接本机 Figma Plugin          | 无                 |
 
 Codex 配置示例分别位于：
 
 - [RAG MCP 配置](mcp/rag-mcp-bridge/config.toml.example)
 - [Azure PR MCP 配置](mcp/azurepr-mcp-bridge/config.toml.example)
+- [Figma MCP 配置](mcp/figma-mcp-bridge/config.toml.example)
 
 生产环境可将 `@latest` 替换为明确版本，以固定 MCP 行为。
 
 如果 `@autobest-ui` 发布在私有 npm registry，使用前需要在 npm 的 `.npmrc` 中配置该 scope 对应的 registry 和认证信息。
 
-## Plugin
+## Figma Plugin
+
+Figma Plugin 与 `figma-mcp-bridge` 分目录维护，并通过同一个 npm 包提供两个独立命令。安装或更新到稳定目录：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-plugin
+```
+
+命令会输出 `manifest.json` 的稳定路径。首次安装后，在 Figma 中通过 **Plugins -> Development -> Import plugin from manifest** 导入该文件。详细说明见 [Figma Plugin 使用说明](plugins/figma-plugin/README.md)。
+
+卸载本地文件：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-plugin uninstall
+```
+
+## Codex Plugin
 
 Autobest Delivery 将交付闭环 Skills 和隔离的 Playwright MCP 运行器作为一个 Codex Plugin 安装。需要 Node.js 20 或更高版本，以及支持 `codex plugin` 命令的 Codex CLI。
 
@@ -126,7 +159,7 @@ Common Skills 会写入 `~/.agents/skills`，React Skills 会写入目标项目
 RAG MCP：
 
 ```bash
-RAG_API_BASE_URL=http://127.0.0.1:3000 \
+RAG_API_BASE_URL="http://127.0.0.1:3000/api/knowledge" \
 npx --yes \
   --package="$AGENT_TARBALL_PATH" \
   autobest-rag-mcp
@@ -141,6 +174,22 @@ npx --yes \
   autobest-azurepr-mcp
 ```
 
+Figma MCP：
+
+```bash
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  figma-mcp-bridge
+```
+
+Figma Plugin：
+
+```bash
+npx --yes \
+  --package="$AGENT_TARBALL_PATH" \
+  figma-plugin
+```
+
 MCP 使用 stdio 协议，启动后持续等待客户端请求属于正常行为，可按 `Ctrl+C` 停止。
 
 ### 5. 在 Codex 中联调 MCP
@@ -157,7 +206,7 @@ args = [
 ]
 
 [mcp_servers.rag-mcp-bridge.env]
-RAG_API_BASE_URL = "http://127.0.0.1:3000"
+RAG_API_BASE_URL = "http://127.0.0.1:3000/api/knowledge"
 
 [mcp_servers.azurepr-mcp-bridge]
 command = "npx"
@@ -167,11 +216,21 @@ args = [
   "autobest-azurepr-mcp"
 ]
 
-[mcp_servers.azurepr-mcp-bridge.env]
-AZURE_DEVOPS_PAT = "your-token"
+env_vars = ["AZURE_DEVOPS_PAT"]
+
+[mcp_servers.figma-mcp-bridge]
+command = "npx"
+args = [
+  "--yes",
+  "--package=/absolute/path/to/autobest-ui-agent-x.y.z.tgz",
+  "figma-mcp-bridge"
+]
+startup_timeout_sec = 30
+tool_timeout_sec = 120
+enabled = true
 ```
 
-修改 `config.toml` 后重启 Codex，再从新会话调用对应 MCP 工具。重新打包后如果 tarball 文件名或路径发生变化，需要同步更新 `config.toml`。
+配置 Azure PR MCP 前，还需要在启动 Codex 的环境中设置 `AZURE_DEVOPS_PAT`。修改 `config.toml` 后重启 Codex，再从新会话调用对应 MCP 工具。重新打包后如果 tarball 文件名或路径发生变化，需要同步更新 `config.toml`。
 
 ## 本地验证
 

package/mcp/figma-mcp-bridge/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/mcp/figma-mcp-bridge/README.md

@@ -0,0 +1,25 @@
+# figma-mcp-bridge
+
+`figma-mcp-bridge` 是本地 STDIO MCP 服务。它在 Codex 与 Figma Plugin 之间建立 WebSocket 桥接，使 Agent 可以读取和修改当前打开的 Figma Design 或 FigJam 文档。
+
+## 安装与配置
+
+先安装 Figma Plugin：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-plugin
+```
+
+然后将 [config.toml.example](config.toml.example) 中的配置加入 `~/.codex/config.toml`，重启 Codex。Codex 会通过 npm 安装并启动 MCP：
+
+```bash
+npx --yes --package=@autobest-ui/agent@latest figma-mcp-bridge
+```
+
+MCP 使用 stdio 通信，启动后持续等待客户端请求属于正常状态。WebSocket 默认从 `3055` 端口开始；如果端口已被占用，会依次尝试到 `3070`。
+
+## 连接 Figma
+
+在 Figma 中通过 **Plugins -> Development -> Import plugin from manifest** 导入安装器输出的 `manifest.json`。打开目标文件并运行插件，将插件显示的端口设置为 MCP 实际监听端口。状态显示 `Connected` 后即可使用。
+
+生产环境可将 `@latest` 替换为明确版本，以固定 MCP 行为。

package/mcp/figma-mcp-bridge/config.toml.example

@@ -0,0 +1,10 @@
+[mcp_servers.figma-mcp-bridge]
+command = "npx"
+args = ["--yes", "--package=@autobest-ui/agent@latest", "figma-mcp-bridge"]
+startup_timeout_sec = 30
+tool_timeout_sec = 120
+enabled = true
+
+[mcp_servers.figma-mcp-bridge.env]
+# 可选。默认从 3055 开始；端口占用时服务会依次尝试到 3070。
+FIGMA_BRIDGE_PORT = "3055"

package/mcp/figma-mcp-bridge/index.test.js

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const directory = path.dirname(fileURLToPath(import.meta.url));
+
+test('ships a valid skill frontmatter', async () => {
+  const skill = await readFile(path.join(directory, 'skills', 'figma-bridge', 'SKILL.md'), 'utf8');
+  assert.match(skill, /^---\nname: figma-bridge\ndescription: [^\n]+\n---\n/);
+});
+
+test('initializes and exposes Figma tools and skill resources over stdio', async () => {
+  const client = new Client({
+    name: 'figma-mcp-bridge-test',
+    version: '1.0.0'
+  });
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [path.join(directory, 'src', 'index.js')],
+    cwd: directory,
+    env: {
+      ...process.env,
+      FIGMA_BRIDGE_PORT: '0'
+    },
+    stderr: 'pipe'
+  });
+
+  try {
+    await client.connect(transport);
+    assert.equal(client.getServerVersion()?.name, 'figma-mcp-bridge');
+    assert.match(client.getInstructions() ?? '', /Figma MCP Bridge v0\.4\.0/);
+
+    const { tools } = await client.listTools();
+    assert.ok(tools.length >= 90);
+    assert.ok(tools.some(({ name }) => name === 'figma_get_context'));
+    assert.ok(tools.some(({ name }) => name === 'figma_create_frame'));
+
+    const { resources } = await client.listResources();
+    assert.ok(resources.some(({ uri }) => uri === 'skill://figma-bridge/SKILL.md'));
+  } finally {
+    await client.close();
+  }
+});

package/mcp/figma-mcp-bridge/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@autobest/figma-mcp-bridge",
+  "version": "0.4.0",
+  "private": true,
+  "description": "STDIO MCP server bridging Codex to the Autobest Figma plugin",
+  "type": "module",
+  "main": "src/index.js",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "ws": "8.18.3",
+    "zod": "4.4.3"
+  }
+}

package/mcp/figma-mcp-bridge/skills/figma-bridge/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: figma-bridge
+description: Operate figma-mcp-bridge for reliable Figma Design and FigJam reads, edits, verification, and export review.
+---
+
+# Figma MCP Bridge — Operation Skill
+
+How to work through the figma-mcp-bridge effectively and honestly. Read this
+before any write-heavy design session. Applies to bridge **v0.4.0+**.
+
+## Verification discipline — the core of this skill
+
+**1. Verify bindings by readback, not by assumption.**
+`figma_get_nodes` (full depth) returns `boundVariables` (node-level variable
+bindings), `explicitVariableModes` (pinned modes), `layoutWrap`,
+`counterAxisSpacing`, and `clipsContent`. After binding, pinning, or layout
+work, read the node back and confirm the field says what you intended. Mutating
+tools echo readbacks in their responses (`verified: true`, resulting
+`explicitVariableModes`, per-side stroke weights, etc.) — check them.
+
+**2. Export the render and look at it before reporting done.**
+`figma_export_node` writes the image to disk and returns the path — Read the
+file and actually look at it. Property readback cannot see composition: real
+sessions passed every numeric check while renders showed a portrait video well
+where a 16:9 one belonged, a heading breaking mid-word, and a button hugging at
+140px instead of spanning its form. Looking catches what measuring cannot.
+
+**3. Report honestly.**
+- If a tool errors, report the failure — never record the work as done.
+- If a readback disagrees with a success response, report that too.
+- Never paper over a missing capability by hardcoding a value.
+- The bridge errors instead of silently no-oping (see error codes below);
+  treat those errors as information about Figma's real constraints, not as
+  obstacles to retry around.
+
+## Errors that mean "Figma forbids this" (don't retry — change approach)
+
+- `INSTANCE_SUBLAYER_RESTRICTED` — size binds, resizes, and reorders inside an
+  instance are not allowed. Make the change on the component master; it flows
+  to every instance.
+- `MODE_NOT_FOUND` / `COLLECTION_NOT_FOUND` — the modeId/collectionId is wrong;
+  the error lists valid modes.
+- `WRONG_EDITOR` / `FIGMA_DESIGN_ONLY` — the tool is gated to FigJam or Figma
+  Design; the error names the current editor type (there are five: figma,
+  figjam, dev, slides, buzz).
+- `BIND_NOT_APPLIED` / `STYLE_NOT_APPLIED` / `RESIZE_NO_OP` /
+  `REORDER_FAILED` / `LIMIT_NOT_APPLIED` — the write did not land and the
+  bridge is telling you instead of pretending. Report it.
+
+## Tool guidance
+
+- **Sizing a child to its parent:** use `figma_set_layout_align: STRETCH`, not
+  `figma_resize_nodes`. STRETCH preserves width/height variable binds; resize
+  may destroy them (the bridge re-applies and warns, but STRETCH avoids the
+  problem entirely).
+- **Pinning variable modes:** `figma_set_variable_mode` sets or clears
+  (`clear: true`) an explicit mode per collection on nodes *and pages*. Pins
+  belong on preview/page frames. Never pin a component master — every instance
+  inherits it, per-collection, and the partial correctness hides the fault.
+- **Text styles:** create with `figma_create_text_style`, bind `fontSize` (and
+  other text fields) to variables via `figma_set_variable` with `styleId`,
+  apply with `figma_apply_style`, delete with `figma_delete_style`.
+- **Borders on one side:** `figma_set_strokes` per-side weights
+  (`strokeTopWeight` etc.); `strokes` may be omitted to change weights only.
+  A mixed weight reads back as the string `'MIXED'` plus the four per-side
+  values.
+- **Min/max sizes:** `figma_set_size_limits`; pass explicit `null` to clear.
+  `figma_unbind_variable` on a min/max field also clears the residual literal.
+- **Reordering:** `figma_reorder_node` `position` is the final index among
+  siblings (0 = back, `childCount-1` = front), verified by readback.
+- **Hiding:** `figma_set_visible` — don't fake it with opacity 0.
+- **Exports:** the returned `path` is the deliverable; Read it. No need to
+  inflate `scale` to force anything.
+- **Constraints:** set `figma_set_constraints` BEFORE converting the parent to
+  auto-layout; inside auto-layout parents it's rejected, and it can't be
+  overridden on instance sublayers at all.
+
+## Auto-layout facts that bite
+
+- `SPACE_BETWEEN` is inert when any child has `layoutGrow: 1` (no free space
+  to distribute) — `itemSpacing` is ignored then too.
+- `figma_set_layout_align: CENTER` is a no-op on a stretched child — use
+  `INHERIT` plus the parent's `counterAxisAlignItems: CENTER`.
+- Reading wrap: `layoutWrap` and `counterAxisSpacing` come back in full node
+  reads; compact children include x/y for geometry checks.
+- `figma_set_text` does not decode HTML entities — send literal characters
+  (`&`, not `&`).
+
+## Concurrency (multi-agent sessions)
+
+- One WebSocket to one open document. More than ~2 write-heavy agents produces
+  transient `Unable to establish connection` errors — retry them; if an agent
+  stalls completely, kill and restart it.
+- **Never call `figma_set_current_page` or `figma_set_selection` from a
+  sub-agent** — it yanks the shared view out from under every other client.
+- The plugin must be connected to THIS server's port: check
+  `figma_server_info` / `figma_get_context` first and surface the port to the
+  user if disconnected.

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

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+
+/**
+ * Figma MCP Bridge - Entry Point
+ *
+ * Starts the WebSocket server for Figma plugin communication
+ * and the MCP server for Agent communication.
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { FigmaBridge } from './websocket.js';
+import { createServer } from './server.js';
+
+const PORT = parseInt(process.env.FIGMA_BRIDGE_PORT || '3055', 10);
+
+async function main() {
+  // eslint-disable-next-line no-console
+  console.error('[FigmaMCP] Starting Figma MCP Bridge...');
+
+  // Create and start WebSocket bridge
+  const bridge = new FigmaBridge(PORT);
+  await bridge.start();
+
+  // Log connection events
+  bridge.on('connected', info => {
+    // eslint-disable-next-line no-console
+    console.error(`[FigmaMCP] Figma connected: ${info.fileName}`);
+  });
+
+  bridge.on('disconnected', () => {
+    // eslint-disable-next-line no-console
+    console.error('[FigmaMCP] Figma disconnected');
+  });
+
+  // Create MCP server
+  const server = createServer(bridge);
+
+  // Connect to stdio transport (Agent communication)
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // eslint-disable-next-line no-console
+  console.error(
+    `[FigmaMCP] MCP server running, WebSocket bound to port ${bridge.port}. Waiting for Figma plugin connection...`
+  );
+
+  // Graceful shutdown helper
+  const shutdown = async reason => {
+    // eslint-disable-next-line no-console
+    console.error(`[FigmaMCP] Shutting down (${reason})...`);
+    await bridge.stop();
+    process.exit(0);
+  };
+
+  // Handle graceful shutdown
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+  // Handle stdio close (when the Agent closes the connection)
+  process.stdin.on('close', () => shutdown('stdin closed'));
+  transport.onclose = () => shutdown('transport closed');
+}
+
+main().catch(error => {
+  // eslint-disable-next-line no-console
+  console.error('[FigmaMCP] Fatal error:', error);
+  process.exit(1);
+});

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

@@ -0,0 +1,159 @@
+/**
+ * MCP Server setup
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTools } from './tools/index.js';
+
+// Read package.json once at module load so version stays in sync with the published artifact
+const __dirname = dirname(fileURLToPath(import.meta.url));
+let pkgVersion = '0.0.0';
+try {
+  const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+  pkgVersion = pkg.version;
+} catch (_) {
+  // Fall back to placeholder if package.json can't be read
+}
+
+/**
+ * Create and configure the MCP server
+ * @param {FigmaBridge} bridge - Figma bridge instance (must be started — bridge.port must reflect the bound port)
+ * @returns {McpServer} Configured MCP server
+ */
+export function createServer(bridge) {
+  const port = bridge.port;
+  const instructions = `# Figma MCP Bridge v${pkgVersion}
+
+## CONNECTION INFO — CHECK FIRST
+
+This MCP server is bridging an Agent to Figma via a WebSocket on **port ${port}**.
+
+Multiple Agent sessions can run concurrently and the bridge falls back through ports 3055–3070, so the port may differ from the default. **At the start of any new Figma-related conversation, call \`figma_get_context\` to check connection state. If it returns \`connected: false\`, proactively tell the user:**
+
+> "The Figma MCP bridge is running on port **${port}**. Open the Figma plugin and set its port input to **${port}**, then re-run the plugin if it was already open."
+
+Don't make the user discover the port themselves — surface it the first time you notice they aren't connected.
+
+## SKILLS — READ BEFORE WRITE-HEAVY WORK
+
+This server ships its own skills as MCP resources. **Before any session that creates or edits design content (not just single reads), read \`skill://figma-bridge/SKILL.md\`** — it covers verification discipline (readback + export-and-look), the error codes that mean "Figma forbids this", bind-preserving sizing, mode pinning, concurrency rules, and auto-layout traps. List resources to discover any additional skills shipped with this server version.
+
+## FigJam Support
+
+This server supports both Figma design files AND FigJam files. FigJam-specific tools (sticky notes, flowchart shapes, connectors, tables, code blocks, link previews) are gated to FigJam files and return a \`WRONG_EDITOR\` error if called against a Figma design file.
+
+**Editor-restricted tools:**
+- FigJam-only (return \`WRONG_EDITOR\` in design files): all sticky / shape-with-text / connector / table / code-block / link-preview tools
+- Figma Design only (return \`FIGMA_DESIGN_ONLY\` in FigJam): \`figma_create_page\`, \`figma_duplicate_page\`. FigJam files have pages but the plugin API does not expose page creation; pages must be created via the FigJam UI by the user.
+
+For flowcharts in FigJam:
+- \`figma_create_shape_with_text\` with \`shapeType\` (ROUNDED_RECTANGLE for processes, DIAMOND for decisions, ENG_DATABASE for data stores, etc.)
+- \`figma_create_connector\` with \`{ start: { nodeId, magnet: 'AUTO' }, end: { nodeId, magnet: 'AUTO' } }\` — \`endCap\` defaults to \`ARROW_EQUILATERAL\` so connectors look like arrows
+- Wrap the diagram in a \`figma_create_section\` for grouping
+
+## IMPORTANT: Always Use Search Tools First
+
+When working with Figma documents, ALWAYS prefer search tools over bulk retrieval:
+
+### For Variables
+- **USE**: \`figma_search_variables\` (~500 tokens) - Filter by name pattern, type, collection
+- **AVOID**: \`figma_get_local_variables\` (25k+ tokens, may truncate)
+
+Example:
+\`\`\`
+figma_search_variables({ namePattern: "colors/*", type: "COLOR", compact: true })
+\`\`\`
+
+### For Nodes
+- **USE**: \`figma_search_nodes\` - Find frames/elements by name within a scope
+- **USE**: \`figma_get_children\` - Browse hierarchy one level at a time
+- **AVOID**: Repeated \`figma_get_nodes\` calls to traverse the tree
+
+Example:
+\`\`\`
+figma_search_nodes({ parentId: "0:1", nameContains: "Button", types: ["FRAME", "COMPONENT"] })
+\`\`\`
+
+### For Components
+- **USE**: \`figma_search_components\` - Find by name pattern
+- Returns compact results with component metadata
+
+### For Styles
+- **USE**: \`figma_search_styles\` - Find by name and type
+- **AVOID**: \`figma_get_local_styles\` for large documents
+
+## Workflow
+
+1. **Start with context**: Call \`figma_get_context\` to understand the current document and selection
+2. **Search first**: Use search tools to find specific elements by name
+3. **Get details only when needed**: Use \`figma_get_nodes\` with \`depth: "minimal"\` or \`"compact"\` for efficiency
+4. **Use full depth sparingly**: Only use \`depth: "full"\` when you need all node properties
+
+## Token Optimization
+
+| Tool | Tokens | Use Case |
+|------|--------|----------|
+| \`figma_search_*\` | ~50/result | Finding specific elements |
+| \`figma_get_children\` | ~50/node | Browsing hierarchy |
+| \`figma_get_nodes\` (minimal) | ~100/node | Tree traversal |
+| \`figma_get_nodes\` (full) | ~500/node | Detailed inspection |
+| \`figma_get_local_variables\` | 25k+ | AVOID - use search instead
+`;
+  const server = new McpServer(
+    {
+      name: 'figma-mcp-bridge',
+      version: pkgVersion
+    },
+    { instructions }
+  );
+
+  // Register all Figma tools
+  registerTools(server, bridge);
+
+  // Serve every skills/<name>/SKILL.md as an MCP resource (skill://<name>/SKILL.md)
+  // so agents get the bridge's operating knowledge without installing anything.
+  registerSkillResources(server);
+
+  return server;
+}
+
+/**
+ * Register the markdown skills shipped in skills/ as MCP resources.
+ * Files are read lazily per request so a dev checkout picks up edits
+ * without a server restart. Missing dir (or a race on a deleted file)
+ * degrades to no/absent resources rather than a crash.
+ * @param {McpServer} server
+ */
+function registerSkillResources(server) {
+  const skillsDir = join(__dirname, '..', 'skills');
+  if (!existsSync(skillsDir)) return;
+
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillPath = join(skillsDir, entry.name, 'SKILL.md');
+    if (!existsSync(skillPath)) continue;
+
+    const uri = `skill://${entry.name}/SKILL.md`;
+    server.registerResource(
+      entry.name,
+      uri,
+      {
+        title: `Skill: ${entry.name}`,
+        description: `Operating skill shipped with figma-mcp-bridge. Read before write-heavy ${entry.name} work.`,
+        mimeType: 'text/markdown'
+      },
+      async () => ({
+        contents: [
+          {
+            uri,
+            mimeType: 'text/markdown',
+            text: readFileSync(skillPath, 'utf8')
+          }
+        ]
+      })
+    );
+  }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * figma_get_context tool
+ * Returns current document context including connection status, file info, and selection
+ */
+
+export const contextTool = {
+  name: 'figma_get_context',
+  description:
+    'Get the current Figma document context including file info, current page, and selection. Use this to understand what document is open and what the user has selected.',
+  inputSchema: {
+    type: 'object',
+    properties: {},
+    required: []
+  }
+};
+
+export async function handleGetContext(bridge) {
+  if (!bridge.isConnected()) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              connected: false,
+              message: 'Figma plugin is not connected. Please open Figma and run the Autobest Figma Plugin.'
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  }
+
+  try {
+    const result = await bridge.sendCommand('get_context', {});
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              connected: true,
+              ...result
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              connected: true,
+              error: {
+                code: error.code || 'UNKNOWN_ERROR',
+                message: error.message
+              }
+            },
+            null,
+            2
+          )
+        }
+      ],
+      isError: true
+    };
+  }
+}