add-mcp-tool
Skill0 starsChanged 2 months agoMITView on GitHub
Add a new tool or wire command to the Figmagent MCP server. Use when extending Figmagent itself — adding an MCP tool in src/figmagent_mcp/tools/, a plugin command handler, a registry entry, or a remote-transport domain mapping. Not for using Figma via the existing tools.
12 other projects use a version of this.
Adopted by
Most recently taken up by
- janusson/MSMCPtheir own version, first seen Oct 25, 2026
- skillist-io/skillisttheir own version, first seen Oct 11, 2026
- james5101/jobtracktheir own version, first seen Oct 11, 2026
- Locker-Room-Tools/synapsetheir own version, first seen Oct 11, 2026
- letehaha/moneymattertheir own version, first seen Oct 11, 2026
- openfootmanager/openfootmanagertheir own version, first seen Oct 8, 2026
Other versions12 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 12
- openfootmanager/openfootmanager★ 1.2ksame name
- letehaha/moneymatter★ 243same name
- dylanroscover/Embody★ 219same name
- tacticlaunch/mcp-linear★ 151same name
- radimsem/remindb★ 125same name
- paulieb89/property-shared★ 16same name
- plumbkit/plumb★ 4same name
- james5101/jobtrack★ 2same name
- Locker-Room-Tools/synapse★ 2same name
- janusson/MSMCP★ 1same name
2 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- analyze-sessionSkill
- tidy-upSkill
- figma-guidelinesSkill
- figma-pluginsSkill
- figma-sub-agentsSkill
The file
We split this skill into the rules it gives an agent
3 rules. 0 are common, 1 is distinctive, and 2 are very specific to this project.
0
Common
Most of the 11 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Use this skill when adding new tools or commands that let AI agents control Figma through the MCP server.
- Very specific: line 35
Run bun run build:plugin (regenerates code.js), bun test, bun run check.
- Very specific: line 85
Errors state fixes: use fail(message, fix) from helpers.js — no user-facing error without a stated fix.
“Common” is measured: kept by at least 6 in 10 of the 11 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Skill: Adding a New MCP Tool to Figmagent
Use this skill when adding new tools or commands that let AI agents control Figma through the MCP server.
Architecture Overview
One command implementation serves two transports. The relay and plugin UI are generic routers — adding a new tool never touches them:
plugin: MCP Server (tools/*.ts) ←WS→ Relay (socket.ts) ←WS→ Plugin UI (ui.html) ←postMessage→ code.js (registry dispatch)
remote: MCP Server (tools/*.ts) → remote/executor.ts → per-domain bundle of the same command modules → Figma's use_figma VMMCP tool names (first arg of server.tool) are decoupled from wire command names — e.g. the edit tool sends the apply wire command. Pick an agent-facing tool name freely; the wire command name is permanent protocol (it never changes after shipping — renames happen at the MCP layer only).
Before adding a tool, check it's needed: write/edit already cover most node creation/mutation, grep/read cover search/reads, and run_script is the escape hatch for one-offs. New first-class tools should come from recurring needs (recurring run_script scripts in session logs are the roadmap).
Files to edit for a new wire command (the checklist that tests enforce)
src/figma_plugin/src/commands/<domain>.js— the handler function. Takes a singleparamsobject, returns a JSON-serializable result. Runs in BOTH Figma VMs (see constraints below).src/figma_plugin/src/registry/<domain>.js— registry entry:my_command: { lock: "read", handler: (params) => myCommand(params) },lockis the concurrency class:"read"(runs freely),"global"(serialized via global mutex — tree mutations, batch writes),"node"(locks byparams.nodeId— single-node writes). The registry is the single source of truth;main.jsdispatches from it and the remote entry shim (src/figma_plugin/src/remote_entries/<domain>.js) picks the new command up automatically — do not edit the shim.src/figmagent_mcp/remote/domains.ts— add the command toCOMMAND_DOMAINS(command → bundle domain). If it's a pure read, also add it toREMOTE_READ_COMMANDS(controls the atomic-retry suffix on remote errors).src/figmagent_mcp/types.ts— add the wire name to theFigmaCommandunion.tests/registry.test.ts— add the wire name toEXPECTED_COMMANDS, and toEXPECTED_READorEXPECTED_GLOBALif its lock isread/global(anything not in those lists must benode). This test also assertsCOMMAND_DOMAINSmirrors the registry — steps 2/3/5 fail loudly if they drift.src/figmagent_mcp/tools/<domain>.ts— the MCP tool registration (or extend an existing tool's schema — folding an op intoedit/writeis often better than a new tool).- Run
bun run build:plugin(regeneratescode.js),bun test,bun run check.
Files you do NOT edit: src/socket.ts (relay), src/figma_plugin/ui.html (forwarder), src/figma_plugin/src/remote_entries/<domain>.js (auto-derived from the registry), src/figma_plugin/code.js (build artifact — never hand-edit).
New domain instead of new command? Also create src/figma_plugin/src/registry/<newdomain>.js + src/figma_plugin/src/remote_entries/<newdomain>.js (copy an existing shim, swap the import), register the domain in src/figma_plugin/src/registry.js (DOMAINS), and keep the bundle under 40KB (asserted in tests).
Request/Response Lifecycle
Plugin transport:
- tools/
<domain>.ts handler callssendCommandToFigma(wireCommand, params)(from../connection.js) - A UUID is generated, stored in
pendingRequestswith resolve/reject callbacks and a 30s timeout (extended when progress updates arrive) - Message → relay → plugin UI →
code.js, which looks the command up in the registry, acquires the lock, runs the handler - Result (sanitized of
figma.mixedsymbols) flows back and resolves the promise by UUID
Remote transport: the same sendCommandToFigma call routes through remote/executor.ts, which prepends the domain's bundled IIFE, injects params as JSON, awaits globalThis.__figmagent.<command>(params) inside one use_figma script, and returns the JSON result. Scripts are atomic (a thrown error rolls back everything) and queue FIFO per fileKey. sendProgressUpdate is a no-op remotely.
Critical: the wire command string must match EXACTLY across sendCommandToFigma("my_command"), the registry key, COMMAND_DOMAINS, and FigmaCommand. Parameter shapes must agree between the Zod schema and the handler's destructuring — there is no shared schema, just convention (and tests).
MCP tool registration template
server.tool(
"my_new_tool", // agent-facing name
"Description — this is the source of truth the agent reads. State capabilities, call shapes, and constraints here, not in CLAUDE.md.",
{
nodeId: z.string().describe("The ID of the node to modify"),
someValue: z.number().describe("A numeric value"),
},
async ({ nodeId, someValue }: any) => {
try {
const result = await sendCommandToFigma("my_new_tool", { nodeId, someValue });
return { content: [{ type: "text", text: JSON.stringify(result) }] };
} catch (error) {
return {
content: [
{ type: "text", text: `Error: ${error instanceof Error ? error.message : String(error)}` },
],
};
}
}
);For write tools, append formatWarningsBlock(result.warnings) (from ../utils.js) to surface post-write assertion warnings, and consider running runPostWriteAssertions/miniLint in the handler (see commands/create.js / commands/apply.js for the pattern).
Handler constraints (both Figma VMs)
- Async-first:
await figma.getNodeByIdAsync(nodeId), never the sync version;await page.loadAsync()before touching another page's children. - No
?., no??, no object spread ({ ...obj }) insrc/figma_plugin/src/— the VMs reject them and Bun does not transpile them down. UseObject.assign({}, obj). Array spread is fine. Biome enforces part of this. - Strict property guard: the remote VM throws on reading properties that don't exist on a node type. Use
prop(node, "name")(fromhelpers.js) for any duck-typed read at serializer/read boundaries. - Errors state fixes: use
fail(message, fix)fromhelpers.js— no user-facing error without a stated fix. - Font loading before text mutation:
await figma.loadFontAsync(node.fontName)before setting.characters; for mixed fonts use the existingsetCharacters()fromsetcharacters.js. - Immutable property arrays: clone-modify-reassign
.fills/.strokes/.effects(JSON.parse(JSON.stringify(...))); never mutate in place. - Colors are 0–1 floats, opacity separate.
- Type-check before type-specific access:
if (!("fills" in node)) fail(...)orif (node.type !== "TEXT") fail(...). - Return JSON-serializable values only (no Figma objects; run results through
sanitizeSymbolsif they may containfigma.mixed— the registry shim androuteCommanddo this for you on the standard paths).
Batch/chunked pattern (10+ nodes)
Chunk with CHUNK_SIZE = 5: chunks sequential, items within a chunk parallel (Promise.all). Call sendProgressUpdate(commandId, type, status, progress, total, processed, message) per chunk — on the plugin path it resets the server-side inactivity timeout (30s → extended); remotely it's a harmless no-op. params.commandId is injected by sendCommandToFigma. Return { success, totalCount, successCount, failureCount, results } with per-item success/error entries — batches continue past per-op failures.
See setMultipleTextContents in commands/text.js for the canonical implementation.
Helpers available in src/figma_plugin/src/
| Helper (module) | Purpose |
prop(node, name) (helpers) | Strict-guard property read — required for duck-typed reads on the remote VM |
fail(message, fix) (helpers) | Throw an error that states its fix |
sendProgressUpdate(...) (helpers) | Progress through the chain — required for batch ops on the plugin path |
loadFontWithFallback(family, weightOrStyle) (helpers) | Font resolution with fallback chain (weight→style name→Inter Regular) |
setCharacters(node, text, options) (setcharacters) | Font-safe text replacement (mixed fonts) |
sanitizeSymbols(obj) (helpers) | Replace figma.mixed symbols with the string "mixed" |
toNumber(value, fallback), rgbaToHex(color), delay(ms), generateCommandId(), findNodeByIdInTree(nodeId), customBase64Encode(bytes) (helpers) | Utilities |
runPostWriteAssertions(ctx), checkNodes(nodeIds) (assertions) | Post-write structural warnings (balloon, width collapse, FILL-not-applied, font fallback, overlaps) |
matchVariable(...), miniLint(rawSets) (commands/lint) | Write-time exact-match variable suggestions |
Checklist
- Wire command string identical in tools/
<domain>.ts, registry/<domain>.js, remote/domains.ts, types.ts - Registry entry has the right
lock(read/global/node) tests/registry.test.tsEXPECTED lists updated (EXPECTED_COMMANDS always; EXPECTED_READ/EXPECTED_GLOBAL per lock)REMOTE_READ_COMMANDSupdated if the command is a pure read- Handler takes a single params object; param names match the Zod schema
- No
?./??/object-spread;prop()for duck-typed reads;fail(message, fix)for errors - Font loaded before text mutation (if applicable); node type/capability checked
- Batch operations chunked with
sendProgressUpdate() - Tool description carries the full agent-facing knowledge (descriptions are the source of truth, not CLAUDE.md)
bun run build:plugin+bun test+bun run checkall green
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

