css-is-awesome 1.12.0 → 1.13.0

package/AGENTS.md

@@ -308,9 +308,24 @@ Inside this package (all whitelisted in `files`):
 
 ## MCP server (SHIPPED — use it)
 
-cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome` (version read from package.json), protocol `2024-11-05`) at `mcp/server.cjs`, exposed as the `css-is-awesome-mcp` bin. It's in the `files` manifest, so it lands in every consumer's `node_modules`. **Prefer querying it over guessing** — it returns cia's real mixin signatures, tokens, themes, and recipes.
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`. It's in the `files` manifest, so it lands in every consumer's `node_modules`. **Prefer querying it over guessing** — it returns cia's real mixin signatures, tokens, themes, and recipes.
 
-Wire it into your MCP client's `.mcp.json`:
+Two ways to run it — prefer the dedicated `npx css-is-awesome-mcp` package (zero install, SDK is a real dependency, no separate peer-install step):
+
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "npx",
+      "args": ["css-is-awesome-mcp"]
+    }
+  }
+}
+```
+
+No install step needed — `npx` fetches it on first run. To pin an exact version instead, `npm install css-is-awesome-mcp` first; `npx` then uses that local copy.
+
+Or run this in-repo copy directly — needs its SDK peer deps installed manually first (`npm install -D @modelcontextprotocol/sdk zod` in the client project, since they're optional peers):
 
 ```json
 {
@@ -323,7 +338,7 @@ Wire it into your MCP client's `.mcp.json`:
 }
 ```
 
-The SDK is an optional peer dep — `npm install -D @modelcontextprotocol/sdk zod` in the client project to run it. It exposes **30 tools** across 8 families:
+Either way it exposes **30 tools** across 8 families:
 
 - **Themes** — `list_themes`, `get_theme`, `search_themes`
 - **Mixins** — `list_mixins`, `get_mixin`, `search_mixins` (real signatures — don't guess)

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.13.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.12.1...v1.13.0) (2026-09-11)
+
+
+### Features
+
+* **mcp:** add derive-theme:<base> intent to assemble_prompt ([576dfcb](https://github.com/Jerry2d3d/css-is-awesome/commit/576dfcb80363f281d13ecf0c9218de8915de6595))
+
+## [1.12.1](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.12.0...v1.12.1) (2026-09-11)
+
+
+### Bug Fixes
+
+* **mcp:** remove colliding css-is-awesome-mcp bin entry, point docs at the new package ([f2ac41c](https://github.com/Jerry2d3d/css-is-awesome/commit/f2ac41c4d6056a1d13c19c5dcb48386acfb0fcda))
+
 # [1.12.0](https://github.com/Jerry2d3d/css-is-awesome/compare/v1.11.1...v1.12.0) (2026-09-11)
 
 

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm](https://img.shields.io/npm/v/css-is-awesome?logo=npm&color=cb3837)](https://www.npmjs.com/package/css-is-awesome) [![CI](https://github.com/Jerry2d3d/css-is-awesome/actions/workflows/ci.yml/badge.svg)](https://github.com/Jerry2d3d/css-is-awesome/actions/workflows/ci.yml) [![Node](https://img.shields.io/badge/node-%E2%89%A520-43853d?logo=node.js&logoColor=white)](./package.json) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![semantic-release](https://img.shields.io/badge/semantic--release-enabled-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
 
-**Bring your own selectors. We bring the design system.** One CSS file per theme — drop it in and the page restyles, no markup change. 24 themes. Zero JavaScript in the npm package. Six browser-native interactive components. Small enough to read in an afternoon.
+**Bring your own components. Bring your own selectors. We bring the design system.** No component library to fight, in React, Vue, Angular, Svelte, Web Components, Razor, SharePoint, or plain HTML — cia styles the markup you already own. One CSS file per theme — drop it in and the page restyles, no markup change. 24 themes. Zero JavaScript in the npm package. Six browser-native interactive components. Small enough to read in an afternoon.
 
 **Docs:** [cssisawesome.com](https://cssisawesome.com/) · **Install:** `npm install css-is-awesome`
 
@@ -16,22 +16,18 @@
 
 **Then connect the MCP server** and stop guessing at signatures. It answers from the real source — 30 tools covering themes, mixins, functions, tokens, recipes and components.
 
-```bash
-npm install -D @modelcontextprotocol/sdk zod   # required — npm will NOT install these for you
-```
-
 ```json
 {
   "mcpServers": {
     "css-is-awesome": {
-      "command": "node",
-      "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
+      "command": "npx",
+      "args": ["css-is-awesome-mcp"]
     }
   }
 }
 ```
 
-The SDK and `zod` are declared as *optional* peer dependencies, so a plain `npm install css-is-awesome` skips them and the server exits with `@modelcontextprotocol/sdk is not installed`. Install both. `npx css-is-awesome-mcp` does **not** work around this — npx fetches the package but not its optional peers.
+That's the whole setup — [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) is a dedicated zero-install package, no manual dependency step. `npx` fetches and caches it on first run with no install command needed; if you'd rather pin an exact version in your own `package.json`/lockfile, `npm install css-is-awesome-mcp` works too — `npx` then uses the locally installed copy instead of fetching. (The in-repo copy at `mcp/server.cjs` still works too, if you'd rather not add a second package — see the MCP section below for that path, which needs `npm install -D @modelcontextprotocol/sdk zod` first since those are optional peers here.)
 
 Why it matters more here than for older frameworks: no model has memorised cia's API the way it has memorised Tailwind's class names. Without `llm.txt` or MCP, an agent will confidently invent a Tailwind-shaped API. With them, it reads the real thing. Details at [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
 
@@ -298,30 +294,43 @@ The scope is kept narrow: 8 `!important` declarations, all inside `@media print`
 
 ## MCP server (for AI agents)
 
-cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) at [`mcp/server.cjs`](./mcp/server.cjs), exposed as the `css-is-awesome-mcp` bin. It's in the `files` manifest, so it lands in every consumer's `node_modules`. Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Exposes **30 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) and `resolve_size` (snap design px values to cia's 4px grid). Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
+cia ships a Model Context Protocol stdio server (JSON-RPC over stdio, protocol `2024-11-05`) exposing **30 tools** across 8 families (themes, mixins, functions, tokens · 127 required of them, animations, components, recipes, doc readers) plus `assemble_prompt` (context bundles) and `resolve_size` (snap design px values to cia's 4px grid). Any MCP-aware client (Claude Code, Cursor, Aider, Gemini, Copilot) can then query cia's real design system — mixin signatures, tokens, themes, recipes — instead of guessing, without grep-walking the repo. Full reference: [`/docs/mcp`](https://cssisawesome.com/docs/mcp/).
+
+**Recommended — zero install:** use the dedicated [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package. It depends on `css-is-awesome` and resolves your installed version's real source, so it's never out of sync — and the MCP SDK ships as a real dependency, not an optional peer you have to remember to add.
 
-**Setup is two steps — do both, or the server won't start.**
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "npx",
+      "args": ["css-is-awesome-mcp"]
+    }
+  }
+}
+```
 
