Skip to main content
Glama
tidy-core

tidy-core

by rominak

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-core

Cursor, 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.git
  1. Figma Desktop → Plugins → Development → Import plugin from manifest

  2. Select plugin/manifest.json from the folder you just cloned

  3. Run it. It scans ports 9240 to 9249 and connects on its own.

Verify:

Check tidy status

Running 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 build

Then 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

tidy_status

✅

Where am I connected, and where will the next command land?

tidy_target

✅

Which file am I working in?

tidy_context

✅

What is in this system, so I can work correctly?

tidy_health

🚧

How healthy is it, and which direction is it moving?

tidy_adoption

🚧

Is anyone actually using it?

tidy_drift

🚧

Does design still match code, Storybook, docs?

tidy_impact

🚧

What breaks if I change this?

tidy_cleanup

🚧

What should I fix first?

tidy_plan

✅

Give me a safe, reviewable sequence of changes.

tidy_apply

✅

Execute the plan I reviewed.

tidy_decisions

🚧

Why is it like this, and do our decisions contradict?

tidy_record_decision

🚧

Capture why we did this.

tidy_gate

🚧

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 mode

Everything 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 tools
tidy_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

    B3.2/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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