CSS is Awesome

MCP server

cia ships a Model Context Protocol stdio server at mcp/server.cjs. Any MCP-aware client — Claude Code, Cursor, Aider, Gemini, Copilot — can connect to it and discover cia’s entire surface without grep-walking the repo. Pure filesystem scan; no database, no build step.

Setup

Add cia to your client’s .mcp.json:

{
  "mcpServers": {
    "css-is-awesome": {
      "command": "node",
      "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
    }
  }
}

Or run it directly via the wired-in bin:

npx css-is-awesome-mcp

The MCP SDK is an optional peer dependency — install it in the client’s project if you want to actually run the server:

npm install -D @modelcontextprotocol/sdk zod

Tools — 30 total: 28 across 8 families + 2 specialty tools

Every tool returns structured JSON. list_* tools return catalogs; get_* tools return a single record; search_* tools run keyword search across the catalog and return ranked matches.

FamilyToolsWhat it surfaces
Themeslist_themes, get_theme, search_themesAll 24 shipped themes (eight families × auto / light / dark) with full token assignments + raw SCSS
Mixinslist_mixins, get_mixin, search_mixins150 public mixins (core, layout, animation, icons, generator + per-component) with signature, doc, body, line range
Functionslist_functions, get_function, search_functions24 public @functions (color, space, radius, shadow, font-size, z, …)
Tokenslist_tokens, get_token, search_tokens127 required + 36 optional contract tokens. get_token returns sample values across themes plus the list of mixins/functions that reference it
Animationslist_animations, get_animation12-slug vocabulary, 3 speeds, 4 hover effects, the animate / animate-on mixin records
Componentslist_components, get_component, search_components10 component files (accordion, buttons, copy-button, data, feedback, forms, navigation, overlay, stepper, tabs) with all their mixins
Recipeslist_recipes, get_recipeRecipes under scss/recipes/ — both markdown pattern recipes (dialog, combobox, print-to-pdf) and opt-in SCSS recipes (e.g. bare-tags, consumed via @use)
Docsread_llm_txt, read_changelog, read_migration, read_theming, read_agents, read_contract, read_three_tiers, read_readme, read_versioningFull markdown bodies of every top-level doc

assemble_prompt

The headline tool. Pass an intent string and get back a ready-to-paste context block tailored for the next AI generation call. Bundles the relevant mixins, tokens, and docs into one prompt — no need to call N separate get_* tools.

Recognized intents:

resolve_size

Snap a design px value to cia's 4px geometric grid. The other AI-facing tool besides assemble_prompt. Returns the step number, the SCSS call to emit (cia.grid(n) when exactly on-grid; cia.px(value) when off-grid), the equivalent rem, and a human-readable note.

Contract for AI agents: call this whenever you receive a px value from a design tool (Figma, mockup, screenshot) and need to express it in cia code. NEVER write raw rem/px literals when a cia function applies. See the composition decision tree for the full rules.

// AI receives "24px button height" from a Figma design
resolve_size({ px: 24 })
// →  { step: 6, exact: true, rem: 1.5, scssCall: "cia.grid(6)", ... }
//
// AI emits in generated SCSS:
//   .my-btn { height: cia.grid(6); }

// Off-grid case: AI receives "17px hero margin"
resolve_size({ px: 17 })
// →  { step: 4, exact: false, rem: 1, scssCall: "cia.px(17)",
//      alternative: "cia.grid(4)  // snaps to 16px (1rem)", ... }
//
// AI follows the note: prefer the snapped grid value unless the
// design intent specifically requires the off-grid value.

Security + portability

Discovery is pure filesystem scan. The server reads files inside the cia package directory and never writes anything. Safe to run from any clone or installed node_modules/css-is-awesome/. No network, no telemetry, no eval. The MCP transport is stdio — your client connects over a pipe, not a port.

Versioning

The MCP server ships in the cia package itself; its version is cia’s version. When cia’s mixin API changes, the server reports the new API on the next read. No separate semver, no client config to update.

Theme