tailwind-context-resolver-mcp

Resolve e valida classes Tailwind em relação à configuração real do projeto local.

GitHubExperimente este MCPPatrocinado

Documentação

tailwind-context-resolver-mcp 🎨🐸

npm version npm downloads CI License: MIT

Um servidor MCP que carrega o tailwind.config.ts/js do seu projeto e expõe seu sistema de design real para agentes de IA — para que eles parem de alucinar nomes de classes.

🤔 O Problema

Agentes de IA geram classes Tailwind com base em dados de treinamento — a documentação padrão do Tailwind. Seu projeto não é a documentação padrão.

Você tem uma paleta de cores personalizada. Uma escala de espaçamento não padrão. Talvez um prefixo como tw-. Tokens de marca como bg-brand-primary. O agente não sabe nada disso. Ele adivinha.

O 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

O agente não consegue validar o que escreve porque não tem acesso à sua configuração resolvida. Ele está trabalhando com base na memória do tema padrão — não no seu.

✅ A Solução

Este servidor MCP executa o resolvedor Tailwind localmente e dá aos agentes uma interface tipada e consultável para sua configuração real. Antes de escrever um componente, o agente pode perguntar:

  • "Quais cores de marca existem neste projeto?"
  • "p-18 é um valor de espaçamento válido aqui?"
  • "Este projeto usa um prefixo personalizado?"
  • "bg-brand-primary flex grid é uma string de classe válida?"

🛠️ Ferramentas

resolve_theme_tokens

Consulte qualquer namespace no tema Tailwind resolvido. Retorna todos os tokens de design como pares chave-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: [...] }

Use antes de gerar componentes para descobrir quais tokens realmente existem.

validate_class_string

Valida uma string de className do Tailwind contra a configuração resolvida do projeto. Retorna classes válidas, classes inválidas (alucinadas) e avisos de conflito.

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

Use para detectar tokens de design alucinados antes de escrever código.

detect_css_conflicts

Detecta utilitários Tailwind conflitantes — ex.: flex + grid, ou absolute + fixed no mesmo elemento.

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

get_config_summary

Retorna uma visão geral compacta: versão do Tailwind, prefixo, quais seções do tema são personalizadas, plugins ativos.

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

Use primeiro para entender o sistema de design do projeto antes de consultar tokens específicos.

🚀 Configuração

Claude Desktop

Adicione ao seu claude_desktop_config.json:

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

Cursor / VS Code / Qualquer cliente MCP

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

📋 Requisitos

  • Tailwind CSS v3 — a v4 usa um formato de configuração baseado em CSS e não é suportada (o servidor informará claramente)
  • Node.js 18+
  • Um tailwind.config.js ou tailwind.config.ts no seu projeto

🔧 Como Funciona

O servidor usa a mesma estratégia de carregamento de configuração que o CLI do Tailwind:

  1. jiti carrega seu tailwind.config.ts em tempo de execução — sem necessidade de ts-node
  2. tailwindcss/resolveConfig mescla sua configuração com os padrões do Tailwind para produzir o tema resolvido completo
  3. As ferramentas realizam validação de classes baseada em tokens — verificando se bg-brand-primary mapeia para um token colors.brand.primary real — sem executar o pipeline completo de PostCSS/JIT

Essa abordagem é rápida, estável e funciona com qualquer projeto Tailwind v3 sem configuração adicional.

📖 Exemplo de Fluxo de Trabalho do 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 do MCP Toolbelt

Construído junto com:

Licença

MIT