feat(m2): add set_opacity / set_visible / rename_node / delete_nodes

awdr74100 · awdr74100 · commit 4eda9d0a0477 · 2026-05-24T03:40:49.000+08:00
Fan out the write pattern: three single-property setters (opacity / visibility /
name) and the first multi-node op, delete_nodes (resolves targets in parallel,
removes sequentially, skips missing/already-removed, returns the affected ids).
shared: BatchNodeResult. All idempotency-wrapped and registered in WRITE_TOOLS.

7 write tools total; +11 tests (307). lint / typecheck / build green.
diff --git a/packages/plugin/src/code.ts b/packages/plugin/src/code.ts
@@ -3,6 +3,7 @@ import { createPluginContextEvent, SELECTION_DETAIL_LIMIT } from '@figma-mcp-rel
 import { dispatchSandboxMessage, type SandboxHandlers } from './dispatcher.js';
 import { createIdempotencyCache, idempotent } from './idempotency.js';
 import { createCreateFrameHandler } from './handlers/create-frame.js';
+import { createDeleteNodesHandler } from './handlers/delete-nodes.js';
 import { createGetAnnotationsHandler } from './handlers/get-annotations.js';
 import { createGetDesignContextHandler } from './handlers/get-design-context.js';
 import { createGetDocumentHandler } from './handlers/get-document.js';
@@ -23,8 +24,11 @@ import { createPingHandler } from './handlers/ping.js';
 import { createScanNodesByTypesHandler } from './handlers/scan-nodes-by-types.js';
 import { createScanTextNodesHandler } from './handlers/scan-text-nodes.js';
 import { createSearchNodesHandler } from './handlers/search-nodes.js';
+import { createRenameNodeHandler } from './handlers/rename-node.js';
 import { createSetFillsHandler } from './handlers/set-fills.js';
+import { createSetOpacityHandler } from './handlers/set-opacity.js';
 import { createSetTextHandler } from './handlers/set-text.js';
+import { createSetVisibleHandler } from './handlers/set-visible.js';
 
 figma.showUI(__html__, { width: 320, height: 400, themeColors: true });
 