-1. Install the SDK peer deps. The MCP SDK needs `@modelcontextprotocol/sdk` + `zod`; they're declared as *optional* peers so npm skips them by default. Without them the server exits and your MCP client shows only a generic "failed to connect":
+No install command required — `npx` fetches and caches the package the first time your MCP client runs it. Prefer a pinned version in your own lockfile instead? `npm install css-is-awesome-mcp` works the same way as any other dependency; `npx` then runs the locally installed copy rather than fetching one:
 
-   ```bash
-   npm install -D @modelcontextprotocol/sdk zod
-   ```
+```bash
+npm install css-is-awesome-mcp
+```
 
-2. Add to your client's `.mcp.json` (the `npx` form uses the shipped bin and is CWD-independent):
+**Alternative — the copy already in your `node_modules`:** cia's own `files` manifest ships [`mcp/server.cjs`](./mcp/server.cjs) too, for anyone who'd rather not add a second package. This copy needs its SDK peer deps installed manually first, since they're declared as *optional* peers (so a plain `npm install css-is-awesome` doesn't pull JS into a CSS-only install):
 
-   ```json
-   {
-     "mcpServers": {
-       "css-is-awesome": {
-         "command": "npx",
-         "args": ["css-is-awesome-mcp"]
-       }
-     }
-   }
-   ```
+```bash
+npm install -D @modelcontextprotocol/sdk zod
+```
 
