tailwind-context-resolver-mcp

tailwind-context-resolver-mcp 🎨🐸

一个 MCP 服务，可加载项目的 tailwind.config.ts/js，并向 AI Agent 暴露实际设计系统，让它们不再臆造类名。

---

🤔 问题所在

AI Agent 根据训练数据（Tailwind 默认文档）生成 Tailwind 类。你的项目并非使用默认文档。

你有自定义调色板、非标准间距比例，也许还有 tw- 这样的前缀，以及 bg-brand-primary 这样的品牌令牌。Agent 对这些一无所知，只能猜测。

结果如下：

// 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

Agent 无法验证自己写下的内容，因为它无法访问解析后的配置。它依赖的是对默认主题的记忆，而不是你的主题。

---

✅ 解决方案

此 MCP 服务会在本地运行 Tailwind 解析器，并提供一个类型化、可查询的接口，让 Agent 访问实际配置。在编写组件之前，Agent 可以询问：

• “这个项目有哪些品牌颜色？”
• “这里的 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. 各工具执行基于令牌的类验证——检查 bg-brand-primary 是否映射到实际的 colors.brand.primary 令牌，而无需运行完整的 PostCSS/JIT 流程

这种方法快速、稳定，无需额外配置即可适用于任何 Tailwind v3 项目。

---

📖 Agent 工作流示例

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 Agent 分析 V8 CPU 配置文件

---

许可证

MIT