@@ -81,6 +85,10 @@ const handlers: SandboxHandlers = {
   set_fills: idempotent(idempotencyCache, createSetFillsHandler(figma)),
   set_text: idempotent(idempotencyCache, createSetTextHandler(figma)),
   create_frame: idempotent(idempotencyCache, createCreateFrameHandler(figma)),
+  set_opacity: idempotent(idempotencyCache, createSetOpacityHandler(figma)),
+  set_visible: idempotent(idempotencyCache, createSetVisibleHandler(figma)),
+  rename_node: idempotent(idempotencyCache, createRenameNodeHandler(figma)),
+  delete_nodes: idempotent(idempotencyCache, createDeleteNodesHandler(figma)),
 };
 
 figma.ui.onmessage = (raw: unknown) => {
diff --git a/packages/plugin/src/handlers/delete-nodes.ts b/packages/plugin/src/handlers/delete-nodes.ts
@@ -0,0 +1,30 @@
+import type { BatchNodeResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createDeleteNodesHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeIds?: unknown };
+    if (!Array.isArray(p.nodeIds) || p.nodeIds.some(id => typeof id !== 'string')) {
+      throw new TypeError('delete_nodes: nodeIds must be a string[]');
+    }
+    const ids = p.nodeIds as readonly string[];
+    const nodes = await Promise.all(ids.map(id => figmaCtx.getNodeByIdAsync(id)));
+
+    // Resolve in parallel, then remove sequentially. Missing / already-removed / non-removable
+    // nodes are skipped (not in `affected`) rather than failing the whole call.
+    const affected: string[] = [];
+    nodes.forEach((node, i) => {
+      if (node === null || !('remove' in node)) return;
+      try {
+        (node as { remove: () => void }).remove();
+        affected.push(ids[i]!);
+      } catch {
+        /* node was already removed (e.g. its ancestor was deleted first) */
+      }
+    });
+
+    const result: BatchNodeResult = { ok: true, affected };
+    return result;
+  };
diff --git a/packages/plugin/src/handlers/rename-node.ts b/packages/plugin/src/handlers/rename-node.ts
@@ -0,0 +1,18 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createRenameNodeHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; name?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('rename_node: nodeId must be a string');
+    if (typeof p.name !== 'string' || p.name.length === 0) {
+      throw new TypeError('rename_node: name must be a non-empty string');
+    }
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null) throw new Error(`rename_node: node ${p.nodeId} not found`);
+    node.name = p.name;
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };
diff --git a/packages/plugin/src/handlers/set-opacity.ts b/packages/plugin/src/handlers/set-opacity.ts
@@ -0,0 +1,20 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createSetOpacityHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; opacity?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('set_opacity: nodeId must be a string');
+    if (typeof p.opacity !== 'number' || p.opacity < 0 || p.opacity > 1) {
+      throw new TypeError('set_opacity: opacity must be a number in 0–1');
+    }
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null || !('opacity' in node)) {
+      throw new Error(`set_opacity: node ${p.nodeId} not found or has no opacity`);
+    }
+    (node as { opacity: number }).opacity = p.opacity;
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };
diff --git a/packages/plugin/src/handlers/set-visible.ts b/packages/plugin/src/handlers/set-visible.ts
@@ -0,0 +1,18 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+
+import type { SandboxToolHandler } from '../dispatcher.js';
+
+export const createSetVisibleHandler =
+  (figmaCtx: typeof figma): SandboxToolHandler =>
+  async params => {
+    const p = (params ?? {}) as { nodeId?: unknown; visible?: unknown };
+    if (typeof p.nodeId !== 'string') throw new TypeError('set_visible: nodeId must be a string');
+    if (typeof p.visible !== 'boolean') throw new TypeError('set_visible: visible must be a boolean');
+    const node = await figmaCtx.getNodeByIdAsync(p.nodeId);
+    if (node === null || !('visible' in node)) {
+      throw new Error(`set_visible: node ${p.nodeId} not found or cannot be hidden`);
+    }
+    (node as SceneNode).visible = p.visible;
+    const result: MutateResult = { ok: true, nodeId: node.id };
+    return result;
+  };
diff --git a/packages/plugin/test/handlers/delete-nodes.test.ts b/packages/plugin/test/handlers/delete-nodes.test.ts
@@ -0,0 +1,38 @@
+import type { BatchNodeResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it, vi } from 'vitest';
+
+import { createDeleteNodesHandler } from '../../src/handlers/delete-nodes.js';
+
+const fakeFigma = (lookup: Record<string, unknown>): typeof figma =>
+  ({ getNodeByIdAsync: async (id: string) => lookup[id] ?? null }) as unknown as typeof figma;
+
+describe('delete_nodes handler', () => {
+  it('removes found nodes and reports only the affected ids', async () => {
+    const a = { id: '1:1', remove: vi.fn<() => void>() };
+    const b = { id: '1:2', remove: vi.fn<() => void>() };
+    const handler = createDeleteNodesHandler(fakeFigma({ '1:1': a, '1:2': b }));
+    const result = (await handler({ nodeIds: ['1:1', '9:9', '1:2'] })) as BatchNodeResult;
+
+    expect(a.remove).toHaveBeenCalled();
+    expect(b.remove).toHaveBeenCalled();
+    expect(result).toEqual({ ok: true, affected: ['1:1', '1:2'] }); // 9:9 missing → skipped
+  });
+
+  it('skips nodes whose remove() throws (e.g. already removed via an ancestor)', async () => {
+    const a = {
+      id: '1:1',
+      remove: () => {
+        throw new Error('already removed');
+      },
+    };
+    const handler = createDeleteNodesHandler(fakeFigma({ '1:1': a }));
+    const result = (await handler({ nodeIds: ['1:1'] })) as BatchNodeResult;
+    expect(result.affected).toEqual([]);
+  });
+
+  it('throws on bad input', async () => {
+    const handler = createDeleteNodesHandler(fakeFigma({}));
+    await expect(handler({ nodeIds: 'x' })).rejects.toThrow(/nodeIds/);
+    await expect(handler({ nodeIds: [1] })).rejects.toThrow(/nodeIds/);
+  });
+});
diff --git a/packages/plugin/test/handlers/rename-node.test.ts b/packages/plugin/test/handlers/rename-node.test.ts
@@ -0,0 +1,24 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it } from 'vitest';
+
+import { createRenameNodeHandler } from '../../src/handlers/rename-node.js';
+
+const fakeFigma = (lookup: Record<string, unknown>): typeof figma =>
+  ({ getNodeByIdAsync: async (id: string) => lookup[id] ?? null }) as unknown as typeof figma;
+
+describe('rename_node handler', () => {
+  it('renames a node and returns ok + nodeId', async () => {
+    const node = { id: '1:1', name: 'Old' };
+    const handler = createRenameNodeHandler(fakeFigma({ '1:1': node }));
+    const result = (await handler({ nodeId: '1:1', name: 'New' })) as MutateResult;
+    expect(node.name).toBe('New');
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('rejects empty name, bad input, and missing nodes', async () => {
+    const handler = createRenameNodeHandler(fakeFigma({ '1:1': { id: '1:1', name: 'Old' } }));
+    await expect(handler({ nodeId: '1:1', name: '' })).rejects.toThrow(/name/);
+    await expect(handler({ nodeId: '1:1' })).rejects.toThrow(/name/);
+    await expect(handler({ nodeId: '9:9', name: 'x' })).rejects.toThrow(/not found/);
+  });
+});
diff --git a/packages/plugin/test/handlers/set-opacity.test.ts b/packages/plugin/test/handlers/set-opacity.test.ts
@@ -0,0 +1,25 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it } from 'vitest';
+
+import { createSetOpacityHandler } from '../../src/handlers/set-opacity.js';
+
+const fakeFigma = (lookup: Record<string, unknown>): typeof figma =>
+  ({ getNodeByIdAsync: async (id: string) => lookup[id] ?? null }) as unknown as typeof figma;
+
+describe('set_opacity handler', () => {
+  it('sets opacity and returns ok + nodeId', async () => {
+    const node = { id: '1:1', opacity: 1 };
+    const handler = createSetOpacityHandler(fakeFigma({ '1:1': node }));
+    const result = (await handler({ nodeId: '1:1', opacity: 0.5 })) as MutateResult;
+    expect(node.opacity).toBe(0.5);
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('rejects out-of-range opacity, bad input, and missing nodes', async () => {
+    const handler = createSetOpacityHandler(fakeFigma({ '1:1': { id: '1:1', opacity: 1 } }));
+    await expect(handler({ nodeId: '1:1', opacity: 2 })).rejects.toThrow(/opacity/);
+    await expect(handler({ nodeId: '1:1' })).rejects.toThrow(/opacity/);
+    await expect(handler({ opacity: 0.5 })).rejects.toThrow(/nodeId/);
+    await expect(handler({ nodeId: '9:9', opacity: 0.5 })).rejects.toThrow(/not found/);
+  });
+});
diff --git a/packages/plugin/test/handlers/set-visible.test.ts b/packages/plugin/test/handlers/set-visible.test.ts
@@ -0,0 +1,24 @@
+import type { MutateResult } from '@figma-mcp-relay/shared';
+import { describe, expect, it } from 'vitest';
+
+import { createSetVisibleHandler } from '../../src/handlers/set-visible.js';
+
+const fakeFigma = (lookup: Record<string, unknown>): typeof figma =>
+  ({ getNodeByIdAsync: async (id: string) => lookup[id] ?? null }) as unknown as typeof figma;
+
+describe('set_visible handler', () => {
+  it('toggles visibility and returns ok + nodeId', async () => {
+    const node = { id: '1:1', visible: true };
+    const handler = createSetVisibleHandler(fakeFigma({ '1:1': node }));
+    const result = (await handler({ nodeId: '1:1', visible: false })) as MutateResult;
+    expect(node.visible).toBe(false);
+    expect(result).toEqual({ ok: true, nodeId: '1:1' });
+  });
+
+  it('rejects non-boolean visible, bad input, and missing nodes', async () => {
+    const handler = createSetVisibleHandler(fakeFigma({ '1:1': { id: '1:1', visible: true } }));
+    await expect(handler({ nodeId: '1:1', visible: 'yes' })).rejects.toThrow(/visible/);
+    await expect(handler({ visible: true })).rejects.toThrow(/nodeId/);
+    await expect(handler({ nodeId: '9:9', visible: true })).rejects.toThrow(/not found/);
+  });
+});
diff --git a/packages/server/src/index.ts b/packages/server/src/index.ts
@@ -43,8 +43,12 @@ import { scanNodesByTypesToolDefinition } from './tools/scan-nodes-by-types.js';
 import { scanTextNodesToolDefinition } from './tools/scan-text-nodes.js';
 import { searchNodesToolDefinition } from './tools/search-nodes.js';
 import { CREATE_FRAME_TOOL_NAME, createFrameToolDefinition } from './tools/create-frame.js';
+import { DELETE_NODES_TOOL_NAME, deleteNodesToolDefinition } from './tools/delete-nodes.js';
+import { RENAME_NODE_TOOL_NAME, renameNodeToolDefinition } from './tools/rename-node.js';
 import { SET_FILLS_TOOL_NAME, setFillsToolDefinition } from './tools/set-fills.js';
+import { SET_OPACITY_TOOL_NAME, setOpacityToolDefinition } from './tools/set-opacity.js';
 import { SET_TEXT_TOOL_NAME, setTextToolDefinition } from './tools/set-text.js';
+import { SET_VISIBLE_TOOL_NAME, setVisibleToolDefinition } from './tools/set-visible.js';
 
 const SERVER_NAME = '@figma-mcp-relay/server';
 const SERVER_VERSION = '0.0.0';
@@ -108,6 +112,10 @@ mcp.setRequestHandler(ListToolsRequestSchema, () => ({
     setFillsToolDefinition,
     setTextToolDefinition,
     createFrameToolDefinition,
+    setOpacityToolDefinition,
+    setVisibleToolDefinition,
+    renameNodeToolDefinition,
+    deleteNodesToolDefinition,
   ],
 }));
 
@@ -117,6 +125,10 @@ const WRITE_TOOLS = new Set<string>([
   SET_FILLS_TOOL_NAME,
   SET_TEXT_TOOL_NAME,
   CREATE_FRAME_TOOL_NAME,
+  SET_OPACITY_TOOL_NAME,
+  SET_VISIBLE_TOOL_NAME,
+  RENAME_NODE_TOOL_NAME,
+  DELETE_NODES_TOOL_NAME,
 ]);
 
 mcp.setRequestHandler(CallToolRequestSchema, async request => {
diff --git a/packages/server/src/tools/delete-nodes.ts b/packages/server/src/tools/delete-nodes.ts
@@ -0,0 +1,17 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const DELETE_NODES_TOOL_NAME = 'delete_nodes';
+
+export const deleteNodesToolDefinition: Tool = {
+  name: DELETE_NODES_TOOL_NAME,
+  description:
+    'Delete nodes by id. Missing / non-removable nodes are skipped. Returns { ok, affected } — the ids actually removed.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      nodeIds: { type: 'array', items: { type: 'string' }, description: 'Node ids to delete' },
+    },
+    required: ['nodeIds'],
+    additionalProperties: false,
+  },
+};
diff --git a/packages/server/src/tools/rename-node.ts b/packages/server/src/tools/rename-node.ts
@@ -0,0 +1,17 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const RENAME_NODE_TOOL_NAME = 'rename_node';
+
+export const renameNodeToolDefinition: Tool = {
+  name: RENAME_NODE_TOOL_NAME,
+  description: "Rename a node. Returns { ok, nodeId }.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      nodeId: { type: 'string', description: 'Figma node id' },
+      name: { type: 'string', description: 'New layer name' },
+    },
+    required: ['nodeId', 'name'],
+    additionalProperties: false,
+  },
+};
diff --git a/packages/server/src/tools/set-opacity.ts b/packages/server/src/tools/set-opacity.ts
@@ -0,0 +1,17 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const SET_OPACITY_TOOL_NAME = 'set_opacity';
+
+export const setOpacityToolDefinition: Tool = {
+  name: SET_OPACITY_TOOL_NAME,
+  description: "Set a node's opacity (0–1). Returns { ok, nodeId }.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      nodeId: { type: 'string', description: 'Figma node id' },
+      opacity: { type: 'number', minimum: 0, maximum: 1, description: 'Opacity 0–1' },
+    },
+    required: ['nodeId', 'opacity'],
+    additionalProperties: false,
+  },
+};
diff --git a/packages/server/src/tools/set-visible.ts b/packages/server/src/tools/set-visible.ts
@@ -0,0 +1,17 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const SET_VISIBLE_TOOL_NAME = 'set_visible';
+
+export const setVisibleToolDefinition: Tool = {
+  name: SET_VISIBLE_TOOL_NAME,
+  description: "Show or hide a node. Returns { ok, nodeId }.",
+  inputSchema: {
+    type: 'object',
+    properties: {
+      nodeId: { type: 'string', description: 'Figma node id' },
+      visible: { type: 'boolean', description: 'true to show, false to hide' },
+    },
+    required: ['nodeId', 'visible'],
+    additionalProperties: false,
+  },
+};
diff --git a/packages/server/test/tools/write-tools.test.ts b/packages/server/test/tools/write-tools.test.ts
@@ -1,8 +1,12 @@
 import { describe, expect, it } from 'vitest';
 
 import { CREATE_FRAME_TOOL_NAME, createFrameToolDefinition } from '../../src/tools/create-frame.js';