-   Equivalent explicit path: `"command": "node", "args": ["node_modules/css-is-awesome/mcp/server.cjs"]`.
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "node",
+      "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
+    }
+  }
+}
+```
 
 ## Docs site
 
@@ -399,7 +408,7 @@ Full detail: [`/docs/testing`](https://cssisawesome.com/docs/testing/).
 
 **Stable, [published on npm](https://www.npmjs.com/package/css-is-awesome)** (first published 2026-09-01). The mixin API, functions, token contract, and theme architecture are stable and under strict SemVer — breaking changes require a major bump. See [`VERSIONING.md`](./VERSIONING.md) for the policy.
 
-The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, and the 30-tool MCP server. The npm package ships ZERO JavaScript by hard rule.
+The 1.0 surface is the v0.8 mixin-first reframe — twelve mixin renames, theme system collapsed to 8 single-file theme families, six zero-JS components, intrinsic-layout vocabulary, opt-in utilities — plus the recipes book, the Tailwind/Bootstrap migration on-ramp, print/PDF support, and the 30-tool MCP server (now also available zero-install via the companion [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package). The npm package ships ZERO JavaScript by hard rule.
 
 See [CHANGELOG.md](./CHANGELOG.md) for the full history and [MIGRATION.md](./MIGRATION.md) for the v0.7 → v0.8 upgrade path.
 

package/bin/README.md

@@ -6,19 +6,19 @@ cia's CLI entry points. **These are the only JavaScript files cia ships** — th
 
 | Bin | File | What it does |
 |---|---|---|
-| `css-is-awesome-mcp` | `../mcp/server.cjs` | MCP stdio server for AI agents (themes, mixins, recipes, etc.) |
-| `cia` | `./cia.cjs` | The CLI router — `migrate` (tailwind/bootstrap), `add` (recipe registry), `analyze` (design-system health) |
+| `cia` | `./cia.cjs` | The CLI router — `migrate` (tailwind/bootstrap/mui/chakra), `add` (recipe registry), `analyze` (design-system health) |
 
-Invoke either via `npx` from a consumer project that has cia installed:
+Invoke via `npx` from a consumer project that has cia installed:
 
 ```bash
