MCP 服务器

design-tokens-mcp

Manages design tokens (colors, spacing, fonts) in a JSON file and enables agents to read, write, export, and detect drift between tokens and CSS via MCP.

README

design-tokens-mcp-server

デザイントークン（色・余白・フォント）を1つのJSONファイルで管理し、MCP経由でエージェントに読み書き・書き出し・ドリフト検知をさせる最小構成のMCPサーバーです。

FigmaのMCPサーバー＋Skillエコシステムで注目される「デザイントークンをコードとデザインの間で同期し、ずれ（ドリフト）を検知する」というワークフローを、Figma契約なしで体験できる教材として実装しています。

できること

サーバーは5つのツールを公開します。

ツール	内容
tokens_list	トークン一覧（type / 名前プレフィックスで絞り込み可）
tokens_get	1件取得。名前が違うときは近い候補を提示
tokens_set	追加・更新。型ごとに値を検証（colorはhex、dimensionは単位付き数値など）
tokens_export	css / tailwind / figma-variables 形式で書き出し
tokens_check_drift	CSSファイル内のハードコードされた色・px値をトークンと照合し、ずれを最寄りトークン付きで報告

トークンファイルはW3C Design Tokens（DTCG）風の $type / $value 形式です。tokens.example.json を参照してください。

動作要件

Node.js 18以上（動作確認は v22）

セットアップ

git clone <このリポジトリのURL>
cd design-tokens-mcp
npm install
npm run build
npm test

npm test はビルド済みサーバーをstdioで起動し、5ツールすべて（バリデーションエラーとドリフト検知を含む16項目）を検証します。すべてPASSすれば準備完了です。

Claude Codeへの登録

claude mcp add design-tokens \
  --env TOKENS_FILE=/絶対パス/tokens.json \
  -- node /絶対パス/design-tokens-mcp/dist/index.js

TOKENS_FILE を省略するとカレントディレクトリの tokens.json を使います。初回は tokens.example.json をコピーして始めてください。

cp tokens.example.json tokens.json

他のMCPクライアント（Cursor等）でも、stdioサーバーとして node dist/index.js を登録すれば動きます。

使用例

エージェントへの指示例：

「トークン一覧を見せて」→ tokens_list
「spacing.xl を 32px で追加して」→ tokens_set（32 だけを渡すと単位がないためエラーになり、修正方法が返ります）
「トークンをCSS変数に書き出して styles/tokens.css に保存して」→ tokens_export
「src/app.css がトークンからずれていないか調べて」→ tokens_check_drift

ドリフト検知の出力例（実際の実行結果）：

{
  "checked_file": "/tmp/sample.css",
  "matched": 2,
  "drift_count": 2,
  "drift": [
    {
      "value": "#0e7a6f",
      "line": 3,
      "kind": "color",
      "nearest_token": "color.primary",
      "nearest_value": "#0F766E"
    },
    {
      "value": "23px",
      "line": 5,
      "kind": "dimension",
      "nearest_token": "spacing.lg",
      "nearest_value": "24px"
    }
  ]
}