# 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](docs/spec.md#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.

## 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 →](GETTING-STARTED.md)**
>
> 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**

```bash
claude mcp add tidy-core -s user -- npx -y tidy-core
```

**Cursor, Windsurf, Claude Desktop**

```json
{
  "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:

```bash
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:

```bash
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](docs/spec.md#9-tidy_plan--implemented).

More in [docs/examples.md](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](docs/spec.md#10-tidy_apply--implemented).

**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](docs/spec.md#the-record-starts-on-install).

## 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](docs/spec.md).

## Development

```bash
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](https://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č](https://github.com/rominak).

## License

MIT