mlola-ui 1.1.9 → 1.1.10

package/README.md

@@ -62,8 +62,9 @@ that its UI is Mlola:
 `npx mlola-ui mcp` is that server. It answers from the registry bundled with
 this CLI, offline: `get_design_rules`, `search_components`, `get_component`,
 `get_tokens`, `check_markup` (invented classes, wrong `data-*` values, utility
-classes, hand-written colors), `add_components` and `init_project`. For
-Claude Code without init:
+classes, and hand-written colors or faded text in `style` attributes and
+`<style>` blocks), `add_components` and `init_project`. For Claude Code
+without init:
 
 ```sh
 claude mcp add mlola --scope project -- npx -y mlola-ui mcp
@@ -71,7 +72,9 @@ claude mcp add mlola --scope project -- npx -y mlola-ui mcp
 
 It is started by your agent and talks over stdio, so run by hand it prints one
 line and waits. The same tools, minus the two that write, answer at
-`https://ui.mlola.com/mcp` for agents that cannot run a command, and the server
+`https://ui.mlola.com/mcp` for agents that cannot run a command (with
+`get_install_command`, which also gives the CDN link and script for a page with
+no build step), and the server
 is listed in the MCP Registry as `io.github.mlolahq/mlola-ui`. See
 https://ui.mlola.com/docs/agents for Cursor, VS Code, Codex and chat apps.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mlola-ui",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "mcpName": "io.github.mlolahq/mlola-ui",
   "description": "Source-copy CLI that writes framework-free Mlola UI items into your project",
   "type": "module",

package/registry/index.json

@@ -2,7 +2,7 @@
   "$schema": "./schema/registry-index.schema.json",
   "schemaVersion": 2,
   "name": "mlola-ui",