+import { DELETE_NODES_TOOL_NAME, deleteNodesToolDefinition } from '../../src/tools/delete-nodes.js';
+import { RENAME_NODE_TOOL_NAME, renameNodeToolDefinition } from '../../src/tools/rename-node.js';
 import { SET_FILLS_TOOL_NAME, setFillsToolDefinition } from '../../src/tools/set-fills.js';
+import { SET_OPACITY_TOOL_NAME, setOpacityToolDefinition } from '../../src/tools/set-opacity.js';
 import { SET_TEXT_TOOL_NAME, setTextToolDefinition } from '../../src/tools/set-text.js';
+import { SET_VISIBLE_TOOL_NAME, setVisibleToolDefinition } from '../../src/tools/set-visible.js';
 
 describe('M2 write tool definitions', () => {
   it('set_fills requires nodeId + fills', () => {
@@ -36,8 +40,42 @@ describe('M2 write tool definitions', () => {
     expect(createFrameToolDefinition.inputSchema.required).toEqual([]);
   });
 
+  it('set_opacity / set_visible / rename_node declare nodeId + their value, required', () => {
+    expect(setOpacityToolDefinition.name).toBe(SET_OPACITY_TOOL_NAME);
+    expect(setOpacityToolDefinition.inputSchema).toMatchObject({
+      required: ['nodeId', 'opacity'],
+      properties: { opacity: { type: 'number', minimum: 0, maximum: 1 } },
+    });
+    expect(setVisibleToolDefinition.name).toBe(SET_VISIBLE_TOOL_NAME);
+    expect(setVisibleToolDefinition.inputSchema).toMatchObject({
+      required: ['nodeId', 'visible'],
+      properties: { visible: { type: 'boolean' } },
+    });
+    expect(renameNodeToolDefinition.name).toBe(RENAME_NODE_TOOL_NAME);
+    expect(renameNodeToolDefinition.inputSchema).toMatchObject({
+      required: ['nodeId', 'name'],
+      properties: { name: { type: 'string' } },
+    });
+  });
+
+  it('delete_nodes requires a nodeIds string array', () => {
+    expect(deleteNodesToolDefinition.name).toBe(DELETE_NODES_TOOL_NAME);
+    expect(deleteNodesToolDefinition.inputSchema).toMatchObject({
+      required: ['nodeIds'],
+      properties: { nodeIds: { type: 'array', items: { type: 'string' } } },
+    });
+  });
+
   it('write tools do not expose requestId in their MCP schema (server injects it)', () => {
-    for (const def of [setFillsToolDefinition, setTextToolDefinition, createFrameToolDefinition]) {
+    for (const def of [
+      setFillsToolDefinition,
+      setTextToolDefinition,
+      createFrameToolDefinition,
+      setOpacityToolDefinition,
+      setVisibleToolDefinition,
+      renameNodeToolDefinition,
+      deleteNodesToolDefinition,
+    ]) {
       const props = def.inputSchema.properties as Record<string, unknown>;
       expect(props.requestId).toBeUndefined();
     }
diff --git a/packages/shared/src/writes.ts b/packages/shared/src/writes.ts
