# 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）

## セットアップ

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

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

## Claude Codeへの登録

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

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

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

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

```json
{
  "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 を参照してください。