{
  "markdown": "# tailwind-context-resolver-mcp 🎨🐸\n\n[![npm version](https://img.shields.io/npm/v/tailwind-context-resolver-mcp.svg)](https://www.npmjs.com/package/tailwind-context-resolver-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/tailwind-context-resolver-mcp.svg)](https://www.npmjs.com/package/tailwind-context-resolver-mcp)\n[![CI](https://github.com/vola-trebla/tailwind-context-resolver-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vola-trebla/tailwind-context-resolver-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn MCP server that loads your project's `tailwind.config.ts/js` and exposes its **actual design system** to AI agents — so they stop hallucinating class names.\n\n---\n\n## 🤔 The Problem\n\nAI agents generate Tailwind classes based on training data — the default Tailwind docs. Your project is not the default docs.\n\nYou have a custom color palette. A non-standard spacing scale. Maybe a prefix like `tw-`. Brand tokens like `bg-brand-primary`. The agent doesn't know any of this. It guesses.\n\nThe result:\n\n```jsx\n// Agent confidently generates this:\n<div className=\"bg-primary-500 text-brand p-18 tw-flex-center\">\n\n// Your project has:\n// - bg-brand-primary (not bg-primary-500)\n// - no \"text-brand\" token\n// - spacing.18 = 4.5rem (ok actually)\n// - no \"flex-center\" utility\n// - no \"tw-\" prefix\n```\n\nThe agent can't validate what it writes because it has no access to your resolved config. It's working from memory of the default theme — not yours.\n\n---\n\n## ✅ The Fix\n\nThis MCP server runs the Tailwind resolver locally and gives agents a typed, queryable interface to your actual config. Before writing a component, the agent can ask:\n\n- \"What brand colors exist in this project?\"\n- \"Is `p-18` a valid spacing value here?\"\n- \"Does this project use a custom prefix?\"\n- \"Is `bg-brand-primary flex grid` a valid class string?\"\n\n---\n\n## 🛠️ Tools\n\n### `resolve_theme_tokens`\n\nQuery any namespace in the resolved Tailwind theme. Returns all design tokens as flat key-value pairs.\n\n```\nnamespace: \"colors.brand\" → { primary: \"#3b82f6\", secondary: \"#8b5cf6\", danger: \"#ef4444\" }\nnamespace: \"spacing\"      → { \"1\": \"0.25rem\", \"2\": \"0.5rem\", \"18\": \"4.5rem\", ... }\nnamespace: \"fontFamily\"   → { sans: [\"Inter\", \"sans-serif\"], mono: [...] }\n```\n\n**Use before generating components** to discover what tokens actually exist.\n\n### `validate_class_string`\n\nValidates a Tailwind className string against the project's resolved config. Returns valid classes, invalid (hallucinated) classes, and conflict warnings.\n\n```json\n{\n  \"valid_classes\": [\"bg-brand-primary\", \"text-white\", \"p-4\", \"hover:bg-brand-secondary\", \"flex\"],\n  \"invalid_classes\": [\"bg-fake-token\", \"text-brand\"],\n  \"warnings\": [\"Conflicting multiple layout models: flex, grid\"],\n  \"config_prefix\": \"\"\n}\n```\n\n**Use to catch hallucinated design tokens** before writing code.\n\n### `detect_css_conflicts`\n\nDetects conflicting Tailwind utilities — e.g. `flex` + `grid`, or `absolute` + `fixed` on the same element.\n\n```json\n{\n  \"conflicts\": [{ \"classes\": [\"flex\", \"grid\"], \"reason\": \"multiple layout models\" }],\n  \"has_conflicts\": true\n}\n```\n\n### `get_config_summary`\n\nReturns a compact overview: Tailwind version, prefix, which theme sections are customized, active plugins.\n\n```json\n{\n  \"tailwind_version\": \"3.4.19\",\n  \"prefix\": \"\",\n  \"theme_extensions\": [\"colors\", \"spacing\", \"fontFamily\"],\n  \"total_colors\": 142,\n  \"total_spacing\": 34,\n  \"plugins\": [\"@tailwindcss/forms\"]\n}\n```\n\n**Use first** to understand the project's design system before querying specific tokens.\n\n---\n\n## 🚀 Setup\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tailwind-context-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"tailwind-context-resolver-mcp\"]\n    }\n  }\n}\n```\n\n### Cursor / VS Code / Any MCP client\n\n```json\n{\n  \"tailwind-context-resolver\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"tailwind-context-resolver-mcp\"]\n  }\n}\n```\n\n---\n\n## 📋 Requirements\n\n- **Tailwind CSS v3** — v4 uses a CSS-based config format and is not supported (the server will tell you clearly)\n- Node.js 18+\n- A `tailwind.config.js` or `tailwind.config.ts` in your project\n\n---\n\n## 🔧 How It Works\n\nThe server uses the same config loading strategy as the Tailwind CLI:\n\n1. **[`jiti`](https://github.com/unjs/jiti)** loads your `tailwind.config.ts` at runtime — no `ts-node` required\n2. **`tailwindcss/resolveConfig`** merges your config with Tailwind defaults to produce the full resolved theme\n3. Tools perform **token-based class validation** — checking that `bg-brand-primary` maps to an actual `colors.brand.primary` token — without running the full PostCSS/JIT pipeline\n\nThis approach is fast, stable, and works with any Tailwind v3 project without additional configuration.\n\n---\n\n## 📖 Agent Workflow Example\n\n```\n1. get_config_summary       → understand the project's design system\n2. resolve_theme_tokens     → query specific namespaces before writing classes\n   (namespace: \"colors.brand\", \"spacing\")\n3. validate_class_string    → validate the className string before committing it\n4. detect_css_conflicts     → final sanity check for conflicting utilities\n```\n\n---\n\n## 🐸 Part of the MCP Toolbelt\n\nBuilt alongside:\n\n- [playwright-network-chaos-mcp](https://github.com/vola-trebla/playwright-network-chaos-mcp) — network fault injection for Playwright tests\n- [v8-cpu-profile-decoder-mcp](https://github.com/vola-trebla/v8-cpu-profile-decoder-mcp) — V8 CPU profile analysis for AI agents\n\n---\n\n## License\n\nMIT\n",
  "bytes": 5609,
  "sha": "95eea9242be3d0ba0a7964853ec251a9cda886a4ca87c6ac87e9f4d1a1c26290",
  "repo_slug": "vola-trebla/tailwind-context-resolver-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vola_trebla_tailwind_context_r_48195bd6/readme"
}