@autobest-ui/agent 1.0.0 → 1.0.2

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

@@ -1,9 +1,9 @@
-import assert from "node:assert/strict";
-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";
+import assert from 'node:assert/strict';
+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';
 import {
   extractAddedContent,
   isAttachmentPath,
@@ -11,66 +11,56 @@ import {
   isInsideRequestedPath,
   MAX_CONTENT_LENGTH,
   parsePullRequestLocation,
-  serializePullRequest,
-} from "./azure-devops.js";
+  serializePullRequest
+} from './azure-devops.js';
 
 const directory = path.dirname(fileURLToPath(import.meta.url));
 
-test("parses supported Azure DevOps PR URLs", () => {
+test('parses supported Azure DevOps PR URLs', () => {
   assert.deepEqual(
-    parsePullRequestLocation(
-      "https://autobest.visualstudio.com/AutoBestChina/_git/web/pullrequest/42",
-    ),
+    parsePullRequestLocation('https://autobest.visualstudio.com/AutoBestChina/_git/web/pullrequest/42'),
     {
-      apiRoot: "https://autobest.visualstudio.com/AutoBestChina",
-      repository: "web",
-      pullRequestId: "42",
-    },
+      apiRoot: 'https://autobest.visualstudio.com/AutoBestChina',
+      repository: 'web',
+      pullRequestId: '42'
+    }
   );
   assert.deepEqual(
-    parsePullRequestLocation(
-      "https://dev.azure.com/example/My%20Project/_git/front%20end/pullrequest/7",
-    ),
+    parsePullRequestLocation('https://dev.azure.com/example/My%20Project/_git/front%20end/pullrequest/7'),
     {
-      apiRoot: "https://dev.azure.com/example/My%20Project",
-      repository: "front end",
-      pullRequestId: "7",
-    },
-  );
-  assert.throws(
-    () =>
-      parsePullRequestLocation(
-        "https://example.com/org/project/_git/repo/pullrequest/1",
-      ),
-    /仅支持/,
+      apiRoot: 'https://dev.azure.com/example/My%20Project',
+      repository: 'front end',
+      pullRequestId: '7'
+    }
   );
+  assert.throws(() => parsePullRequestLocation('https://example.com/org/project/_git/repo/pullrequest/1'), /仅支持/);
 });
 
-test("filters paths and extracts added lines", () => {
-  assert.equal(isAttachmentPath("/docs/.attachments/image.png"), true);
-  assert.equal(isBinaryPath("/assets/logo.PNG"), true);
-  assert.equal(isInsideRequestedPath("/src/app/index.js", "/src"), true);
-  assert.equal(isInsideRequestedPath("/scripts/build.js", "/src"), false);
-  assert.deepEqual(extractAddedContent("a\nb\n", "a\nc\nb\n"), {
-    content: "c\n",
-    truncated: false,
+test('filters paths and extracts added lines', () => {
+  assert.equal(isAttachmentPath('/docs/.attachments/image.png'), true);
+  assert.equal(isBinaryPath('/assets/logo.PNG'), true);
+  assert.equal(isInsideRequestedPath('/src/app/index.js', '/src'), true);
+  assert.equal(isInsideRequestedPath('/scripts/build.js', '/src'), false);
+  assert.deepEqual(extractAddedContent('a\nb\n', 'a\nc\nb\n'), {
+    content: 'c\n',
+    truncated: false
   });
 });
 
-test("serializes oversized results as valid bounded JSON", () => {
+test('serializes oversized results as valid bounded JSON', () => {
   const text = serializePullRequest({
-    title: "Large PR",
-    description: "description",
-    status: "active",
+    title: 'Large PR',
+    description: 'description',
+    status: 'active',
     reviewers: [],
     reviewComments: [],
     workItems: [],
     latestIterationId: 1,
     changedFiles: Array.from({ length: 20 }, (_, index) => ({
-      changeType: "edit",
+      changeType: 'edit',
       path: `/src/file-${index}.js`,
-      addedContent: "x".repeat(20_000),
-    })),
+      addedContent: 'x'.repeat(20_000)
+    }))
   });
 
   assert.ok(text.length <= MAX_CONTENT_LENGTH);
@@ -78,35 +68,36 @@ test("serializes oversized results as valid bounded JSON", () => {
   assert.ok(JSON.parse(text).addedContentOmittedDueToResponseLimit > 0);
 });
 
-test("initializes and exposes the Azure PR tool over stdio", async () => {
+test('initializes and exposes the Azure PR tool over stdio', async () => {
   const client = new Client({
-    name: "azurepr-mcp-bridge-test",
-    version: "1.0.0",
+    name: 'azurepr-mcp-bridge-test',
+    version: '1.0.0'
   });
   const transport = new StdioClientTransport({
     command: process.execPath,
-    args: [path.join(directory, "index.js")],
-    cwd: path.resolve(directory, "../.."),
-    stderr: "pipe",
+    args: [path.join(directory, 'index.js')],
+    cwd: path.resolve(directory, '../..'),
+    stderr: 'pipe'
   });
 
   try {
     await client.connect(transport);
-    assert.equal(client.getServerVersion()?.name, "azurepr-mcp-bridge");
-    assert.match(client.getInstructions() ?? "", /AZURE_DEVOPS_PAT/);
+    assert.equal(client.getServerVersion()?.name, 'azurepr-mcp-bridge');
+    assert.match(client.getInstructions() ?? '', /AZURE_DEVOPS_PAT/);
 
     const { tools } = await client.listTools();
-    assert.deepEqual(tools.map(({ name }) => name), [
-      "get_azure_pull_request",
-    ]);
+    assert.deepEqual(
+      tools.map(({ name }) => name),
+      'get_azure_pull_request'
+    );
     assert.equal(tools[0].annotations?.readOnlyHint, true);
     assert.equal(tools[0].annotations?.openWorldHint, true);
 
     const missingPatResult = await client.callTool({
-      name: "get_azure_pull_request",
+      name: 'get_azure_pull_request',
       arguments: {
-        url: "https://autobest.visualstudio.com/AutoBestChina/_git/web/pullrequest/42",
-      },
+        url: 'https://autobest.visualstudio.com/AutoBestChina/_git/web/pullrequest/42'
+      }
     });
     assert.equal(missingPatResult.isError, true);
     assert.match(missingPatResult.content[0].text, /AZURE_DEVOPS_PAT 未配置/);

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')
+          }
+        ]
+      })
+    );
+  }
+}