Neumo Toolkit (Figma Plugin) — Setup Guide

How to install and connect @kofile/neumo-toolkit — the Figma desktop plugin that bridges the Neumo / GDS design system into Figma so Claude and other external editors can call Figma tools over a live WebSocket connection (via figma-console-mcp).

It is the design-side counterpart to @kofile/neumo-mcp-server: the MCP server answers questions about the design system; the toolkit gives an assistant a live connection into Figma for design-to-code work.

This is a Figma plugin, not an MCP server. You don't register it in .mcp.json. You install the npm package, import its manifest into the Figma desktop app, and connect it to a running figma-console-mcp bridge.

Table of contents

• How it differs from the MCP server
• Prerequisites
• 1. Install the package
• 2. Import the plugin into Figma
• 3. Start the bridge server
• 4. Connect
• Updating
• Troubleshooting

How it differs from the MCP server

The two are complementary — install both for the full workflow.

Note: figma-console-mcp (southleft) is a separate bridge from the official Figma MCP server. This toolkit rides on figma-console-mcp specifically.

Prerequisites

• Figma desktop app (plugin development requires the desktop app, not the browser)
• Node.js ≥ 18 — to run the figma-console-mcp bridge
• Access to the @kofile npm scope

1. Install the package

You don't need to clone the design-system monorepo — the published package ships the built dist/ + manifest.json, and Figma resolves the plugin files relative to the manifest.

Private package — authenticate first. @kofile/* is private on npm, so you need a one-time access token before installing. Create a Read-only token at npmjs.com (avatar → Access Tokens, with @kofile org membership), then run npm config set //registry.npmjs.org/:_authToken=PASTE_TOKEN_HERE. Full guide: npm access token.

npm install --save-dev @kofile/neumo-toolkit   # pin a version, e.g. @kofile/neumo-toolkit@0.1.0

This installs the plugin at node_modules/@kofile/neumo-toolkit/ with:

manifest.json     ← the file you point Figma at
dist/code.js      ← plugin main thread (Figma sandbox)
dist/ui.html      ← iframe UI shell
dist/ui.js        ← tab nav + Bridge WebSocket client

This is a Figma-side install, not project-side. Importing the manifest registers the plugin in your Figma desktop app globally — it isn't scoped to this repo. The repo only matters because that's where node_modules (and thus the manifest path you point Figma at) lives.

2. Import the plugin into Figma

In the Figma desktop app:

1. Plugins → Development → Import plugin from manifest…
2. Select the manifest at:

   <your-project>/node_modules/@kofile/neumo-toolkit/manifest.json
   

3. Run Neumo Toolkit from the Plugins → Development menu.

The plugin opens with three tabs: Bridge (the WebSocket connection), Tokens, and Components (the latter two are placeholders in v0.1).

3. Start the bridge server

The Bridge tab connects to a running figma-console-mcp server. Start it from a terminal:

npx figma-console-mcp

It listens on ws://localhost:9220 by default and rolls forward (9221, 9222, …, up to 9232) if a lower port is already in use — this is how it supports multiple Figma windows.

⚠️ Remember which port it actually claimed. If 9220 was busy when it started, the server will be on a higher port, and you must select that exact port in step 4. This is the #1 cause of connection errors — see Troubleshooting.

To see the port it bound to:

lsof -nP -iTCP -sTCP:LISTEN | grep -E ':92[0-9][0-9]'

4. Connect

1. In the plugin's Bridge tab, set the PORT dropdown to the port the server actually claimed in step 3 (e.g. 9220, or 9224 if it rolled forward).
2. Click Connect.
3. The header status pill turns green and STATUS reads connected once the WebSocket handshake completes.

You're now bridged — Claude / external editors can call Figma tools against this file.

Updating

npm install --save-dev @kofile/neumo-toolkit@latest

Then reload the plugin in Figma (re-run it, or Plugins → Development → reload). The bundled plugin code is a snapshot from publish time, so bump the package to get new features/fixes.

Troubleshooting

🔴 Status: "Error", LAST EVENT: close — almost always a port mismatch

Symptom: the header pill is red / says Error, and the STATUS panel shows a close @ <time> event for an endpoint like ws://localhost:9223.

What it means: the plugin opened a WebSocket to the port you selected, and nothing was listening there, so the connection closed immediately. It is not a problem with the plugin or the design system.

The usual cause: the figma-console-mcp server bound to a different port than the one selected in the dropdown — because the default 9220 (or whichever lower port) was busy at launch and it rolled forward.

Fix:

1. Find the port the server actually claimed:

   lsof -nP -iTCP -sTCP:LISTEN | grep -E ':92[0-9][0-9]'
   

   e.g. node … TCP [::1]:9224 (LISTEN) means it's on 9224.
2. Set the plugin's PORT dropdown to that exact port.
3. Click Connect — the pill should turn green.

Tip — pin it to the default port. If you want a predictable 9220, make sure no stray bridge processes are holding the lower ports, then relaunch:

pkill -f figma-console-mcp     # stop any running bridges
npx figma-console-mcp          # relaunch; it will claim 9220 if free

Confirm with the lsof command above, then select 9220 in the plugin.

No 92xx port is listening at all

The bridge server isn't running. Start it with npx figma-console-mcp and check for the listener with the lsof command above before connecting.

Plugin doesn't appear in Figma

• Confirm you used the desktop app (browser Figma can't import dev plugins).
• Re-import: Plugins → Development → Import plugin from manifest… and select node_modules/@kofile/neumo-toolkit/manifest.json.
• Confirm dist/code.js and dist/ui.html exist (they ship in the package).

Connection succeeds but selection/variables don't update

The UI iframe owns the WebSocket; the plugin main thread (code.js) brokers anything needing the Figma API. Make sure a file is open and an element is selected — the CURRENT SELECTION panel reflects the active selection.

Plugin version documented: @kofile/neumo-toolkit@0.1.0; bridge: figma-console-mcp (ports 9220–9232).