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"
    }
  ]
}

設計メモ

Anthropicのmcp-builderスキルの指針に沿っています。

• ツール名はサービス接頭辞付きのsnake_case（tokens_list など）
• 入力はZodスキーマで検証し、制約違反時は「次に何をすべきか」を含むエラーメッセージを返す
• 読み取り系ツールには readOnlyHint / idempotentHint のannotationsを付与
• 出力は structuredContent（構造化データ）とテキストの両方で返す

ライセンス

MIT License. 詳細は LICENSE を参照してください。