tailwind-context-resolver-mcp

Resuelve y valida las clases de Tailwind contra la configuración real del proyecto local.

GitHubPrueba este MCPPatrocinado

Documentación

tailwind-context-resolver-mcp 🎨🐸

npm version npm downloads CI License: MIT

Un servidor MCP que carga el tailwind.config.ts/js de tu proyecto y expone su sistema de diseño real a los agentes de IA — para que dejen de alucinar nombres de clases.

🤔 El Problema

Los agentes de IA generan clases de Tailwind basándose en datos de entrenamiento — la documentación predeterminada de Tailwind. Tu proyecto no es la documentación predeterminada.

Tienes una paleta de colores personalizada. Una escala de espaciado no estándar. Quizás un prefijo como tw-. Tokens de marca como bg-brand-primary. El agente no sabe nada de esto. Adivina.

El resultado:

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

El agente no puede validar lo que escribe porque no tiene acceso a tu configuración resuelta. Está trabajando desde la memoria del tema predeterminado — no el tuyo.

✅ La Solución

Este servidor MCP ejecuta el resolvedor de Tailwind localmente y les da a los agentes una interfaz tipada y consultable a tu configuración real. Antes de escribir un componente, el agente puede preguntar:

  • "¿Qué colores de marca existen en este proyecto?"
  • "¿Es p-18 un valor de espaciado válido aquí?"
  • "¿Este proyecto usa un prefijo personalizado?"
  • "¿Es bg-brand-primary flex grid una cadena de clases válida?"

🛠️ Herramientas

resolve_theme_tokens

Consulta cualquier espacio de nombres en el tema de Tailwind resuelto. Devuelve todos los tokens de diseño como pares clave-valor planos.

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: [...] }

Úsalo antes de generar componentes para descubrir qué tokens existen realmente.

validate_class_string

Valida una cadena de clases de Tailwind contra la configuración resuelta del proyecto. Devuelve clases válidas, clases inválidas (alucinadas) y advertencias de conflictos.

{
  "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": ""
}

Úsalo para detectar tokens de diseño alucinados antes de escribir código.

detect_css_conflicts

Detecta utilidades de Tailwind en conflicto — p. ej. flex + grid, o absolute + fixed en el mismo elemento.

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

get_config_summary

Devuelve un resumen compacto: versión de Tailwind, prefijo, qué secciones del tema están personalizadas, plugins activos.

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

Úsalo primero para entender el sistema de diseño del proyecto antes de consultar tokens específicos.

🚀 Configuración

Claude Desktop

Añade a tu claude_desktop_config.json:

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

Cursor / VS Code / Cualquier cliente MCP

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

📋 Requisitos

  • Tailwind CSS v3 — v4 usa un formato de configuración basado en CSS y no es compatible (el servidor te lo indicará claramente)
  • Node.js 18+
  • Un tailwind.config.js o tailwind.config.ts en tu proyecto

🔧 Cómo Funciona

El servidor usa la misma estrategia de carga de configuración que la CLI de Tailwind:

  1. jiti carga tu tailwind.config.ts en tiempo de ejecución — no se requiere ts-node
  2. tailwindcss/resolveConfig fusiona tu configuración con los valores predeterminados de Tailwind para producir el tema resuelto completo
  3. Las herramientas realizan validación de clases basada en tokens — verificando que bg-brand-primary se asigne a un token real de colors.brand.primary — sin ejecutar el pipeline completo de PostCSS/JIT

Este enfoque es rápido, estable y funciona con cualquier proyecto de Tailwind v3 sin configuración adicional.

📖 Ejemplo de Flujo de Trabajo del Agente

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

🐸 Parte del MCP Toolbelt

Construido junto a:

Licencia

MIT