-npx css-is-awesome-mcp        # MCP server (stdio; configure via .mcp.json)
 npx cia --help                # CLI help
 npx cia migrate tailwind ./tailwind.config.js
 npx cia add bottom-nav        # copy a recipe into the project — own the pattern
 npx cia analyze src/styles    # health check: dead symbols, space() trap, hex, BEM
 ```
 
+**MCP server is NOT registered here** — `../mcp/server.cjs` ships in the `files` manifest but deliberately has no `bin` entry. It used to (`css-is-awesome-mcp`), but that collided with the separate [`css-is-awesome-mcp`](https://www.npmjs.com/package/css-is-awesome-mcp) package's own identically-named bin: since that package depends on `css-is-awesome`, npm links both packages' bins into the same `node_modules/.bin/`, and whichever wins is undefined — in practice it silently ran this repo's copy instead of the dedicated package's. Removed here so there's exactly one owner of that command name. Run this in-repo copy directly via `node mcp/server.cjs` (see the README's MCP section for both invocation paths).
+
 ## Subcommand files
 
 `cia.cjs` is the router. Each subcommand lives in its own sibling file and is loaded lazily so consumers who only use one path don't pay the require cost of the others.

package/llm.txt

@@ -128,22 +128,28 @@ Newspaper by day, hacker terminal by night. Most design systems give you dark mo
 
 ## MCP server (shipped 2026-05-22)
 
-cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome` (version read from package.json), protocol `2024-11-05`) at `mcp/server.cjs`, exposed as the `css-is-awesome-mcp` bin and included in the `files` manifest — so it lands in every consumer's `node_modules`. **30 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 36 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling and `resolve_size` for snapping design px values to cia's 4px geometric grid (AI agents: call this whenever you receive a px value from a design tool). Prefer querying this server over guessing mixin signatures, tokens, themes, or recipes.
+cia ships an MCP stdio server (JSON-RPC over stdio, `serverInfo` name `css-is-awesome`, protocol `2024-11-05`) at `mcp/server.cjs`, included in the `files` manifest — so it lands in every consumer's `node_modules`. **30 tools** across 8 resource families: themes, mixins, functions, tokens (127 required + 36 optional), animations, components, recipes, doc readers. Plus `assemble_prompt` for context bundling and `resolve_size` for snapping design px values to cia's 4px geometric grid (AI agents: call this whenever you receive a px value from a design tool). Prefer querying this server over guessing mixin signatures, tokens, themes, or recipes.
 
-Add to your MCP client's `.mcp.json`:
+**Recommended: suggest the dedicated `css-is-awesome-mcp` package** — zero install,
+SDK ships as a real dependency, no separate peer-install step:
 ```json
 {
   "mcpServers": {
     "css-is-awesome": {
-      "command": "node",
-      "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
+      "command": "npx",
+      "args": ["css-is-awesome-mcp"]
     }
   }
 }
 ```
