@unpunnyfuns/swatchbook-mcp 0.19.7 → 0.19.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -40
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,12 +1,10 @@
|
|
|
1
1
|
# swatchbook-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A [Model Context Protocol](https://modelcontextprotocol.io/) server for [swatchbook](https://github.com/unpunnyfuns/swatchbook).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Exposes a DTCG project's tokens, axes, alias chains, and diagnostics to AI agents without running Storybook. Useful for agents doing figma-to-token round-trips, alias-chain navigation, CI lint hooks, AI-assisted token authoring.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
Agents that need to reason about your design tokens — figma-to-token round-trips, alias-chain navigation, CI lint hooks, AI-assisted authoring — without spinning up a Storybook iframe. Point it at a `swatchbook.config.{ts,mts,js,mjs}` or a bare DTCG `resolver.json` and it parses the project on startup, then answers MCP tool calls against the resolved graph.
|
|
7
|
+
Point it at a swatchbook config (or a bare DTCG `resolver.json`) and it parses the project on startup, then answers MCP tool calls against the resolved graph.
|
|
10
8
|
|
|
11
9
|
## Install & run
|
|
12
10
|
|
|
@@ -14,7 +12,7 @@ Agents that need to reason about your design tokens — figma-to-token round-tri
|
|
|
14
12
|
npx @unpunnyfuns/swatchbook-mcp --config swatchbook.config.ts
|
|
15
13
|
```
|
|
16
14
|
|
|
17
|
-
Or wire it into an MCP client
|
|
15
|
+
Or wire it into an MCP client. Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
|
|
18
16
|
|
|
19
17
|
```json
|
|
20
18
|
{
|
|
@@ -27,39 +25,11 @@ Or wire it into an MCP client's config. Claude Desktop (`~/Library/Application S
|
|
|
27
25
|
}
|
|
28
26
|
```
|
|
29
27
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
| Flag | What |
|
|
33
|
-
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
34
|
-
| `--config <path>` | Required. Either a `swatchbook.config.{ts,mts,js,mjs}` (full config) or a DTCG `resolver.json` (bare — other options at defaults). |
|
|
35
|
-
| `--cwd <path>` | Override the working directory for resolving relative `resolver` / `tokens` paths. |
|
|
36
|
-
| `--no-watch` | Disable live-reload. By default the server watches the config + resolved source files and swaps in fresh data on edits. |
|
|
37
|
-
| `--help` | Print usage and exit. |
|
|
38
|
-
|
|
39
|
-
## Tools
|
|
40
|
-
|
|
41
|
-
| Tool | Inputs | Returns |
|
|
42
|
-
| --------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
43
|
-
| `describe_project` | (none) | High-level overview — token counts, axes, themes, presets, diagnostic counts, `$type`s present. |
|
|
44
|
-
| `list_tokens` | `filter?` path glob, `type?` DTCG `$type`, `theme?` name | Array of `{ path, type?, value }` from the named theme (or default). Use first to discover paths. |
|
|
45
|
-
| `search_tokens` | `query`, `theme?`, `limit?` | Case-insensitive substring search across paths, descriptions, and values. Returns matches + `matchedIn` hint. |
|
|
46
|
-
| `resolve_theme` | `tuple`, `filter?`, `type?` | Resolved token map for an axis tuple (`{ mode: "Dark", brand: "…" }`). Fills omitted axes from defaults. |
|
|
47
|
-
| `get_token` | `path` | Full detail: per-theme value, alias chain, aliased-by list, CSS var reference. |
|
|
48
|
-
| `get_alias_chain` | `path` | Forward alias chain per theme (`path → ... → primitive`). Empty when the token is a primitive. |
|
|
49
|
-
| `get_aliased_by` | `path`, `maxDepth?` | Backward alias tree — every token that resolves through this path. Breadth-first with cycle protection; default max depth 6. |
|
|
50
|
-
| `get_consumer_output` | `path`, `tuple?` | CSS var, resolved value, compound `[data-…]` selector + HTML attrs needed to pin the tuple on `<html>`. |
|
|
51
|
-
| `get_color_formats` | `path`, `theme?` | Color token rendered in `hex` / `rgb` / `hsl` / `oklch` / `raw`, each with an `outOfGamut` flag. |
|
|
52
|
-
| `get_color_contrast` | `foreground`, `background`, `theme?`, `algorithm?` | Pair-wise contrast between two color tokens. `wcag21` returns the 1–21 ratio + AA/AAA pass flags (normal + large text); `apca` returns the signed Lc + body / large-text / non-text pass flags. |
|
|
53
|
-
| `get_axis_variance` | `path` | Classify how the token's resolved value depends on each axis. Returns `kind` (`constant` / `single` / `multi`), varying vs constant axes, and a per-axis breakdown with the value seen in each context. |
|
|
54
|
-
| `list_axes` | (none) | Axes + contexts + themes + presets from the project config. |
|
|
55
|
-
| `get_diagnostics` | `severity?` `'error' \| 'warn' \| 'info'` | Parser / resolver / validation diagnostics. |
|
|
56
|
-
| `emit_css` | (none) | Full project stylesheet — `:root` default + per-tuple compound-selector blocks. |
|
|
57
|
-
|
|
58
|
-
Path globs accept `*` (one segment), `**` (any number of segments trailing or mid-path), or exact dot-paths.
|
|
28
|
+
Live-reload is on by default — the server watches the config and resolved source files, swapping in fresh data on edits. Pass `--no-watch` to disable.
|
|
59
29
|
|
|
60
30
|
## Programmatic use
|
|
61
31
|
|
|
62
|
-
|
|
32
|
+
For embedding the MCP handler in a larger toolchain:
|
|
63
33
|
|
|
64
34
|
```ts
|
|
65
35
|
import { createServer, loadFromConfig } from '@unpunnyfuns/swatchbook-mcp';
|
|
@@ -70,8 +40,14 @@ const server = createServer(project);
|
|
|
70
40
|
await server.connect(new StdioServerTransport());
|
|
71
41
|
```
|
|
72
42
|
|
|
73
|
-
##
|
|
43
|
+
## Tools
|
|
44
|
+
|
|
45
|
+
Fourteen read-only tools covering token listing, search, theme resolution, alias chains, color formats + contrast, axis variance, and diagnostics. Full catalogue in the [MCP reference](https://unpunnyfuns.github.io/swatchbook/reference/mcp).
|
|
46
|
+
|
|
47
|
+
## Credits
|
|
48
|
+
|
|
49
|
+
Token parsing and resolver evaluation come from [Terrazzo](https://terrazzo.app/) by the [Terrazzo team](https://github.com/terrazzoapp) via `@unpunnyfuns/swatchbook-core`.
|
|
50
|
+
|
|
51
|
+
## Documentation
|
|
74
52
|
|
|
75
|
-
|
|
76
|
-
- [Project README](../../README.md) — install and wiring flow for the whole toolchain.
|
|
77
|
-
- [Model Context Protocol](https://modelcontextprotocol.io/) — the upstream spec.
|
|
53
|
+
[unpunnyfuns.github.io/swatchbook](https://unpunnyfuns.github.io/swatchbook/) — concepts, guides, and full API reference.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@unpunnyfuns/swatchbook-mcp",
|
|
3
|
-
"version": "0.19.
|
|
3
|
+
"version": "0.19.9",
|
|
4
4
|
"description": "Model Context Protocol server for swatchbook — exposes a DTCG project's tokens, axes, and diagnostics to AI agents without running Storybook.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "unpunnyfuns <unpunnyfuns@gmail.com>",
|
|
@@ -51,7 +51,7 @@
|
|
|
51
51
|
"colorjs.io": "0.6.1",
|
|
52
52
|
"jiti": "^2.4.0",
|
|
53
53
|
"zod": "^3.23.8",
|
|
54
|
-
"@unpunnyfuns/swatchbook-core": "0.19.
|
|
54
|
+
"@unpunnyfuns/swatchbook-core": "0.19.9"
|
|
55
55
|
},
|
|
56
56
|
"devDependencies": {
|
|
57
57
|
"@modelcontextprotocol/inspector": "^0.21.2",
|