@sakaniui/react 0.8.8 → 0.8.10

package/bin/sakaniui-mcp.mjs

@@ -2,13 +2,14 @@
 /**
  * SakaniUI MCP server -- lets an AI editor/agent look up the design system instead of guessing.
  *
- *   npx -y -p @sakaniui/react sakaniui-mcp [--project <dir>]
+ *   npx -y @sakaniui/mcp [--project <dir>]     (or: npx -y -p @sakaniui/react sakaniui-mcp)
  *
  * Zero dependencies: speaks newline-delimited JSON-RPC (MCP stdio transport).
  *
- * Read-only by construction. It reads four fixed files (package.json, dist/manifest.json,
- * AGENTS.md, CHANGELOG.md) from a @sakaniui/react install and writes nothing, runs nothing and
- * opens no network connection. No tool takes a path; every tool argument is validated.
+ * Read-only by construction. It reads five fixed files (package.json, dist/manifest.json,
+ * dist/icon-index.json, AGENTS.md, CHANGELOG.md) from a @sakaniui/react install and writes nothing,
+ * runs nothing and opens no network connection. No tool takes a path; every argument is validated.
+ * Code passed to check_code is only read as text, never executed.
  *
  * Version-aware. `npx` may fetch a newer release than the project uses, so the server looks for
  * the project's own installed @sakaniui/react (walking up from --project or the working
@@ -30,7 +31,7 @@ const readJson = (root, rel) => { try { return JSON.parse(readText(root, rel));
 function loadInstall(root) {
   const pkg = readJson(root, 'package.json');
   if (!pkg || pkg.name !== '@sakaniui/react') return null;
-  return { root, version: pkg.version, manifest: readJson(root, 'dist/manifest.json'), guide: readText(root, 'AGENTS.md'), changelog: readText(root, 'CHANGELOG.md') };
+  return { root, version: pkg.version, manifest: readJson(root, 'dist/manifest.json'), icons: readJson(root, 'dist/icon-index.json'), guide: readText(root, 'AGENTS.md'), changelog: readText(root, 'CHANGELOG.md') };
 }
 
 function findProjectInstall() {
@@ -46,7 +47,8 @@ function findProjectInstall() {
   return null;
 }
 
-const bundled = loadInstall(ownRoot);
+// inside @sakaniui/react the data sits next to bin/; inside @sakaniui/mcp it is copied into data/
+const bundled = loadInstall(fs.existsSync(path.join(ownRoot, 'dist', 'manifest.json')) ? ownRoot : path.join(ownRoot, 'data'));
 if (!bundled || !bundled.manifest) {
   process.stderr.write('sakaniui-mcp: dist/manifest.json not found. Run `npm run build:lib` (or install a published version).\n');
   process.exit(1);
@@ -64,8 +66,25 @@ const active = project && project.manifest && schemaOf(project) >= schemaOf(bund
 const manifest = active.manifest;
 const guide = active.guide || bundled.guide || '';
 const changelog = active.changelog || bundled.changelog || '';
+const iconIndex = (active.icons && active.icons.icons) || (bundled.icons && bundled.icons.icons) || [];
 const projectVersion = project ? project.version : null;
 
+// The HTML attributes React accepts (shipped in the manifest since 0.8.10; older manifests use the fallback list).
+const nativeAttrs = new Set(manifest.nativeAttributes || []);
+const NATIVE = { test: (n) => /^(aria-|data-)/.test(n) || /^on[A-Z]/.test(n) || n === 'key' || n === 'ref' || n === 'children' || (nativeAttrs.size ? nativeAttrs.has(n) : NATIVE_FALLBACK.test(n)) };
+/** What to say about a prop the component does not declare: an error when nothing accepts it, else a note. */
+function unknownProp(c, name) {
+  if (NATIVE.test(name)) {
+    // a real HTML attribute (placeholder, href, name, defaultChecked...): passed to the element, and fine.
+    // `color` is the one people mistake for a styling prop: it does not colour the component.
+    return name === 'color' ? { level: 'warning', message: `"color" is not a ${c.name} prop: it is the old HTML colour attribute and does not change the component's colours. Use the component's own props, or design tokens (get_tokens).` } : null;
+  }
+  // close spellings, plus the usual synonyms (leftIcon -> leadingIcon, onChange vs onValueChange is left to the list)
+  const canon = (x) => x.toLowerCase().replace(/left|start|before|prefix/g, 'leading').replace(/right|end|after|suffix/g, 'trailing').replace(/colou?r|tone|kind|type/g, 'variant');
+  const near = c.props.map((p) => p.name).filter((p) => distance(p.toLowerCase(), name.toLowerCase()) <= 2 || canon(p) === canon(name));
+  return { level: 'error', message: `"${name}" is not a ${c.name} prop${near.length ? ` (did you mean ${near.map((x) => `"${x}"`).join(', ')}?)` : ''}. ${c.name} accepts: ${c.props.map((p) => p.name).join(', ') || 'no props of its own'}.` };
+}
+
 /* ---------- versions ---------- */
 const SEMVER = /^\d+\.\d+\.\d+/;
 const parse = (v) => String(v).split('-')[0].split('.').map(Number);