-**Two dependencies are required and npm will NOT install them for you.** They are
-declared as OPTIONAL peer dependencies, so `npm install css-is-awesome` skips
-them silently and the server exits with:
+No install command needed — `npx` fetches it on first run. To pin an exact
+version in a lockfile instead, `npm install css-is-awesome-mcp` works the same
+as any other dependency; `npx` then uses that local copy.
+
+Alternative: the copy already in `node_modules` (this repo's own `mcp/server.cjs`).
+**Two dependencies are required and npm will NOT install them for you** for this
+path specifically — they are declared as OPTIONAL peer dependencies, so
+`npm install css-is-awesome` skips them silently and this copy exits with:
 
 ```
 css-is-awesome MCP server: @modelcontextprotocol/sdk is not installed.
@@ -155,9 +161,16 @@ Fix, in the client project:
 npm install -D @modelcontextprotocol/sdk zod
 ```
 
-Do NOT suggest `npx css-is-awesome-mcp` as a shortcut. `npx` fetches the package
-but not its optional peers, so it hits the same error. Run it from an install
-that has both, using the config above.
+```json
+{
+  "mcpServers": {
+    "css-is-awesome": {
+      "command": "node",
+      "args": ["node_modules/css-is-awesome/mcp/server.cjs"]
+    }
+  }
+}
+```
 
 ## Recipes (shipped in 1.0.0)
 

package/mcp/server.cjs

@@ -87,7 +87,9 @@ function resolveMcp() {
   catch {
     throw new Error(
       'css-is-awesome MCP server: @modelcontextprotocol/sdk is not installed. ' +
-      'Install with: npm install @modelcontextprotocol/sdk zod'
+      'Easiest fix: run `npx css-is-awesome-mcp` instead — it has the SDK as ' +
+      'a real dependency, no manual install needed. ' +
+      'To use this in-repo copy directly anyway: npm install @modelcontextprotocol/sdk zod'
     );
   }
 }
@@ -95,7 +97,10 @@ function resolveMcp() {
 function resolveStdio() {
   try { return require('@modelcontextprotocol/sdk/server/stdio.js'); }
   catch {
-    throw new Error('css-is-awesome MCP server: @modelcontextprotocol/sdk (stdio) missing — reinstall.');
+    throw new Error(
+      'css-is-awesome MCP server: @modelcontextprotocol/sdk (stdio) missing. ' +
+      'Run `npx css-is-awesome-mcp` instead, or reinstall the peer deps here.'
+    );
   }
 }
 
@@ -1131,6 +1136,40 @@ const handlers = {
         }
         break;
       }
+      case 'derive-theme': {
+        if (!target) throw new Error('assemble_prompt: intent "derive-theme:" requires a base theme name');
+        const base = handlers.get_theme({ name: target });
+        const themeMixin = handlers.get_mixin({ name: 'theme' });
+        const tk = getTokens();
+        banner(`css-is-awesome — deriving a new theme from ${base.name}`);
+        sub('Base theme — copy this, then edit only what should change');
+        lines.push('```scss');
+        lines.push(base.raw_scss);
+        lines.push('```');
+        lines.push('');
+        sub('The `theme()` wrapper contract');
+        lines.push('```scss');
+        lines.push(themeMixin.signature);
+        lines.push('```');
+        if (themeMixin.doc) { lines.push(''); lines.push(themeMixin.doc); }
+        lines.push('');
+        sub('Required + optional tokens (must all still be present)');
+        lines.push(`Required: ${tk.required.length}. Optional: ${tk.optional.length}.`);
+        lines.push('');
+        const dtCats = Object.keys(tk.byCategory).sort();
+        for (const cat of dtCats) {
+          lines.push(`### ${cat} (${tk.byCategory[cat].length})`);
+          lines.push('');
+          for (const name of tk.byCategory[cat].sort()) lines.push(`- ${name}`);
+          lines.push('');
+        }
+        sub('Rules');
+        lines.push('1. This server never writes files. Build the new theme file\'s content from the above, then write it yourself with your own file tools — ask the user where it should go if it isn\'t obvious.');
+        lines.push('2. Keep the `:root, :root[data-theme="<new-name>"]` shape (the base theme above already has it) unless you are deliberately building a multi-theme-bundle entry, where `$standalone: false` applies instead.');
+        lines.push('3. Only change values that should actually differ for the new design — copy everything else from the base theme unchanged, including tokens you don\'t recognize.');
+        lines.push('4. Before calling it done: every required token listed above must still be present in the new file. If this repo is available locally, `node scripts/theme-validator.js <path-to-new-theme.css>` confirms it.');
+        break;
+      }
       case 'animations': {
         const a = getAnimations();
         banner('css-is-awesome — animations');
@@ -1170,7 +1209,7 @@ const handlers = {
         break;
       }
       default:
-        throw new Error(`assemble_prompt: unknown intent "${intent}". Try overview | mixin:<name> | component:<name> | theme:<name> | tokens | animations | recipe:<name>.`);
+        throw new Error(`assemble_prompt: unknown intent "${intent}". Try overview | mixin:<name> | component:<name> | theme:<name> | derive-theme:<base> | tokens | animations | recipe:<name>.`);
     }
 
     if (args && typeof args === 'string' && args.trim()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "css-is-awesome",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "A token-driven SCSS design system with light/dark theming, semantic color tokens, and a 800+ LOC mixin API.",
   "homepage": "https://github.com/Jerry2d3d/css-is-awesome#readme",
   "bugs": {
@@ -10,7 +10,6 @@
   "style": "dist/css-is-awesome.css",
   "sass": "scss/main.scss",
   "bin": {
-    "css-is-awesome-mcp": "mcp/server.cjs",
     "cia": "bin/cia.cjs"
   },
   "sideEffects": [