-  "version": "1.1.9",
+  "version": "1.1.10",
   "homepage": "https://ui.mlola.com",
   "themeContract": {
     "attribute": "data-theme",
@@ -177,8 +177,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -239,7 +239,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -390,7 +390,9 @@
       "tags": [
         "status",
         "label",
-        "indicator"
+        "indicator",
+        "chip",
+        "pill"
       ],
       "usage": {
         "importPath": "{{aliases.components}}/badge",
@@ -399,7 +401,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -491,7 +493,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -544,7 +546,7 @@
         "spinner"
       ],
       "engineDependencies": {
-        "@mlola-ui/motion": "^1.1.9"
+        "@mlola-ui/motion": "^1.1.10"
       },
       "options": [
         {
@@ -632,7 +634,10 @@
       "tags": [
         "layout",
         "container",
-        "surface"
+        "surface",
+        "stat",
+        "kpi",
+        "metric"
       ],
       "usage": {
         "importPath": "{{aliases.components}}/card",
@@ -708,8 +713,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -777,7 +782,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -832,7 +837,7 @@
         "modal"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -895,8 +900,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -960,7 +965,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -1184,8 +1189,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -1335,7 +1340,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -1386,7 +1391,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10"
       },
       "options": [
         {
@@ -1761,7 +1766,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -1814,8 +1819,8 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -1892,8 +1897,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -2039,7 +2044,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10"
       },
       "options": [
         {
@@ -2184,7 +2189,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10"
       },
       "options": [
         {
@@ -2316,7 +2321,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -2402,7 +2407,7 @@
         "spinner"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -2545,7 +2550,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10"
       },
       "options": [
         {
@@ -2684,7 +2689,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -2756,7 +2761,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -2826,7 +2831,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -3024,7 +3029,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -3101,7 +3106,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -3156,7 +3161,7 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -3219,7 +3224,7 @@
         "popover"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -3289,7 +3294,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -3408,8 +3413,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -3473,7 +3478,7 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10"
       },
       "options": [
         {
@@ -3560,8 +3565,8 @@
       },
       "registryDependencies": [],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -3635,7 +3640,7 @@
         "sheet"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [],
       "variants": [],
@@ -3758,7 +3763,7 @@
         "button"
       ],
       "engineDependencies": {
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {
@@ -3861,8 +3866,8 @@
         "input"
       ],
       "engineDependencies": {
-        "@mlola-ui/behavior": "^1.1.9",
-        "@mlola-ui/icons": "^1.1.9"
+        "@mlola-ui/behavior": "^1.1.10",
+        "@mlola-ui/icons": "^1.1.10"
       },
       "options": [
         {

package/src/knowledge.js

@@ -50,21 +50,41 @@ export function allItems() {
   return [...free, ...pro];
 }
 
-/** Items matching a query: every word must appear in the name, title, description, category or tags. */
+/**
+ * Items matching a query, searched in the name, title, description, category
+ * and tags. Items that match every word come first; when none does, the items
+ * that match the most words, so "radio card" still finds the radio group. A
+ * plural matches its singular, and "stat-card" reads as "stat card".
+ */
 export function searchItems({ query = "", kind, category, tier } = {}) {
-  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
-  return allItems()
+  const words = query.toLowerCase().split(/[\s-]+/).filter(Boolean);
+  const forms = (word) => [word, ...(word.length > 3 && word.endsWith("s") ? [word.slice(0, -1)] : [])];
+  const scored = allItems()
     .filter((item) => (!kind || item.kind === kind) && (!category || item.category === category) && (!tier || item.tier === tier))
     .map((item) => {
       const haystack = [item.name, item.title, item.description, item.category, ...item.tags].join(" ").toLowerCase();
-      const score = words.reduce((sum, word) => sum + (item.name === word ? 5 : item.name.includes(word) ? 3 : haystack.includes(word) ? 1 : -100), 0);
-      return { item, score };
-    })
-    .filter(({ score }) => score >= 0)
+      let matched = 0;
+      let score = 0;
+      for (const word of words) {
+        const hit = Math.max(...forms(word).map((form) => (item.name === form ? 5 : item.name.includes(form) ? 3 : haystack.includes(form) ? 1 : 0)));
+        if (hit) matched += 1;
+        score += hit;
+      }
+      return { item, score, matched };
+    });
+  const best = Math.max(0, ...scored.map(({ matched }) => matched));
+  return scored
+    .filter(({ matched }) => !words.length || (best > 0 && matched === best))
     .sort((a, b) => b.score - a.score || a.item.name.localeCompare(b.item.name))
     .map(({ item }) => item);
 }
 
+/** " Did you mean: …?" for a name that is not an item, or nothing. */
+export function suggest(name) {
+  const close = [...new Set([...allItems().filter((entry) => entry.name.includes(name) || name.includes(entry.name)).map((entry) => entry.name), ...searchItems({ query: name }).map((entry) => entry.name)])].slice(0, 5);
+  return close.length ? ` Did you mean: ${close.join(", ")}?` : "";
+}
+
 /** The classes a component styles (its own prefix) and the attributes each reacts to. */
 function elementsOf(name) {
   const contract = bundled("contract.json");
@@ -84,7 +104,9 @@ function projectConfig(cwd) {
 }
 
 /** Everything an agent needs to use one item correctly. */
-export function describeItem(name, { cwd = process.cwd(), includeSource = false } = {}) {
+export function describeItem(requested, { cwd = process.cwd(), includeSource = false } = {}) {
+  // Agents often ask by class ("ml-button") or title ("Date picker"): both mean the item.
+  const name = requested.trim().toLowerCase().replace(/^ml-/, "").replace(/\s+/g, "-");
   const registry = loadRegistry();
   const item = registry.items.find((entry) => entry.name === name);
   if (!item) {
@@ -101,8 +123,7 @@ export function describeItem(name, { cwd = process.cwd(), includeSource = false
         note: "Part of Mlola Pro. Its source arrives with a license token; its classes and attributes are listed in mlola-pro.agents.md after the first Pro install.",
       };
     }
-    const close = allItems().filter((entry) => entry.name.includes(name) || name.includes(entry.name)).map((entry) => entry.name).slice(0, 5);
-    throw new Error(`No item named "${name}".${close.length ? ` Did you mean: ${close.join(", ")}?` : ""} Search with search_components.`);
+    throw new Error(`No item named "${requested}".${suggest(name)} Search with search_components.`);
   }
   const config = projectConfig(cwd);
   const usage = item.usage
@@ -267,8 +288,8 @@ export function checkMarkup(markup) {
       if (name === "data-theme" && value && !themeIds.has(value) && !/^th-[0-9a-z]{12}$/.test(value)) {
         note("error", tag, `data-theme="${value}" is not a theme.`, `Use one of: ${[...themeIds].join(", ")}, or a Studio theme id.`);
       }
-      if (name === "data-mode" && !["light", "dark"].includes(value)) {
-        note("error", tag, `data-mode is "light" or "dark"; "${value}" belongs in an attribute of your own.`, "data-theme and data-mode belong to the engine. Use data-kind or data-state for a component's own meaning.");
+      if (name === "data-mode" && !["light", "dark", "system"].includes(value)) {
+        note("error", tag, `data-mode is "light", "dark" or "system"; "${value}" belongs in an attribute of your own.`, "data-theme and data-mode belong to the engine. Use data-kind or data-state for a component's own meaning.");
       }
       if (!SHARED.has(name) || !mlola.length) continue;
       const allowed = new Set();
@@ -295,5 +316,28 @@ export function checkMarkup(markup) {
       }
     }
   }
+
+  // The page's own stylesheet: the same rules hold in a <style> block.
+  for (const [, css] of markup.matchAll(/<style[^>]*>([\s\S]*?)<\/style>/gi)) {
+    for (const rule of css.replace(/\/\*[\s\S]*?\*\//g, "").split("}")) {
+      const open = rule.lastIndexOf("{");
+      if (open < 0) continue;
+      const selector = rule.slice(0, open).split("{").pop().trim();
+      const body = rule.slice(open + 1).replace(/url\([^)]*\)/g, "");
+      const where = `<style> ${selector}`;
+      const overridden = [...body.matchAll(/(--ml-[\w-]+)\s*:/g)].map((match) => match[1]).filter((token) => tokenNames.has(token));
+      if (COLOR.test(body.replace(/--[\w-]+\s*:[^;]*/g, ""))) {
+        note("error", where, "A color is written by hand in the stylesheet.", "Read a token: var(--ml-text), var(--ml-primary-text), var(--ml-surface)… (get_tokens). The theme then keeps its contrast in every mode.");
+      }
+      if (overridden.length) {
+        note("error", where, `${overridden.join(", ")} is a theme token; setting it here overrides the theme.`, "Pick a theme, or change the theme's spec (mlola.theme.json), instead of redefining its tokens.");
+      }
+      // Faded text: its contrast now depends on the theme behind it.
+      const opacity = /(?:^|;)\s*opacity\s*:\s*(0?\.\d+|0)\s*(?:;|$)/.exec(body);
+      if (opacity && !/disabled|:empty|::?placeholder|\[hidden\]|inert/.test(selector)) {
+        note("warning", where, `opacity: ${opacity[1]} fades whatever text is inside, and how far it falls below the contrast floor depends on the theme and the fill behind it.`, "For quieter text use color: var(--ml-text-muted); on a filled control, its -foreground role. Keep opacity for disabled or decorative parts.");
+      }
+    }
+  }
   return issues;
 }

package/src/mcp.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import readline from "node:readline";
-import { checkMarkup, describeItem, designData, designGuide, searchItems, themes, tokens } from "./knowledge.js";
+import { checkMarkup, describeItem, designData, designGuide, searchItems, suggest, themes, tokens } from "./knowledge.js";
 
 /**
  * `mlola-ui mcp` — a Model Context Protocol server over stdio.
@@ -24,12 +24,28 @@ const INSTRUCTIONS = `This project's UI is Mlola UI: native CSS classes (ml-*),
 Before writing UI: call get_design_rules once, then search_components for what you need and get_component for how to use it. Read tokens with get_tokens instead of writing colors, sizes, shadows or durations. After writing markup, run check_markup on it and fix what it reports.`;
 
 const REMOTE_INSTRUCTIONS = `Mlola UI is a component system on native CSS classes (ml-*), data-* attributes for state and variant, and --ml-* tokens. There is no Tailwind.
-Before writing UI: call get_design_rules once, then search_components for what you need and get_component for how to use it. Read tokens with get_tokens. After writing markup, run check_markup and fix what it reports. This server cannot write files: get_install_command gives the commands to run in the project, and Mlola Pro items need a license token (npx mlola-ui login).`;
+Before writing UI: call get_design_rules once, then search_components for what you need and get_component for how to use it. Read tokens with get_tokens. After writing markup, run check_markup and fix what it reports. This server cannot write files: get_install_command gives the commands to run in the project, and Mlola Pro items need a license token (npx mlola-ui login). For a page with no build step (one HTML file), get_design_rules gives the stylesheet link and the script to paste.`;
 
 const text = (value) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] });
 
+/**
+ * How to load Mlola in a page with no build step: the engine's stylesheet and
+ * the behavior runtime from a CDN, at this release's version.
+ */
+export function noBuildSetup(version) {
+  const cdn = (pkg, file) => `https://cdn.jsdelivr.net/npm/@mlola-ui/${pkg}@${version}/${file}`;
+  return [
+    "Without a build step (one HTML file), load Mlola from a CDN:",
+    `<link rel="stylesheet" href="${cdn("engine", "generated/mlola.css")}">`,
+    `<html data-theme="graphite" data-mode="system">   (data-mode system follows the reader's light or dark setting)`,
+    "For menus, dialogs, tabs, selects, sliders, switches, tooltips and toasts, mark each root with data-ml=\"<behavior>\" as get_component's html example shows, and load the runtime once:",
+    `<script type="module">import { observe } from "${cdn("behavior", "src/index.js")}"; observe();</script>`,
+    "The free components work this way. Mlola Pro items need a project, the CLI and a license.",
+  ].join("\n");
+}
+
 /** Tools that only read the registry: the local and the remote server share them. */
-function readTools({ cwd }) {
+function readTools({ cwd, version }) {
   return [
     {
       name: "get_design_rules",
@@ -39,7 +55,7 @@ function readTools({ cwd }) {
       annotations: { readOnlyHint: true },
       handler: () => {
         const data = designData();
-        return text(`${data?.rules ?? ""}\nThemes: ${themes().map((theme) => theme.id).join(", ")} (data-theme on any ancestor, data-mode light|dark).\nComposition primitives: ${(data?.primitives ?? []).map((entry) => entry.name).join(" ")}`);
+        return text(`${data?.rules ?? ""}\nThemes: ${themes().map((theme) => theme.id).join(", ")} (data-theme on any ancestor, data-mode light|dark|system).\nComposition primitives: ${(data?.primitives ?? []).map((entry) => entry.name).join(" ")}\n\n${noBuildSetup(version)}`);
       },
     },
     {
@@ -88,7 +104,7 @@ function readTools({ cwd }) {
     {
       name: "check_markup",
       title: "Check markup against the Mlola contract",
-      description: "Checks HTML or JSX: classes that do not exist, variant classes, data-* values a class does not react to, utility classes, hand-written colors, and misuse of data-theme or data-mode. Run it on markup you wrote before finishing.",
+      description: "Checks HTML or JSX: classes that do not exist, variant classes, data-* values a class does not react to, utility classes, misuse of data-theme or data-mode, and in style attributes and <style> blocks hand-written colors, overridden theme tokens and text faded with opacity. Run it on markup you wrote before finishing.",
       inputSchema: { type: "object", properties: { markup: { type: "string" } }, required: ["markup"], additionalProperties: false },
       annotations: { readOnlyHint: true },
       handler: ({ markup }) => {
@@ -99,7 +115,7 @@ function readTools({ cwd }) {
   ];
 }
 
-function tools({ cwd, run }) {
+function tools({ cwd, run, version }) {
   const capture = async (argv) => {
     const lines = [];
     const output = { log: (...parts) => lines.push(parts.join(" ")), error: (...parts) => lines.push(parts.join(" ")) };
@@ -109,7 +125,7 @@ function tools({ cwd, run }) {
     return { code, output: lines.join("\n") };
   };
   return [
-    ...readTools({ cwd }),
+    ...readTools({ cwd, version }),
     {
       name: "add_components",
       title: "Install Mlola components",
@@ -179,6 +195,32 @@ function prompt(name, args) {
   };
 }
 
+/**
+ * Arguments that do not fit a tool's input schema, described so an agent can
+ * correct the call: a missing required argument, one of the wrong type, one
+ * the tool does not take. Null when they fit.
+ */
+function invalidArguments(tool, args) {
+  const schema = tool.inputSchema ?? {};
+  const properties = schema.properties ?? {};
+  const example = (name) => (properties[name]?.type === "array" ? `["…"]` : properties[name]?.type === "boolean" ? "true" : `"…"`);
+  const typeOf = (value) => (Array.isArray(value) ? "array" : typeof value);
+  if (typeOf(args) !== "object" || args === null) return `${tool.name} takes an object of arguments.`;
+  for (const name of schema.required ?? []) {
+    if (args[name] === undefined) return `${tool.name} needs "${name}" (${properties[name]?.type ?? "a value"}), for example {"${name}": ${example(name)}}.`;
+  }
+  for (const [name, value] of Object.entries(args)) {
+    const expected = properties[name];
+    if (!expected) {
+      if (schema.additionalProperties === false) return `${tool.name} does not take "${name}". It takes: ${Object.keys(properties).join(", ") || "no arguments"}.`;
+      continue;
+    }
+    if (expected.type && typeOf(value) !== expected.type) return `"${name}" should be ${expected.type === "array" ? "an array" : `a ${expected.type}`}, not ${typeOf(value) === "array" ? "an array" : `a ${typeOf(value)}`}.`;
+    if (expected.enum && !expected.enum.includes(value)) return `"${name}" is one of: ${expected.enum.join(", ")}.`;
+  }
+  return null;
+}
+
 /**
  * The protocol, apart from any transport: takes one JSON-RPC message and
  * resolves to the reply, or to null for a notification. The stdio server
@@ -208,6 +250,8 @@ export function createMcpHandler({ tools: available, listResources, readResource
         case "tools/call": {
           const tool = available.find((entry) => entry.name === params?.name);
           if (!tool) return fail(id, -32602, `Unknown tool ${params?.name}`);
+          const problem = invalidArguments(tool, params?.arguments ?? {});
+          if (problem) return reply(id, { ...text(problem), isError: true });
           try {
             return reply(id, await tool.handler(params?.arguments ?? {}));
           } catch (error) {
@@ -246,13 +290,14 @@ export function remoteMcpHandler({ version }) {
   const install = {
     name: "get_install_command",
     title: "How to install Mlola components",
-    description: "The commands to run in the project to set Mlola up and add components, blocks, pages or templates, including the license step for Mlola Pro items.",
-    inputSchema: { type: "object", properties: { names: { type: "array", items: { type: "string" }, minItems: 1 } }, required: ["names"], additionalProperties: false },
+    description: "How to set Mlola up: the commands to run in a project to add components, blocks, pages or templates (with the license step for Mlola Pro items), and the stylesheet link and script for a page with no build step. Leave names out for the setup alone.",
+    inputSchema: { type: "object", properties: { names: { type: "array", items: { type: "string" }, description: "Item names from search_components, for example [\"button\", \"date-picker\"]." } }, additionalProperties: false },
     annotations: { readOnlyHint: true },
-    handler: ({ names }) => {
+    handler: ({ names = [] }) => {
+      if (!names.length) return text(["In a project:", "", "npx mlola-ui init   # once: config, stylesheet, the engine, and agent instructions", "npx mlola-ui add <names>", "", noBuildSetup(version)].join("\n"));
       const found = names.map((name) => searchItems({ query: name }).find((item) => item.name === name));
       const unknown = names.filter((_, index) => !found[index]);
-      if (unknown.length) return { ...text(`No Mlola item is called ${unknown.join(", ")}. Find names with search_components.`), isError: true };
+      if (unknown.length) return { ...text(unknown.map((name) => `No Mlola item is called ${name}.${suggest(name)}`).join("\n") + " Find names with search_components."), isError: true };
       const pro = found.filter((item) => item.tier === "pro").map((item) => item.name);
       return text([
         "Run in the project:",
@@ -262,11 +307,13 @@ export function remoteMcpHandler({ version }) {
         `npx mlola-ui add ${names.join(" ")}`,
         "",
         'Then import styles/mlola/index.css once and set data-theme="graphite" (or atelier, machined, aerogel, nordic) on the root element.',
+        "",
+        noBuildSetup(version),
       ].join("\n"));
     },
   };
   return createMcpHandler({
-    tools: [...readTools({ cwd }), install],
+    tools: [...readTools({ cwd, version }), install],
     listResources: () => [{ uri: "mlola://guide", name: "Mlola UI design guide", description: "Classes, attributes, tokens and rules, generated from the stylesheet.", mimeType: "text/markdown" }],
     readResource: (uri) => {
       if (uri === "mlola://guide") return designGuide() ?? "";
@@ -279,7 +326,7 @@ export function remoteMcpHandler({ version }) {
 
 export async function serveMcp({ cwd, run, version, input = process.stdin, output = process.stdout }) {
   const handle = createMcpHandler({
-    tools: tools({ cwd, run }),
+    tools: tools({ cwd, run, version }),
     listResources: () => resources(cwd),
     readResource: (uri) => readResource(uri, cwd),
     version,