tailwind-context-resolver-mcp

tailwind-context-resolver-mcp 🎨🐸

プロジェクトの tailwind.config.ts/js を読み込み、実際のデザインシステムを AI エージェントに提供する MCP サーバーです。これにより、クラス名の幻覚を防ぎます。

---

🤔 問題

AI エージェントは、トレーニングデータに基づいて Tailwind クラスを生成します。つまり、デフォルトの Tailwind ドキュメントが基準です。しかし、あなたのプロジェクトはデフォルトのドキュメントとは異なります。

独自のカラーパレットや、標準外のスペーシングスケールがあるかもしれません。tw- のようなプレフィックスや、bg-brand-primary のようなブランドトークンを使っているかもしれません。エージェントはこうした情報を知りません。推測するしかありません。

その結果は次のとおりです。

// Agent confidently generates this:
<div className="bg-primary-500 text-brand p-18 tw-flex-center">

// Your project has:
// - bg-brand-primary (not bg-primary-500)
// - no "text-brand" token
// - spacing.18 = 4.5rem (ok actually)
// - no "flex-center" utility
// - no "tw-" prefix

エージェントは解決済みの設定にアクセスできないため、生成した内容を検証できません。あなたのテーマではなく、デフォルトのテーマの記憶を頼りに作業しています。

---

✅ 解決策

この MCP サーバーは Tailwind のリゾルバーをローカルで実行し、実際の設定を型付きでクエリ可能なインターフェースとしてエージェントに提供します。コンポーネントを作成する前に、エージェントは次のように質問できます。

• 「このプロジェクトにはどのようなブランドカラーがありますか？」
• 「このプロジェクトでは p-18 は有効なスペーシング値ですか？」
• 「このプロジェクトではカスタムプレフィックスを使っていますか？」
• 「bg-brand-primary flex grid は有効なクラス文字列ですか？」

---

🛠️ ツール

resolve_theme_tokens

解決済みの Tailwind テーマの任意の名前空間をクエリします。すべてのデザイントークンをフラットなキーと値のペアで返します。

namespace: "colors.brand" → { primary: "#3b82f6", secondary: "#8b5cf6", danger: "#ef4444" }
namespace: "spacing"      → { "1": "0.25rem", "2": "0.5rem", "18": "4.5rem", ... }
namespace: "fontFamily"   → { sans: ["Inter", "sans-serif"], mono: [...] }

コンポーネントの生成前に使用して、実際に存在するトークンを確認します。

validate_class_string

プロジェクトの解決済み設定に照らして、Tailwind の className 文字列を検証します。有効なクラス、無効な（幻覚による）クラス、競合の警告を返します。

{
  "valid_classes": ["bg-brand-primary", "text-white", "p-4", "hover:bg-brand-secondary", "flex"],
  "invalid_classes": ["bg-fake-token", "text-brand"],
  "warnings": ["Conflicting multiple layout models: flex, grid"],
  "config_prefix": ""
}

コードを書く前に幻覚によるデザイントークンを検出するために使用します。

detect_css_conflicts

競合する Tailwind ユーティリティを検出します。たとえば、同じ要素上の flex と grid、または absolute と fixed の組み合わせです。

{
  "conflicts": [{ "classes": ["flex", "grid"], "reason": "multiple layout models" }],
  "has_conflicts": true
}

get_config_summary

コンパクトな概要を返します。Tailwind のバージョン、プレフィックス、カスタマイズされているテーマセクション、有効なプラグインを確認できます。

{
  "tailwind_version": "3.4.19",
  "prefix": "",
  "theme_extensions": ["colors", "spacing", "fontFamily"],
  "total_colors": 142,
  "total_spacing": 34,
  "plugins": ["@tailwindcss/forms"]
}

最初に使用して、特定のトークンをクエリする前にプロジェクトのデザインシステムを把握します。

---

🚀 セットアップ

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "tailwind-context-resolver": {
      "command": "npx",
      "args": ["-y", "tailwind-context-resolver-mcp"]
    }
  }
}

Cursor / VS Code / 任意の MCP クライアント

{
  "tailwind-context-resolver": {
    "command": "npx",
    "args": ["-y", "tailwind-context-resolver-mcp"]
  }
}

---

📋 要件

• Tailwind CSS v3 — v4 は CSS ベースの設定形式を使用しており、サポートされていません（サーバーが明確に通知します）
• Node.js 18+
• プロジェクト内に tailwind.config.js または tailwind.config.ts があること

---

🔧 仕組み

このサーバーは Tailwind CLI と同じ設定読み込み方式を使用します。

1. jiti が実行時に tailwind.config.ts を読み込みます。ts-node は不要です
2. tailwindcss/resolveConfig が設定を Tailwind のデフォルト設定とマージし、完全な解決済みテーマを生成します
3. ツールは トークンベースのクラス検証を行います。完全な PostCSS/JIT パイプラインを実行せずに、bg-brand-primary が実在する colors.brand.primary トークンに対応しているかを確認します

この方法は高速で安定しており、追加設定なしであらゆる Tailwind v3 プロジェクトで動作します。

---

📖 エージェントのワークフロー例

1. get_config_summary       → understand the project's design system
2. resolve_theme_tokens     → query specific namespaces before writing classes
   (namespace: "colors.brand", "spacing")
3. validate_class_string    → validate the className string before committing it
4. detect_css_conflicts     → final sanity check for conflicting utilities

---

🐸 MCP ツールベルトの一部

以下のツールとともに開発されました。

• playwright-network-chaos-mcp — Playwright テスト用のネットワーク障害注入
• v8-cpu-profile-decoder-mcp — AI エージェント向けの V8 CPU プロファイル分析

---

ライセンス

MIT