tidy-core
tidy-core is a Figma design-system governance MCP server that lets you inspect a design system, plan and apply safe variable changes with decision records, and explicitly avoids guessing which file to write to.
Check connection status (
tidy_status): shows where tidy-core is connected and where the next command will land, with concrete fixes when nothing is connected.Set or clear the working file (
tidy_target): pin all subsequent commands to one connected Figma file by name or key; when no target is set and multiple files are connected, commands fail with a list instead of guessing.Load the design system contract (
tidy_context): returns collections, modes, token names grouped by intent, component variant axes, and naming/binding conventions actually in use.Build reviewable change plans (
tidy_plan): create a non-mutating plan for variable operations (rename, delete, set description), see dependencies and risks, and get a plan hash.Execute plans safely (
tidy_apply): apply a plan only by its hash, only with explicit confirmation, and only if targets haven't changed; writes a decision entry recording what and why.Registered but not yet implemented (
tidy_health,tidy_adoption,tidy_drift,tidy_impact,tidy_cleanup,tidy_decisions,tidy_record_decision,tidy_gate): these are available in the tool list but explicitly refuse with “not built yet” rather than returning empty results.
Provides governance and health monitoring for Figma design systems, offering tools to assess adoption, drift, impact, and decision history rather than authoring components.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tidy-core show adoption trends for the Button component"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tidy-core
Other Figma MCP servers let an agent change your design system. tidy-core tells you whether it should, what will break, whether anyone adopted the last change, and what you decided six months ago.
Design system governance over the Model Context Protocol. Thirteen tools, not a hundred.
Status: v0.3.0, early. Five of the thirteen tools are implemented, including the plan/apply pair that makes changes reviewable. The other eight are registered and will tell you they are not built yet rather than returning an empty result. See the build sequence.
Why this exists
Reading and writing Figma from an agent is a solved problem. Figma ships a first-party MCP server, and there are good third-party ones with a hundred-plus tools.
What none of them do is answer the question a design system lead actually gets asked: is this working, and is it worth the headcount?
You can show a component count. You cannot show adoption, drift, decision history, or the cost of the next migration. So the system gets judged on output volume, which is the one metric that rewards the wrong behaviour.
tidy-core is built for that gap. It is not a faster way to draw components.
Related MCP server: design-architect-mcp
What it does
Capability | The question it answers |
Decision record | Why is the system like this? Which decisions now contradict each other? |
Longitudinal health | Is it improving or decaying, and which category moved? |
Adoption evidence | Do designers use the components, or detach and override them? |
Blast radius | What breaks if I rename this token, and what will the migration cost? |
Drift and parity | Does the design still match code, Storybook, and the docs? |
CI enforcement | Does this change violate a recorded decision? Block it. |
What it does not do
Not a design-to-code generator. Figma's own MCP server does that well.
Not a way to author components faster. Other servers do that well.
Not a tool-count competition. The small surface is the point.
It is designed to sit alongside an authoring MCP server, not replace one. Use those to make the change. Use this to decide whether to make it, and to prove what happened.
Install
👋 New to this?
Read the step-by-step guide instead →
It assumes no coding experience, explains every term, and tells you what should happen after each step. About 20 minutes.
The short version, for people who have set up an MCP server before.
Requires Node 18+ and Figma Desktop. A browser tab cannot reach a localhost WebSocket, and there is no workaround.
1. Add the server
Claude Code
claude mcp add tidy-core -s user -- npx -y tidy-coreCursor, Windsurf, Claude Desktop
{
"mcpServers": {
"tidy-core": {
"command": "npx",
"args": ["-y", "tidy-core"]
}
}
}Nothing to clone and nothing to build. Pin a version with tidy-core@0.3.0 if you would rather a governance tool did not change under you between sessions.
2. Add the Figma plugin
The server talks to Figma through a small plugin, which needs a folder that stays where you put it. Figma stores the path you import from, and an npm cache directory is not somewhere to point it. So this step does want the repo:
git clone https://github.com/rominak/tidy-core.gitFigma Desktop → Plugins → Development → Import plugin from manifest
Select
plugin/manifest.jsonfrom the folder you just clonedRun it. It scans ports 9240 to 9249 and connects on its own.
Verify:
Check tidy statusRunning from source instead
For contributing, or to pin to a specific commit:
git clone https://github.com/rominak/tidy-core.git
cd tidy-core
npm install
npm run buildThen point your client at the build rather than at npx: command node, args ["/absolute/path/to/tidy-core/dist/index.js"].
First run
Load the design system contract.tidy_context returns collections, modes, token names grouped by intent, component variant axes, and the naming conventions actually in use, inferred from your data rather than asserted.
Changing something
Every change goes through the same two steps. tidy_plan tells you what depends on the thing you are about to touch and hands back a hash. tidy_apply takes that hash, checks nothing moved underneath it, and writes a decision entry.
Point color/background/raised at blue/600 in Dark mode.Plan 3f9c2a1b04e7 Point "color/background/raised" (Dark) at "blue/600"
color/background/raised COLOR · Theme · Light, Dark
4 alias references · 212 layer bindings
blue/600 COLOR · Primitives
low "blue/600" is itself an alias, so "color/background/raised"
will sit two levels from a raw value.
To execute: tidy_apply with planHash "3f9c…" and confirm: true.The six operations a plan can contain are createVariable, renameVariable, setVariableDescription, setVariableValue, aliasVariable and deleteVariable, all scoped to variables. Each has its own blocking conditions: you cannot delete a variable something still uses, alias across mismatched types, create a name that already exists, or write a value that does not match the variable's type. The full table is in the spec.
More in docs/examples.md.
Design decisions worth knowing
It refuses to guess which file you mean. With two or more Figma files connected and no target set, commands fail with a list of the files instead of picking the first open socket. Picking is a coin flip, and losing it writes to the wrong file. Set one with tidy_target.
It tags every response. Real setups run several Figma MCP servers side by side. Every response carries _mcp: "tidy-core" and every error is prefixed [tidy-core], so another server's failure is never blamed on this one.
Unbuilt tools say so. The eight planned tools are registered and return an explicit refusal naming what they will do. A tool that silently returns {} is worse than one that admits it does not exist yet.
It will not kill your other tools. If port 9240 is busy it moves to the next free one in 9240 to 9249, which the plugin scans anyway. It deliberately does not terminate whatever was holding the port.
New capability arrives as an operation, never as an escape hatch. There is no execute tool and there will not be one. Every operation tidy_plan accepts earns impact analysis, a hash gate and a decision entry; arbitrary code earns none of those, and would immediately become the easiest path for exactly the changes that most needed reviewing. The cost is that a capability tidy-core does not have yet takes a release rather than a prompt. That is the deal. Reasoning.
Reads will write. Once tidy_health and tidy_adoption land, every call persists a snapshot. That is what makes the second run able to show a delta without anyone scheduling anything. A noCapture flag will exist for read-only CI checks. See the reasoning.
The thirteen tools
Tool | Status | Question |
| ✅ | Where am I connected, and where will the next command land? |
| ✅ | Which file am I working in? |
| ✅ | What is in this system, so I can work correctly? |
| 🚧 | How healthy is it, and which direction is it moving? |
| 🚧 | Is anyone actually using it? |
| 🚧 | Does design still match code, Storybook, docs? |
| 🚧 | What breaks if I change this? |
| 🚧 | What should I fix first? |
| ✅ | Give me a safe, reviewable sequence of changes. |
| ✅ | Execute the plan I reviewed. |
| 🚧 | Why is it like this, and do our decisions contradict? |
| 🚧 | Capture why we did this. |
| 🚧 | Should this change be allowed to merge? |
Full definitions in docs/spec.md.
Development
npm install
npm run build # emits dist/, excludes tests
npm test
npm run typecheck # checks everything including tests
npm run dev # watch modeEverything runs locally. No data leaves your machine, and there is no telemetry.
Learn more
tidy-core comes out of ongoing work on design systems and AI at aidesign.guide, where the thinking behind it is written up in more depth: how design systems get measured, where AI actually helps, and where it quietly makes things worse.
Built by Romina Kavčič.
License
MIT
Available Tools
13 toolstidy_adoptionC
[NOT IMPLEMENTED YET] Instance counts, detach rate, override patterns, variant entropy, and the correlation between adoption and health. Persists a measurement on every call, which is what builds the series.
Inputs: no named parameters.
tidy_applyA
Execute a plan produced by tidy_plan, identified by its hash. This is the only tool in tidy-core that changes anything. It refuses plans it did not generate, plans that have expired, and plans whose targets have changed since the plan was built. On success it writes a decision entry recording what changed and why.
Inputs: confirm (required), planHash (required), note, figmaFile.
tidy_cleanupB
[NOT IMPLEMENTED YET] A ranked worklist: ghost variables, dead styles, unused tokens, raw colors, deprecation candidates. Ranked by impact over effort, not by count.
Inputs: no named parameters.
tidy_contextA
Get the design system contract in one call: collections, modes, token names grouped by intent, component variant axes, and the naming and binding conventions actually in use. Call this before writing anything into the file. Without it an agent guesses token names, and guessed names are how raw hex ends up in a component.
Inputs: detail, include, figmaFile.
tidy_decisionsA
[NOT IMPLEMENTED YET] Search the decision record, find components with no recorded rationale, and detect decisions that contradict each other. Read-only.
Inputs: no named parameters.
tidy_driftD
[NOT IMPLEMENTED YET] One drift report across four surfaces: design versus code specs, versus Storybook, versus docs, and page-to-page inside the file.
Inputs: no named parameters.
tidy_gateA
[NOT IMPLEMENTED YET] CI and pre-push verdict. Runs drift, cleanup regressions, publish readiness and decision compliance, then passes or fails with reasons.
Inputs: no named parameters.
tidy_healthA
[NOT IMPLEMENTED YET] Six-category health score plus the delta since the last snapshot plus what caused the delta. Persists a snapshot on every call, so the second run has a delta.
Inputs: no named parameters.
tidy_impactB
[NOT IMPLEMENTED YET] Blast radius for a token, component or style. What breaks if you rename it, what the migration costs, what the regression risk is. Read-only.
Inputs: no named parameters.
tidy_planA
Build a reviewable plan for a set of changes, and return a hash for it. Never mutates anything. For each target it reports what depends on it (alias references and layer bindings) and flags the risks, including refusing to issue a hash at all when an operation would break something. Pair with tidy_apply, which is the only tool that can execute the plan.
Inputs: operations (required), intent, figmaFile.
tidy_record_decisionA
[NOT IMPLEMENTED YET] Record why a change was made. Called automatically by tidy_apply, and manually when a decision happens in a meeting rather than in a diff.
Inputs: no named parameters.
tidy_statusA
Check where tidy-core is connected and where the next command will land. Read the routing field first: it says in plain language which Figma file commands go to. When nothing is connected it returns concrete fixes rather than just connected: false.
Inputs: no named parameters.
tidy_targetA
Pin every subsequent command to one connected Figma file. Accepts a file name (for example 'Design System') or a file key. Call with no arguments to see the current target, or clear: true to unpin. When several files are connected and no target is set, commands fail with a list of the files rather than guessing, because guessing means writing to the wrong file.
Inputs: file, clear.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Tools like tidy_plan and tidy_apply have clear separation (read vs. execute), and tidy_status/tidy_target handle connection vs. targeting. However, some tools like tidy_health, tidy_impact, and tidy_cleanup all involve analysis of the design system, and their distinct purposes might not be immediately obvious without reading descriptions closely, though descriptions do help.
All tools use the pattern 'tidy_' prefix followed by a lowercase verb or noun in snake_case, e.g., tidy_status, tidy_target, tidy_plan, tidy_apply. This is perfectly consistent and predictable.
13 tools is within the recommended range. However, 8 of them are marked as not implemented yet, which might make the server feel thin in terms of actual functionality, but the planned surface is of appropriate size for a comprehensive design system management toolkit.
The implemented tools cover status, targeting, context, planning, and applying changes, which are core operations. However, many permanent capabilities like adoption, drift, health, impact, cleanup, decisions, and gating are not yet implemented, leaving notable gaps in the intended functionality.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Monitor MCP servers, API contracts and AI outputs for schema drift. Alerts on breaking changes.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Governed MCP workflow automation for MSPs and agencies: approvals, durable state, signed evidence.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI coding environments to enforce engineering governance through MCP tools and resources for init, check, route, and review workflows.10 npm2MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that exposes a design system and UX rulebook as tools, enabling AI to generate UI consistent with your design tokens, components, layout rules, accessibility guidelines, and templates. It also provides a review tool to score UI proposals against the design system.MIT
- FlicenseNot gradedqualityCmaintenanceProvides governed MCP tools for a controlled, AI-assisted asset-change pipeline, featuring natural-language requests, mandatory approvals, execution-time revalidation, and complete audit.-
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to access a governed, versioned design style specification through MCP, including deterministic checks, proposal review workflows, and generated CSS, JSON, and TypeScript artifacts.Apache 2.0