seed-verify-figma-mcp-transports

Files (1)

• SKILL.md

SKILL.md (first lines)

# Verify Figma MCP Transports

A Figma MCP tool answers the same question over two paths: **REST** (personal access token) and **WebSocket** (the Figma plugin). Fixing one and not the other still typechecks, so the drift is silent. Run both and compare mechanically.

두 경로의 구현 차이가 판단에 필요할 때만 `packages/mcp/AGENTS.md`를 읽는다.

> [!IMPORTANT]
> Run this skill **on the main thread**. Phase 3 is a hard stop that waits on a person, and a subagent has nobody to ask — it will pass itself.

## Prerequisites

- `FIGMA_PERSONAL_ACCESS_TOKEN` is set. If not, stop at Phase 0 and ask for it.
- The Figma desktop app is installed.
- The tool under test is registered in `PROBES` in the probe script. If it isn't, register it first — see the header comment in that file.

## Phase 0: Decide what to inspect

Both transports need a target, so this comes before any probing — REST in Phase 1 already needs it.

**검증 기준은 변경 diff에서 스스로 도출한다.** 사용자가 이미 조건을 만족하는 layer URL을 제공했으면 그대로 사용한다. 그렇지 않으면 특정 node가 아니라 필요한 layer 형태를 설명해 URL을 요청한다. "A frame containing a layer with two or more annotations, and a text layer with none"은 답할 수 있지만, "Give me a layer URL"은 검증 설계를 사용자에게 넘긴다.

Start from this checklist and cut what your change doesn't touch:

| Cover | Why |
|---|---|
| The queried node itself carrying a value | Catches a traversal that skips its own root |
| A descendant carrying a value | The recursive collection path |
| A leaf (no `children`) | Whether a non-container node throws |
| A page (`CANVAS` / `PAGE`) | The plugin-only `loadAsync` path, plus the type-vocabulary difference |
| A node inside a component instance | IDs composed as `I<a>;<b>;<c>` |

The last two apply to every tool. The rest apply only when the tool walks a tree.

Ask with **AskUserQuestion**, and ask for a **layer URL** — `parseFigmaUrl` takes the file key and node id straight out of it, so nobody has to read ids off a canvas.

If the same file gets reused across runs, put its key in `SEED_MCP_PROBE_FILE_KEY` and pass only `--node-id` afterwards.

## Phase 1: REST alone (no person needed)

REST needs nothing but the token, so **finish it without asking anyone.**

```bash
bun packages/mcp/scripts/probe-transports.ts \
  --probe <tool> \
  --transport rest \
  --file-key <key> \
  --node-id <id>
```

- The script calls the same helper the tool handler calls. Never reach past it to the REST API directly — that tests Figma, not the tool.
- If this fails, do not move on to WebSocket prep. Calling a person in to help debug a broken REST path spends their time on your bug.

## Phase 2: Prepare WebSocket (up to the human boundary)

Build everything that does not need a person, so the person is interrupted exactly once.

1. Build the plugin. Editing the source without rebuilding leaves Figma reading the old `dist`.

   ```bash
   bun --filter figma-mcp build
   ```

2. Start the relay in the background (`Bash` with `run_in_background: true`).

   ```bash
   bun packages/mcp/bin/index.mjs socket
   ```

   Wait for `WebSocket server running on port 3055`. If the port is already held, ask whether to reuse that process — never kill something you did not start.

## Phase 3: Hand off (hard stop)

Only a person can drive the Figma desktop app. There is no way around this step.

**Before asking, confirm all of these.** If any is false, go back to Phase 2 — the person gets called once.

- [ ] `tools/figma-mcp/dist` was just rebuilt
- [ ] The relay is listening on 3055
- [ ] Phase 1 passed

Then ask with **AskUserQuestion**. Do not write the question into chat and continue — that is not a stop.

Spell out what to do and why each step matters; without the reason people skip the reload. Refer to the file by the key Phase 1 actually used. If they open a different file the two transports answer about different documents, and that difference gets reported as a code bug.

```text
WebSocket side is ready. Two things in Figma:

1. Quit the plugin and run it again — dist was just rebuilt, and a running
   instance keeps answering with the old code.
2. Open the file from Phase 1 (<key>) and hit Connect in the plugin.
   Port 3055, channel is fixed to local-default, so there is nothing to type.
```

Offer three options:

| Option | Next |
|---|---|
| `Ready` | Phase 4 |
| `Show me how to reload the plugin` | Explain, then ask again |
| `Stop` | Clean up the relay, report Phase 1 only |

## Phase 4: Probe and compare

1. **Do not take "ready" at face value.** Check the relay log for `New client connected` first. If it is missing, ask again rather than probing into a void — an unconnected run yields a 30-second timeout that reads like a plugin bug.

2. Run both and diff:

   ```bash
   bun packages/mcp/scripts/probe-transports.ts \
     --probe <tool> \
     --transport both \
     --file-key <key> \
     --node-id <id>
   ```

3. **The exit code decides whether anything differs — not whether it is a bug.** Do not read the output and conclude it "looks the same"; 0 means the transports agree on every compared field. A 1 prints the disagreement, which you then classify with the table below before calling it a bug.

4. Run every node you chose in Phase 0. One passing node is not a pass.

From daangn/seed-design, Apache-2.0.

More from daangn/seed-design