@@ -91,6 +110,15 @@ function inInstalled(c, installed = projectVersion) {
   return cmp(c.since, installed) <= 0;
 }
 
+/** Is this prop (or this value of it) in the project's install? Returns a message when it is not. */
+function propTooNew(c, p, value, installed = projectVersion) {
+  if (!installed) return null;
+  if (p.since && cmp(p.since, installed) > 0) return `"${p.name}" was added to ${c.name} in ${p.since}; the project has ${installed}, where it does not exist. Upgrade (npm install @sakaniui/react@latest) or leave it out.`;
+  const vs = p.valuesSince && typeof value === 'string' ? p.valuesSince[value] : null;
+  if (vs && cmp(vs, installed) > 0) return `${p.name}=${JSON.stringify(value)} was added in ${vs}; the project has ${installed}, where it does not exist.`;
+  return null;
+}
+
 /* ---------- helpers ---------- */
 const byName = new Map(manifest.components.map((c) => [c.name.toLowerCase(), c]));
 const brief = (c) => {
@@ -152,7 +180,78 @@ function closest(name) {
     .map(([, c]) => c);
 }
 
-const NATIVE = /^(className|style|id|ref|key|children|role|tabIndex|title|hidden|lang|dir|slot|on[A-Z].*|aria-.*|data-.*)$/;
+/* ---------- icons ---------- */
+const iconNames = new Set();
+for (const i of iconIndex) { iconNames.add(i.name); if (i.filled) iconNames.add(i.filled); }
+const iconOtherExports = new Set(((active.icons && active.icons.other) || (bundled.icons && bundled.icons.other)) || []);
+const iconWords = (name) => name.replace(/^Icon/, '').replace(/Filled$/, '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Za-z])(\d)/g, '$1 $2').toLowerCase();
+
+// The conventional icon for common UI intents, ranked first (tags alone rank e.g. IconHttpDelete above IconTrash for "delete").
+const COMMON = {
+  delete: ['IconTrash'], remove: ['IconTrash', 'IconX'], trash: ['IconTrash'], bin: ['IconTrash'], edit: ['IconPencil', 'IconEdit'], rename: ['IconPencil'],
+  close: ['IconX'], dismiss: ['IconX'], cancel: ['IconX'], add: ['IconPlus'], new: ['IconPlus'], create: ['IconPlus'], plus: ['IconPlus'],
+  search: ['IconSearch'], find: ['IconSearch'], settings: ['IconSettings', 'IconAdjustments'], preferences: ['IconSettings'], menu: ['IconMenu2'],
+  more: ['IconDots', 'IconDotsVertical'], options: ['IconDots', 'IconDotsVertical'], user: ['IconUser'], profile: ['IconUser', 'IconUserCircle'], account: ['IconUserCircle'],
+  home: ['IconHome'], back: ['IconArrowLeft', 'IconChevronLeft'], next: ['IconArrowRight', 'IconChevronRight'], forward: ['IconArrowRight'], previous: ['IconArrowLeft', 'IconChevronLeft'],
+  expand: ['IconChevronDown'], collapse: ['IconChevronUp'], dropdown: ['IconChevronDown'], upload: ['IconUpload'], download: ['IconDownload'], share: ['IconShare'],
+  copy: ['IconCopy'], duplicate: ['IconCopy'], save: ['IconDeviceFloppy'], filter: ['IconFilter'], sort: ['IconArrowsSort'], calendar: ['IconCalendar'], date: ['IconCalendar'],
+  notification: ['IconBell'], notifications: ['IconBell'], bell: ['IconBell'], mail: ['IconMail'], email: ['IconMail'], message: ['IconMessage'], chat: ['IconMessageCircle'],
+  phone: ['IconPhone'], call: ['IconPhone'], logout: ['IconLogout'], signout: ['IconLogout'], login: ['IconLogin'], help: ['IconHelpCircle', 'IconHelp'], info: ['IconInfoCircle'],
+  warning: ['IconAlertTriangle'], error: ['IconAlertCircle'], success: ['IconCircleCheck'], check: ['IconCheck'], done: ['IconCheck'], favorite: ['IconHeart', 'IconStar'],
+  like: ['IconHeart', 'IconThumbUp'], star: ['IconStar'], rating: ['IconStar'], cart: ['IconShoppingCart'], refresh: ['IconRefresh'], reload: ['IconRefresh'], link: ['IconLink'],
+  attach: ['IconPaperclip'], attachment: ['IconPaperclip'], lock: ['IconLock'], password: ['IconLock'], view: ['IconEye'], show: ['IconEye'], hide: ['IconEyeOff'],
+  play: ['IconPlayerPlay'], pause: ['IconPlayerPause'], stop: ['IconPlayerStop'], theme: ['IconSun', 'IconMoon'], dark: ['IconMoon'], light: ['IconSun'],
+  external: ['IconExternalLink'], drag: ['IconGripVertical'], sidebar: ['IconLayoutSidebar'], dashboard: ['IconLayoutDashboard'], analytics: ['IconChartBar'], chart: ['IconChartBar'],
+  money: ['IconCurrencyDollar'], payment: ['IconCreditCard'], card: ['IconCreditCard'], location: ['IconMapPin'], time: ['IconClock'], clock: ['IconClock'], file: ['IconFile'],
+  folder: ['IconFolder'], image: ['IconPhoto'], photo: ['IconPhoto'], video: ['IconVideo'],
+};
+
+function searchIcons(query, limit = 12) {
+  const terms = String(query).toLowerCase().replace(/icon/g, ' ').split(/[^a-z0-9]+/).filter(Boolean);
+  if (!terms.length) return [];
+  const boosted = new Map();
+  for (const t of terms) (COMMON[t] || []).forEach((n, k) => boosted.set(n, Math.max(boosted.get(n) || 0, 40 - k * 5)));
+  return iconIndex
+    .map((i) => {
+      const words = iconWords(i.name).split(' ');
+      const tags = (i.tags || []).map((t) => t.toLowerCase());
+      let s = boosted.get(i.name) || 0;
+      for (const t of terms) {
+        if (words.join(' ') === t) s += 30;
+        else if (words[0] === t) s += 12;
+        else if (words.includes(t)) s += 8;
+        else if (words.some((w) => w.startsWith(t))) s += 4;
+        if (tags.includes(t)) s += 6;
+        else if (tags.some((g) => g.includes(t))) s += 2;
+        if ((i.category || '').toLowerCase() === t) s += 2;
+      }
+      return [s - words.length * 0.1, i];
+    })
+    .filter(([s]) => s > 0.5)
+    .sort((a, b) => b[0] - a[0])
+    .slice(0, limit)
+    .map(([, i]) => i);
+}
+
+/** Checks a value given for an icon prop. Returns an error string, or null. */
+function iconProblem(propName, raw, importedElsewhere = new Set(), localNames = new Set()) {
+  const v = String(raw).trim().replace(/^\{|\}$/g, '').trim();
+  if (/^</.test(v)) {
+    const tag = (/^<\s*([A-Za-z][\w.]*)/.exec(v) || [])[1] || 'Icon';
+    const real = iconNames.has(tag) || importedElsewhere.has(tag) ? tag : (searchIcons(tag, 1)[0] || {}).name;
+    const unknown = real && real !== tag ? ` ${tag} is not a SakaniUI icon either.` : '';
+    return `"${propName}" takes the icon component itself, not an element: write ${propName}={${real || 'IconName'}}, not ${propName}={<${tag} />}.${unknown}${!real ? ' Use search_icons to find the real name.' : ''}`;
+  }
+  if (!/^[A-Za-z_$][\w$]*$/.test(v)) return null; // an expression we cannot judge
+  if (iconNames.has(v) || importedElsewhere.has(v) || localNames.has(v)) return null;
+  // a local name (alias, parameter, constant): the import line was already checked, and we cannot see the rest
+  if (!/^Icon[A-Z0-9]/.test(v)) return null;
+  const hint = searchIcons(v, 3).map((i) => i.name);
+  return `"${v}" is not a SakaniUI icon.${hint.length ? ` Did you mean: ${hint.join(', ')}?` : ''} Use search_icons to find the real name.`;
+}
+
+// Attributes every component forwards to its root element. A prop outside this list and the contract is worth a warning.
+const NATIVE_FALLBACK = /^(className|style|id|ref|key|children|role|tabIndex|title|hidden|lang|dir|slot|on[A-Z].*|aria-.*|data-.*|href|target|rel|download|name|type|value|defaultValue|checked|defaultChecked|disabled|required|readOnly|placeholder|htmlFor|form|autoFocus|autoComplete|autoCapitalize|spellCheck|inputMode|pattern|min|max|step|minLength|maxLength|rows|cols|multiple|accept|src|srcSet|alt|width|height|loading|draggable|tabindex|ariaLabel)$/;
 
 /** Release notes: [{version, body}] newest first, from the CHANGELOG that matches the answering install. */
 function releases() {
@@ -162,6 +261,215 @@ function releases() {
   return out.sort((a, b) => cmp(b.version, a.version));
 }
 
+/* ---------- check_code: a small, read-only JSX scanner (the code is never executed) ---------- */
+/** Line number lookup in O(log n): a precomputed index of line starts per code string. */
+function lineIndex(code) {
+  const starts = [0];
+  for (let i = 0; i < code.length; i++) if (code.charCodeAt(i) === 10) starts.push(i + 1);
+  return (pos) => { let lo = 0, hi = starts.length - 1; while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= pos) lo = mid; else hi = mid - 1; } return lo + 1; };
+}
+let lineAt = (code, i) => code.slice(0, i).split('\n').length;
+
+function parseImports(code) {
+  const out = [];
+  const re = /import\s+(type\s+)?(?:([A-Za-z_$][\w$]*)\s*,?\s*)?(?:\{([^}]*)\})?\s*from\s*['"]([^'"]+)['"]/g;
+  let m;
+  while ((m = re.exec(code))) {
+    const names = (m[3] || '').split(',').map((x) => x.trim()).filter(Boolean).map((x) => {
+      const typeOnly = /^type\s+/.test(x);
+      const [imported, local] = x.replace(/^type\s+/, '').split(/\s+as\s+/).map((y) => y.trim());
+      return { imported, local: local || imported, typeOnly: typeOnly || !!m[1] };
+    });
+    out.push({ from: m[4], names, line: lineAt(code, m.index), def: m[2] || null });
+  }
+  return out;
+}
+
+/** Reads a balanced {...} starting at code[i] === '{'. Returns the index after the closing brace. */
+function skipBraces(code, i) {
+  let depth = 0;
+  for (; i < code.length; i++) {
+    const ch = code[i];
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const q = ch;
+      for (i++; i < code.length && code[i] !== q; i++) if (code[i] === '\\') i++;
+      continue;
+    }
+    if (ch === '{') depth++;
+    else if (ch === '}') { depth--; if (depth === 0) return i + 1; }
+  }
+  return code.length;
+}
+
+const ATTR_NAME = /[A-Za-z_][\w:.-]*/y;
+
+function parseElements(code, wanted) {
+  const els = [];
+  const re = /<([A-Z][\w]*(?:\.[A-Z][\w]*)?)(?=[\s/>])/g;
+  let m;
+  while ((m = re.exec(code))) {
+    const tag = m[1];
+    if (!wanted(tag)) continue;
+    let i = m.index + m[0].length;
+    const attrs = [];
+    let spread = false;
+    let selfClosing = false;
+    // every pass must move forward; an unterminated attribute ends the element instead of looping
+    for (let guard = 0; i < code.length && guard < 5000; guard++) {
+      while (/\s/.test(code[i])) i++;
+      if (code[i] === '/' && code[i + 1] === '>') { selfClosing = true; i += 2; break; }
+      if (code[i] === '>') { i++; break; }
+      if (code[i] === '<') break; // a new tag before this one closed: malformed, stop here
+      if (code[i] === '{') { const end = skipBraces(code, i); if (/^\{\s*\.\.\./.test(code.slice(i, end))) spread = true; i = end; continue; }
+      ATTR_NAME.lastIndex = i;
+      const nm = ATTR_NAME.exec(code);
+      if (!nm) { i++; continue; }
+      const name = nm[0];
+      i += name.length;
+      while (/\s/.test(code[i])) i++;
+      if (code[i] !== '=') { attrs.push({ name, kind: 'boolean', value: true }); continue; }
+      i++;
+      while (/\s/.test(code[i])) i++;
+      if (code[i] === '"' || code[i] === "'") {
+        const q = code[i];
+        const end = code.indexOf(q, i + 1);
+        if (end === -1) { attrs.push({ name, kind: 'string', value: code.slice(i + 1) }); i = code.length; break; }
+        attrs.push({ name, kind: 'string', value: code.slice(i + 1, end) });
+        i = end + 1;
+      } else if (code[i] === '{') {
+        const end = skipBraces(code, i);
+        const expr = code.slice(i + 1, end - 1).trim();
+        attrs.push({ name, ...classify(expr) });
+        i = end;
+      }
+    }
+    els.push({ tag, attrs, spread, selfClosing, line: lineAt(code, m.index) });
+    if (els.length >= 5000) break;
+    re.lastIndex = Math.max(re.lastIndex, i);
+  }
+  return els;
+}
+
+function classify(expr) {
+  let m;
+  if ((m = /^(['"])([\s\S]*)\1$/.exec(expr))) return { kind: 'string', value: m[2], raw: expr };
+  if ((m = /^`([^`$]*)`$/.exec(expr))) return { kind: 'string', value: m[1], raw: expr };
+  if (/^-?\d+(\.\d+)?$/.test(expr)) return { kind: 'number', value: Number(expr), raw: expr };
+  if (expr === 'true' || expr === 'false') return { kind: 'boolean', value: expr === 'true', raw: expr };
+  if (/^</.test(expr)) return { kind: 'element', raw: expr };
+  if (/^[A-Za-z_$][\w$]*$/.test(expr)) return { kind: 'identifier', value: expr, raw: expr };
+  return { kind: 'expression', raw: expr };
+}
+
+const TYPE_LIKE = /(Props|Type|Variant|Size|Item|Option|Datum|Column|Link|Plan|Post|Action|Step|Image|Author|Change|Data|Tab|Color|Category|Job|Member|Testimonial|Transaction)$/;
+
+/** Replaces the contents of template literals with spaces (newlines kept): code shown inside a string is not code. */
+function blankTemplates(code) {
+  let out = '';
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i];
+    if (ch === '`') {
+      let j = i + 1, depth = 0;
+      for (; j < code.length; j++) {
+        if (code[j] === '\\') { j++; continue; }
+        if (code[j] === '$' && code[j + 1] === '{') { depth++; j++; continue; }
+        if (code[j] === '}' && depth > 0) { depth--; continue; }
+        if (code[j] === '`' && depth === 0) break;
+      }
+      out += '`' + code.slice(i + 1, j).replace(/[^\n]/g, ' ') + '`';
+      i = j;
+    } else out += ch;
+  }
+  return out;
+}
+
+function checkCode(source) {
+  const code = blankTemplates(source);
+  lineAt = ((idx) => (_c, pos) => idx(pos))(lineIndex(code));
+  const errors = [];
+  const warnings = [];
+  const imports = parseImports(code);
+  const importedFrom = new Map(); // local name -> module
+  for (const imp of imports) { for (const n of imp.names) importedFrom.set(n.local, imp.from); if (imp.def) importedFrom.set(imp.def, imp.from); }
+  const importedElsewhere = new Set([...importedFrom].filter(([, from]) => !from.startsWith('@sakaniui/react')).map(([n]) => n));
+  // anything the snippet declares itself (const Icon = ..., function X, class Y) or aliases: not ours to judge
+  const localNames = new Set([...code.matchAll(/\b(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g)].map((m) => m[1]));
+  for (const imp of imports) for (const n of imp.names) if (n.local !== n.imported) localNames.add(n.local);
+
+  for (const imp of imports) {
+    if (!imp.from.startsWith('@sakaniui/react')) continue;
+    const entry = imp.from;
+    if (!['@sakaniui/react', '@sakaniui/react/blocks', '@sakaniui/react/icons'].includes(entry)) {
+      if (imp.names.length) errors.push({ line: imp.line, message: `"${entry}" has no named exports. Import components from @sakaniui/react, blocks from @sakaniui/react/blocks and icons from @sakaniui/react/icons.` });
+      continue;
+    }
+    if (imp.def) errors.push({ line: imp.line, message: `${entry} has no default export; use a named import: import { ${imp.def} } from '${entry}';` });
+    for (const n of imp.names) {
+      if (n.typeOnly) continue;
+      const c = byName.get(n.imported.toLowerCase());
+      const isUtility = manifest.utilities?.some((u) => u.name === n.imported);
+      if (entry === '@sakaniui/react/icons') {
+        if (!iconNames.has(n.imported) && !iconOtherExports.has(n.imported)) {
+          const hint = searchIcons(n.imported, 3).map((i) => i.name);
+          errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react/icons.${hint.length ? ` Did you mean: ${hint.join(', ')}?` : ''}` });
+        }
+        continue;
+      }
+      if (c && c.name !== n.imported) { errors.push({ line: imp.line, message: `${n.imported} has the wrong casing; the export is ${c.name}.` }); continue; }
+      if (entry === '@sakaniui/react/blocks') {
+        if (!c || c.kind !== 'block') errors.push({ line: imp.line, message: c ? `${n.imported} is a component: import it from @sakaniui/react.` : `${n.imported} is not a SakaniUI block.` });
+        continue;
+      }
+      if (c && c.kind === 'block') { errors.push({ line: imp.line, message: `${n.imported} is a block: import it from @sakaniui/react/blocks.` }); continue; }
+      if (!c && !isUtility) {
+        if (TYPE_LIKE.test(n.imported)) continue; // most likely a type export
+        const near = closest(n.imported);
+        errors.push({ line: imp.line, message: `${n.imported} is not exported by @sakaniui/react.${near.length ? ` Did you mean: ${near.join(', ')}?` : ''} Use search_components.` });
+      }
+      if (c && inInstalled(c) === false) errors.push({ line: imp.line, message: `${c.name} was added in ${c.since}; the project has ${projectVersion}.` });
+    }
+  }
+
+  // elements: anything imported from @sakaniui, plus manifest names used without an import
+  const isSakani = (tag) => importedFrom.get(tag)?.startsWith('@sakaniui/react') || (!importedFrom.has(tag) && byName.has(tag.toLowerCase()) && byName.get(tag.toLowerCase()).name === tag);
+  const elements = parseElements(code, isSakani);
+  for (const el of elements) {
+    const c = byName.get(el.tag.toLowerCase());
+    if (!c) continue;
+    const at = (message) => ({ line: el.line, message: `<${el.tag}>: ${message}` });
+    if (inInstalled(c) === false && !importedFrom.has(el.tag)) errors.push(at(`${c.name} was added in ${c.since}; the project has ${projectVersion}, where it does not exist.`));
+    if (!importedFrom.has(el.tag)) warnings.push(at(`not imported. Add: import { ${c.name} } from '${c.import}';`));
+    const given = new Map(el.attrs.map((a) => [a.name, a]));
+    if (!el.selfClosing) given.set('children', { kind: 'expression' });
+    for (const r of c.contract.requiredProps) {
+      if (given.has(r)) continue;
+      if (el.spread) warnings.push(at(`required prop "${r}" is not written out (it may come from the spread).`));
+      else errors.push(at(`missing required prop "${r}".`));
+    }
+    const known = new Map(c.props.map((p) => [p.name, p]));
+    for (const a of el.attrs) {
+      const p = known.get(a.name);
+      if (!p) { const u = unknownProp(c, a.name); if (u) (u.level === 'error' ? errors : warnings).push(at(u.message)); continue; }
+      if (p.values && ['string', 'number', 'boolean'].includes(a.kind) && !p.values.includes(a.value)) {
+        errors.push(at(`${a.name}=${JSON.stringify(a.value)} is not allowed. Use one of: ${p.values.map((x) => JSON.stringify(x)).join(', ')}.`));
+      }
+      { const tooNew = propTooNew(c, p, a.kind === 'string' ? a.value : undefined); if (tooNew) errors.push(at(tooNew)); }
+      if (p.type === 'IconComponent') {
+        if (a.kind === 'string') errors.push(at(`"${a.name}" takes an icon component, not a string: ${a.name}={IconName}.`));
+        else if (a.kind === 'element' || a.kind === 'identifier') {
+          const e = iconProblem(a.name, a.raw, importedElsewhere, localNames);
+          if (e) errors.push(at(e));
+          else if (a.kind === 'identifier' && iconNames.has(a.value) && !importedFrom.has(a.value) && !localNames.has(a.value)) warnings.push(at(`${a.value} is not imported. Add: import { ${a.value} } from '@sakaniui/react/icons';`));
+        }
+      }
+    }
+  }
+  if (!elements.length && !imports.some((i) => i.from.startsWith('@sakaniui/react'))) warnings.push({ line: 1, message: 'No SakaniUI imports or elements found in this code.' });
+  const out = { ok: errors.length === 0, checkedElements: elements.length, errors, warnings };
+  const note = versionNote(); if (note) out.versionNote = note;
+  return out;
+}
+
 const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
 
 /* ---------- tools ---------- */
@@ -194,7 +502,20 @@ const tools = {
       const c = byName.get(n.value.toLowerCase());
       if (!c) return fail(`No component named "${n.value}". Did you mean: ${closest(n.value).join(', ') || '(none close)'}? Use search_components.`);
       const out = { ...c, note: 'Native HTML attributes (className, style, aria-*, event handlers) are also accepted on the root element.' };
+      if (c.example) out.exampleNote = 'Start from `example`: it is type-checked against this release. Replace the placeholder text and values; keep the prop names and shapes.';
+      if (c.props.some((p) => p.type === 'IconComponent')) out.iconNote = 'Icon props take the component itself (icon={IconTrash}), not an element. The example uses IconStar as a placeholder: find the real icon with search_icons.';
       if (inInstalled(c) === false) out.availableInInstalled = false;
+      if (projectVersion) {
+        out.props = c.props.map((p) => {
+          const tooNew = propTooNew(c, p);
+          const newerValues = p.valuesSince ? Object.entries(p.valuesSince).filter(([, v]) => cmp(v, projectVersion) > 0).map(([k]) => k) : [];
+          if (!tooNew && !newerValues.length) return p;
+          const q = { ...p };
+          if (tooNew) q.availableInInstalled = false;
+          if (newerValues.length) q.valuesNotInInstalled = newerValues;
+          return q;
+        });
+      }
       const note = versionNote();
       if (note) out.versionNote = note;
       if (inInstalled(c) === false) out.warning = `${c.name} was added in ${c.since} but the project has ${projectVersion}. Do not use it without upgrading (npm install @sakaniui/react@latest).`;
@@ -251,10 +572,12 @@ const tools = {
       for (const r of c.contract.requiredProps) if (!Object.hasOwn(props, r)) errors.push(`Missing required prop "${r}".`);
       for (const [k, v] of Object.entries(props)) {
         const p = known.get(k);
-        if (!p) { if (!NATIVE.test(k)) warnings.push(`"${k}" is not a ${c.name} prop in the manifest (it would only work if it is a native attribute).`); continue; }
+        if (!p) { const u = unknownProp(c, k); if (u) (u.level === 'error' ? errors : warnings).push(u.message); continue; }
         if (p.values && (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') && !p.values.includes(v)) {
           errors.push(`"${k}" = ${JSON.stringify(v)} is not allowed. Use one of: ${p.values.map((x) => JSON.stringify(x)).join(', ')}.`);
         }
+        if (p.type === 'IconComponent' && typeof v === 'string') { const e = iconProblem(k, v); if (e) errors.push(e); }
+        const tooNew = propTooNew(c, p, v); if (tooNew) errors.push(tooNew);
       }
       if (c.contract.requiresAccessibleName && !errors.length) warnings.push('This control has no visible text of its own: keep its accessible-name prop set.');
       const out = { component: c.name, ok: errors.length === 0, errors, warnings };
@@ -301,11 +624,34 @@ const tools = {
       return text(pick.map((r) => `## ${r.version}\n\n${r.body}`).join('\n\n'));
     },
   },
+  search_icons: {
+    description: 'Find real icon names (Tabler set, exported from @sakaniui/react/icons) by meaning, e.g. "delete", "settings", "arrow right". Never guess an icon name: only names returned here exist.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string' }, limit: { type: 'number' } }, required: ['query'] },
+    run(args) {
+      const q = strArg(args, 'query', { required: true }); if (q.err) return fail(q.err);
+      if (!iconIndex.length) return fail('The icon index is not available in this install.');
+      const limit = Number.isInteger(args.limit) ? Math.min(Math.max(args.limit, 1), 30) : 12;
+      const hits = searchIcons(q.value, limit).map((i) => { const o = { name: i.name }; if (i.filled) o.filled = i.filled; if (i.category) o.category = i.category; if (i.tags) o.tags = i.tags.slice(0, 5); return o; });
+      if (!hits.length) return text(`No icon matches "${q.value}". Try a simpler word (e.g. "delete" rather than "remove item").`);
+      return text({ import: "import { IconName } from '@sakaniui/react/icons';", usage: 'icon={IconName} (the component, not <IconName />)', icons: hits });
+    },
+  },
+  check_code: {
+    description: 'Check a JSX/TSX snippet you wrote: imports from @sakaniui/react (and /blocks, /icons) must exist, every SakaniUI element must have its required props, prop values must be allowed, and icon props must be real icon components passed as components. The code is only read, never run. Run it on every snippet before you answer.',
+    inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'The snippet, including its import lines.' } }, required: ['code'] },
+    run(args) {
+      const code = args.code;
+      if (typeof code !== 'string' || !code.trim()) return fail('"code" must be a non-empty string.');
+      if (code.length > 50000) return fail('"code" is too long (max 50,000 characters).');
+      return text(checkCode(code));
+    },
+  },
   get_guide: {
     description: 'The AGENTS.md guide (principles, token rules, when nothing fits, glass, icons, per-component "why / when not to use", checklist). Pass a section number or heading text to get just that section; omit for the section list.',
-    inputSchema: { type: 'object', properties: { section: { type: 'string' } } },
+    inputSchema: { type: 'object', properties: { section: { type: 'string', description: 'A section number ("3") or words from its heading ("icons").' } } },
     run(args) {
-      const s0 = strArg(args, 'section'); if (s0.err) return fail(s0.err);
+      // agents sometimes call it with `query`; treat that as the section
+      const s0 = strArg(args.section === undefined && args.query !== undefined ? { section: args.query } : args, 'section'); if (s0.err) return fail(s0.err);
       if (!guide) return fail('AGENTS.md is not available in this install.');
       const parts = guide.split(/^(?=## )/m).filter((p) => p.startsWith('## '));
       const heads = parts.map((p) => p.split('\n')[0].replace(/^## /, ''));
@@ -318,45 +664,71 @@ const tools = {
 };
 
 /* ---------- JSON-RPC over stdio ---------- */
-const send = (msg) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...msg }) + '\n');
+// Protocol versions this server implements; the client's is used when it is one of them.
+const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
 
+let stdoutClosed = false;
+process.stdout.on('error', () => { stdoutClosed = true; process.exit(0); }); // the client went away (EPIPE)
+const write = (payload) => { if (!stdoutClosed) process.stdout.write(JSON.stringify(payload) + '\n'); };
+const reply = (id, body) => ({ jsonrpc: '2.0', id, ...body });
+
+/** Handles one message. Returns the response, or null for notifications. */
 function handle(msg) {
-  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return send({ id: null, error: { code: -32600, message: 'Invalid request' } });
+  if (!msg || typeof msg !== 'object' || Array.isArray(msg)) return reply(null, { error: { code: -32600, message: 'Invalid request' } });
   const { id, method, params } = msg;
   const isRequest = id !== undefined && id !== null;
+  if (typeof method !== 'string') return isRequest ? reply(id, { error: { code: -32600, message: 'Invalid request: method must be a string' } }) : null;
+  if (!isRequest) return null; // notifications (initialized, cancelled, ...) need no answer
   try {
     switch (method) {
       case 'initialize': {
         const note = versionNote();
-        return send({ id, result: {
-          protocolVersion: params?.protocolVersion || '2025-06-18',
-          capabilities: { tools: {} },
-          serverInfo: { name: 'sakaniui', version: refVersion },
-          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component before writing JSX, validate with check_usage, use only tokens from get_tokens, and read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
+        const asked = params && typeof params.protocolVersion === 'string' ? params.protocolVersion : null;
+        return reply(id, { result: {
+          protocolVersion: asked && PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'sakaniui', title: 'SakaniUI', version: refVersion },
+          instructions: `SakaniUI ${refVersion}${projectVersion ? ` (project has ${projectVersion})` : ''}. Read-only reference. Look components up with search_components / get_component and start from their \`example\`; find icon names with search_icons (never guess them); run check_code on every snippet before you answer; style anything beyond props with the design tokens from get_tokens (CSS variables), not hard-coded colours or utility classes the project may not have; read get_guide when nothing fits.${note ? ` ${note}` : ''}`,
         } });
       }
       case 'ping':
-        return send({ id, result: {} });
+        return reply(id, { result: {} });
       case 'tools/list':
-        return send({ id, result: { tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema, annotations: READ_ONLY })) } });
+        return reply(id, { result: { tools: Object.entries(tools).map(([name, t]) => ({ name, description: t.description, inputSchema: t.inputSchema, annotations: READ_ONLY })) } });
       case 'tools/call': {
         const t = typeof params?.name === 'string' && Object.hasOwn(tools, params.name) ? tools[params.name] : null;
-        if (!t) return send({ id, error: { code: -32602, message: `Unknown tool: ${String(params?.name).slice(0, 60)}` } });
+        if (!t) return reply(id, { error: { code: -32602, message: `Unknown tool: ${String(params?.name).slice(0, 60)}` } });
         const args = params.arguments;
-        if (args !== undefined && args !== null && (typeof args !== 'object' || Array.isArray(args))) return send({ id, result: fail('Tool arguments must be an object.') });
-        return send({ id, result: t.run(args || {}) });
+        if (args !== undefined && args !== null && (typeof args !== 'object' || Array.isArray(args))) return reply(id, { result: fail('Tool arguments must be an object.') });
+        return reply(id, { result: t.run(args || {}) });
       }
+      // Some clients ask for these even when only tools are offered; an empty list is the polite answer.
+      case 'resources/list': return reply(id, { result: { resources: [] } });
+      case 'resources/templates/list': return reply(id, { result: { resourceTemplates: [] } });
+      case 'prompts/list': return reply(id, { result: { prompts: [] } });
+      case 'logging/setLevel': return reply(id, { result: {} });
       default:
-        if (isRequest) send({ id, error: { code: -32601, message: `Method not found: ${String(method).slice(0, 60)}` } });
+        return reply(id, { error: { code: -32601, message: `Method not found: ${method.slice(0, 60)}` } });
     }
   } catch (e) {
-    if (isRequest) send({ id, error: { code: -32603, message: String(e?.message || e) } });
+    return reply(id, { error: { code: -32603, message: String(e?.message || e) } });
   }
 }
 
-readline.createInterface({ input: process.stdin }).on('line', (line) => {
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', (line) => {
   if (!line.trim()) return;
   let msg;
-  try { msg = JSON.parse(line); } catch { return send({ id: null, error: { code: -32700, message: 'Parse error' } }); }
-  handle(msg);
+  try { msg = JSON.parse(line); } catch { return write(reply(null, { error: { code: -32700, message: 'Parse error' } })); }
+  if (Array.isArray(msg)) { // a batch (older protocol versions): answer with one array
+    if (!msg.length) return write(reply(null, { error: { code: -32600, message: 'Invalid request: empty batch' } }));
+    const out = msg.map(handle).filter(Boolean);
+    if (out.length) write(out);
+    return;
+  }
+  const r = handle(msg);
+  if (r) write(r);
 });
+// the editor closed the connection: exit instead of lingering as an orphan process
+// (flush first: on macOS and Windows, writes to a pipe are asynchronous)
+rl.on('close', () => { if (stdoutClosed) process.exit(0); else process.stdout.write('', () => process.exit(0)); });