@tattva/mcp 0.0.0-stage → 0.11.1

package/LICENSE.md

@@ -0,0 +1,49 @@
+# Tattva licence
+
+> **Draft.** This explains in plain words how Tattva may be used. It is not legal advice. Have it reviewed before you sell the paid plans.
+
+Tattva comes in three plans: **Free**, **Pro** and **Team**. Plans and prices are on the [pricing page](https://lkb00.github.io/tattva/#pricing).
+
+## Free
+
+The free core covers:
+- the documentation, patterns, case studies and guides
+- the design tokens
+- the parts marked **Free** on the site: the basic building blocks and the parts of a plain chat
+
+You may use the free core in any project, personal or commercial, and change it as you like. Keep this licence notice with any copy of the source you share.
+
+## Pro and Team (paid)
+
+A paid licence covers:
+- every part, marked **Pro** on the site
+- the page templates and whole screens
+- the AI-agent kit: the MCP server, `components.json` and the Markdown page for each part
+
+**Who may use it**
+- **Pro:** one person.
+- **Team:** up to 10 people at one company.
+
+**What you may do**
+- Use the parts in unlimited projects, including work for clients and products you sell.
+- Change the parts to fit your product.
+
+**What you may not do**
+- Resell, share or give away the parts, the templates or the AI-agent kit, whether on their own or as part of another UI kit, design system, template or theme.
+- Share your licence key or the download with people it does not cover.
+
+**Updates**
+- You get updates for one year from the date you buy.
+- Everything you received in that year is yours to keep using after that.
+
+**Payment and refunds**
+- Lemon Squeezy, the seller of record, handles payment, receipts and sales tax or VAT.
+- Refunds follow the policy shown at checkout.
+
+## No warranty
+
+Tattva is provided as it is, without any warranty. The authors are not liable for any claim or damage that arises from using it.
+
+## Questions
+
+Open an issue on the repository: https://github.com/LKB00/tattva/issues

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @tattva/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The [Tattva](https://lkb00.github.io/tattva/) MCP server. It lets an AI coding tool look up every Tattva part, plan a build, and check the code it writes. Read-only, no dependencies, needs Node 18 or newer.
+
+Claude Code:
+
+```sh
+claude mcp add tattva -- npx -y @tattva/mcp
+```
+
+Cursor, Claude Desktop and others (MCP settings):
+
+```json
+{ "mcpServers": { "tattva": { "command": "npx", "args": ["-y", "@tattva/mcp"] } } }
+```
+
+Pro and Team: set `TATTVA_API` and `TATTVA_LICENSE_KEY` (from your receipt) to unlock the full code of Pro parts. More: https://lkb00.github.io/tattva/connect-ai/

package/mcp-guide.mjs

@@ -0,0 +1,289 @@
+// Guidance for the Tattva MCP server: the starting questions, the build recipes and the code checker.
+// Pure functions, no dependencies. mcp-server.mjs imports this file, so keep the two files together.
+
+/** The questions an agent asks the person before building. Every question has a default, so "defaults" is a valid answer. */
+export const QUESTIONS = [
+  { id: "product", question: "What are you building?", default: "chat-assistant",
+    options: [
+      { value: "chat-assistant", label: "A chat assistant (a thread, a message box, sources and confidence)" },
+      { value: "agent-console", label: "An agent console (plans, steps, approvals, diffs, a needs-you inbox)" },
+      { value: "creative-tool", label: "A creative AI tool (prompt, variations, canvas, history)" },
+      { value: "generative-ui", label: "An app where the AI builds interface on the fly" },
+      { value: "ai-dashboard", label: "A dashboard for an AI product (usage, cost, charts, tables)" },
+    ] },
+  { id: "stack", question: "Is this a new project or an existing app, and which framework?", default: "new-vite",
+    options: [
+      { value: "new-vite", label: "New project with React and Vite" },
+      { value: "new-next", label: "New project with Next.js" },
+      { value: "existing", label: "Add it to an existing React app that uses Tailwind CSS v4" },
+      { value: "no-code", label: "A no-code AI builder such as Lovable, v0 or Bolt (nothing to install)" },
+    ] },
+  { id: "theme", question: "Which colour theme?", default: "lime",
+    options: [
+      { value: "lime", label: "Lime: warm paper, fresh lime" },
+      { value: "teal", label: "Teal: cool paper, calm teal" },
+      { value: "indigo", label: "Indigo: soft violet-blue" },
+      { value: "harbor", label: "Harbor: steady, trusted blue" },
+      { value: "plum", label: "Plum: warm berry pink" },
+      { value: "graphite", label: "Graphite: no colour, the AI is marked by label and icon" },
+      { value: "terminal", label: "Terminal: near-black and dense, with a sky-blue AI colour, for trading and data screens" },
+    ] },
+  { id: "mode", question: "Light, dark, or both?", default: "both",
+    options: [{ value: "both", label: "Both, following the person's device" }, { value: "light", label: "Light only" }, { value: "dark", label: "Dark only" }] },
+  { id: "trust", question: "Which trust behaviours does the product need? (pick any)", default: ["sources", "feedback"], multiple: true,
+    options: [
+      { value: "sources", label: "Show sources and citations" },
+      { value: "confidence", label: "Show how sure the AI is" },
+      { value: "approvals", label: "Ask before the AI acts (approvals)" },
+      { value: "undo", label: "Undo and checkpoints" },
+      { value: "memory", label: "Memory the person can see and edit" },
+      { value: "disclosure", label: "Clear AI labels and disclosure" },
+      { value: "feedback", label: "Thumbs up and down feedback" },
+      { value: "errors", label: "Calm error, refusal and rate-limit states" },
+    ] },
+  { id: "plan", question: "Which plan are you on?", default: "free",
+    options: [{ value: "free", label: "Free: the basic building blocks and a plain chat" }, { value: "pro", label: "Pro or Team: every part" }] },
+];
+
+/** Parts per product, in the order to build them. `core` is always used; `why` is one plain line. Ids are checked against components.json. */
+export const RECIPES = {
+  "chat-assistant": {
+    title: "Chat assistant",
+    screen: "thread-template",
+    core: [["message-list", "The scrolling thread."], ["message", "One turn: the person's bubble or the assistant's text."], ["composer", "The message box."], ["markdown", "Renders the assistant's formatting safely."], ["thinking-block", "Shows the assistant is working, and what it did."], ["typing-indicator", "A quiet sign a reply is on the way."], ["suggestion-chips", "Starter prompts and follow-ups."], ["message-actions", "Copy, retry and rate under a reply."], ["conversation-list", "Past chats in the sidebar."], ["model-picker", "Lets the person choose a model."]],
+    patterns: ["source", "uncertain", "undo", "mistake"],
+  },
+  "agent-console": {
+    title: "Agent console",
+    screen: "split-canvas-template",
+    core: [["agent-session-list", "All runs, with what each needs."], ["plan-card", "The plan, before the agent starts."], ["step-timeline", "What the agent did, in order."], ["tool-call-card", "One tool call and its result."], ["permission-prompt", "Asks before an action that matters."], ["needs-you-inbox", "Everything waiting on a person, in one place."], ["agent-question-card", "The agent asks a question mid-task."], ["takeover-bar", "Lets the person take control."], ["diff-view", "Shows exactly what changed."], ["checkpoint-list", "Go back to an earlier point."], ["budget-control", "Limits cost and time."], ["re-entry-recap", "Catches the person up when they return."]],
+    patterns: ["approval", "ask before", "undo", "work as it happens"],
+  },
+  "creative-tool": {
+    title: "Creative AI tool",
+    screen: "split-canvas-template",
+    core: [["prompt-box", "Where the person describes what they want."], ["variant-grid", "Several options to choose from."], ["canvas-panel", "The working area."], ["parameter-panel", "Controls such as size, style and strength."], ["generation-progress", "Honest progress while it makes the result."], ["version-history", "Every earlier result, so nothing is lost."], ["variation-actions", "More like this, upscale, edit."], ["suggestion-bar", "Ideas to try next."], ["media-grid", "A library of results."]],
+    patterns: ["undo", "mistake", "work as it happens"],
+  },
+  "generative-ui": {
+    title: "Generative interface",
+    screen: "thread-template",
+    core: [["gen-ui-renderer", "Draws interface the AI describes."], ["generated-surface", "The frame generated content lives in."], ["sandboxed-frame", "Keeps untrusted generated content safe."], ["message-list", "The thread beside it."], ["composer", "The message box."], ["markdown", "Formatted text."], ["ai-label", "Marks what the AI made."]],
+    patterns: ["ask before", "undo"],
+  },
+  "ai-dashboard": {
+    title: "AI product dashboard",
+    screen: "app-shell",
+    core: [["stat-tile", "One headline number."], ["usage-meter", "How much has been used."], ["context-meter", "How full the AI's memory window is."], ["line-chart", "A trend over time."], ["bar-chart", "Compare amounts."], ["data-table", "Rows people can sort and read."], ["chart-frame", "Title, caption and a table view for every chart."], ["timeline", "Events in order."]],
+    patterns: ["uncertain"],
+  },
+};
+
+/** Extra parts for each trust behaviour the person asked for. */
+export const TRUST = {
+  sources: [["citation-marker", "The small numbered marker in the text."], ["source-list", "The sources behind an answer."], ["source-card", "One source."]],
+  confidence: [["confidence-indicator", "Shows how sure the AI is, with a word as well as a colour."]],
+  approvals: [["permission-prompt", "Asks before an action that matters."], ["approval-prompt", "A simple yes or no on one step."]],
+  undo: [["revert-toggle", "Switch back to the earlier version."], ["checkpoint-list", "Return to an earlier point."], ["version-pager", "Step between versions of a reply."], ["action-log", "A record of what the agent did, with a timed undo."]],
+  memory: [["memory-notice", "Tells the person something was remembered."], ["memory-list", "See, edit and delete memories."]],
+  disclosure: [["ai-label", "Marks AI-made content."], ["ai-disclosure", "A plain statement that the person is talking to an AI."], ["ai-badge", "A small badge for AI features."]],
+  feedback: [["feedback-bar", "Thumbs up and down with a reason."]],
+  errors: [["error-state", "Says what went wrong and what to do."], ["refusal-notice", "Explains a refusal kindly."], ["rate-limit-notice", "Explains a limit and when it lifts."], ["callout", "A calm note inside a page."]],
+};
+
+const SITE = "https://lkb00.github.io/tattva";
+const FONTS = `<link href="https://fonts.googleapis.com/css2?family=Geist:wght@400..700&family=Geist+Mono:wght@400..600&display=swap" rel="stylesheet" />`;
+
+const setupSteps = (a) => {
+  const steps = [];
+  const stack = a.stack;
+  if (stack === "no-code") {
+    steps.push("Paste the prompt into your AI builder. It carries your choices and the rules, so you do not need to explain the design system.");
+    steps.push(`If the builder cannot install packages, give it the one-file source of every free part: ${SITE}/downloads/tattva-free-source.md, and ask it to copy the parts it needs into the project.`);
+    steps.push(`Add the colours: ${SITE}/downloads/tokens.css goes in the project's global stylesheet.${a.theme && a.theme !== "lime" ? ` Then set data-palette="${a.theme}" on the html element.` : ""}`);
+    steps.push("Pro parts cannot be installed by a builder. If the plan lists them, use the free parts or ask for a plain stand-in and swap in the Pro part later.");
+    return steps;
+  }
+  if (stack === "new-vite") steps.push("Create the app: `npm create vite@latest my-app -- --template react-ts`, then add Tailwind CSS v4: `npm install tailwindcss @tailwindcss/vite` and add the plugin to vite.config.");
+  else if (stack === "new-next") steps.push("Create the app: `npx create-next-app@latest` (TypeScript and Tailwind CSS v4 on), then keep the Tattva files under `src/`.");
+  else steps.push("Check the app uses React 18+ and Tailwind CSS v4. Tattva's tokens are written for v4.");
+  if (a.plan === "free") steps.push(`Install the free parts and the tokens from npm: \`npm install @tattva/ui\`. Create \`src/tattva.css\` holding \`@import "@tattva/ui/tokens.css";\` and \`@source "../node_modules/@tattva/ui/dist";\` (the tokens load Tailwind, so this replaces your own \`@import "tailwindcss";\`; the @source line lets Tailwind see the classes the parts use) and import it once at the top of the app entry (\`import "./tattva.css";\`).`);
+  else steps.push(`Add the tokens: download ${SITE}/downloads/tokens.css, save it as \`src/tokens/tokens.css\` and import it once at the top of the app entry (\`import "./tokens/tokens.css";\`).`);
+  steps.push(`Load the fonts (Geist and Geist Mono) by adding this to the page head: ${FONTS}`);
+  if (a.theme && a.theme !== "lime") steps.push(`Set the colour theme on the root element: \`<html data-palette="${a.theme}">\`.`);
+  if (a.mode === "dark") steps.push('Dark only: add `class="dark"` to the `<html>` element.');
+  else if (a.mode === "both") steps.push('Light and dark: toggle `class="dark"` on `<html>`, starting from `matchMedia("(prefers-color-scheme: dark)")` so it follows the device.');
+  if (a.plan === "free") steps.push("Import every part from the package only (`import { Message } from \"@tattva/ui\"`), never from a deep path. Pro parts are not in the package; they come with a Pro or Team plan.");
+  else steps.push("Install all the parts from the Pro zip: the person got `tattva-pro.zip` when they bought Pro or Team (check their email or the store's download page). Ask them for its path; do not look for it online. Unzip it so that its `tattva` folder lands in `src/` and its `tokens.css` replaces `src/tokens/tokens.css`. Import from that folder only (`import { ApprovalPrompt } from \"./tattva\"`, adjusting the relative path).");
+  return steps;
+};
+
+/** Files an agent can write as they are, so setup does not depend on it remembering the steps. */
+const setupFiles = (a, brief) => {
+  const files = [{ path: "tattva.md", why: "The project brief. Read it first in every session.", content: brief + "\n" }];
+  if (a.stack === "new-vite") {
+    const dark = a.mode === "dark" ? ' class="dark"' : "";
+    const palette = a.theme && a.theme !== "lime" ? ` data-palette="${a.theme}"` : "";
+    const script = a.mode === "both" ? `
+    <script>
+      (function () {
+        if (matchMedia("(prefers-color-scheme: dark)").matches) document.documentElement.classList.add("dark");
+      })();
+    </script>` : "";
+    files.push(
+      { path: "vite.config.ts", why: "React and Tailwind CSS v4.", content: `import { defineConfig } from "vite";\nimport react from "@vitejs/plugin-react";\nimport tailwindcss from "@tailwindcss/vite";\n\nexport default defineConfig({ plugins: [react(), tailwindcss()] });\n` },
+      { path: "index.html", why: `Fonts, ${a.theme === "lime" ? "the default theme" : `the ${a.theme} theme`}${a.mode === "both" ? " and light/dark that follows the device" : a.mode === "dark" ? " and dark mode" : ""}.`, content: `<!doctype html>\n<html lang="en"${dark}${palette}>\n  <head>\n    <meta charset="UTF-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1.0" />\n    <title>My app</title>\n    <link rel="preconnect" href="https://fonts.googleapis.com" />\n    ${FONTS}${script}\n  </head>\n  <body>\n    <div id="root"></div>\n    <script type="module" src="/src/main.tsx"></script>\n  </body>\n</html>\n` },
+      { path: "src/main.tsx", why: "Loads the tokens and renders App. You write src/App.tsx.", content: `import { StrictMode } from "react";\nimport { createRoot } from "react-dom/client";\nimport "${a.plan === "free" ? "./tattva.css" : "./tokens/tokens.css"}";\nimport { App } from "./App";\n\ncreateRoot(document.getElementById("root")!).render(<StrictMode><App /></StrictMode>);\n` },
+    );
+    if (a.plan === "free") files.push({ path: "src/tattva.css", why: "The Tattva tokens (they load Tailwind) and the package's classes.", content: `@import "@tattva/ui/tokens.css";\n@source "../node_modules/@tattva/ui/dist";\n` });
+  }
+  return files;
+};
+
+const setupCommands = (a) => a.stack === "no-code" ? [] : [
+  ...(a.stack === "new-vite" ? ["npm create vite@latest my-app -- --template react-ts", "cd my-app && npm install && npm install tailwindcss @tailwindcss/vite"] : []),
+  ...(a.plan === "free" ? ["npm install @tattva/ui"] : [`mkdir -p src/tokens && curl -fsSL ${SITE}/downloads/tokens.css -o src/tokens/tokens.css`, "unzip -oq <path to tattva-pro.zip> 'tattva/*' -d src && unzip -oqj <path to tattva-pro.zip> tokens.css -d src/tokens"]),
+  ...(a.stack === "new-vite" ? ["rm -f src/index.css src/App.css"] : []),
+];
+
+/** Builds the plan for an agent: setup, parts in order (with Pro marks), patterns to read and a brief to save. */
+export function planBuild(rawAnswers, components) {
+  const byId = new Map(components.map((c) => [c.id, c]));
+  const a = { product: "chat-assistant", stack: "new-vite", theme: "lime", mode: "both", trust: ["sources", "feedback"], plan: "free", ...Object.fromEntries(Object.entries(rawAnswers ?? {}).filter(([, v]) => v !== undefined && v !== null && v !== "")) };
+  if (typeof a.trust === "string") a.trust = a.trust.split(/[,\s]+/).filter(Boolean);
+  const recipe = RECIPES[a.product];
+  if (!recipe) return { error: `Unknown product "${a.product}". Use one of: ${Object.keys(RECIPES).join(", ")}.` };
+  const warnings = [];
+  const themes = ["lime", "teal", "indigo", "harbor", "plum", "graphite", "terminal"];
+  if (!themes.includes(a.theme)) { warnings.push(`Unknown theme "${a.theme}"; using lime. Themes: ${themes.join(", ")}.`); a.theme = "lime"; }
+  const unknownTrust = a.trust.filter((t) => !TRUST[t]);
+  if (unknownTrust.length) warnings.push(`Ignored unknown trust behaviours: ${unknownTrust.join(", ")}. Known: ${Object.keys(TRUST).join(", ")}.`);
+  const seen = new Set();
+  const parts = [];
+  const add = (list, group) => {
+    for (let [id, why] of list) {
+      if (seen.has(id)) continue; seen.add(id);
+      let c = byId.get(id);
+      if (!c) { warnings.push(`The part "${id}" was not found in this copy of Tattva, so it is left out.`); continue; }
+      const stage = c.lifecycle?.stage ?? c.status ?? "stable";
+      if ((stage === "deprecated" || stage === "retired") && c.lifecycle?.replacedBy && byId.get(c.lifecycle.replacedBy)) {
+        warnings.push(`${c.name} is ${stage}; using ${byId.get(c.lifecycle.replacedBy).name} instead.`);
+        c = byId.get(c.lifecycle.replacedBy); id = c.id;
+        if (seen.has(id)) continue; seen.add(id);
+      }
+      parts.push({ id, name: c.name, group, why, plan: c.plan ?? "free", stage: c.lifecycle?.stage ?? c.status ?? "stable", importLine: c.importPath });
+    }
+  };
+  add([[recipe.screen, `The page layout (${recipe.title}).`]], "Screen");
+  add(recipe.core, recipe.title);
+  for (const t of a.trust.filter((x) => TRUST[x])) add(TRUST[t], `Trust: ${t}`);
+  const pro = parts.filter((p) => p.plan === "pro");
+  if (a.plan === "free" && pro.length) warnings.push(`${pro.length} of ${parts.length} parts are Pro (${pro.slice(0, 6).map((p) => p.name).join(", ")}${pro.length > 6 ? ", ..." : ""}). Their previews and guidance are free, but their code comes with Pro or Team: ${SITE}/#pricing. Tell the person before relying on them, and offer the free parts first.`);
+  const brief = [
+    "# Tattva project brief", "",
+    "Saved by the Tattva MCP server. Read this first in every session so the product stays consistent.", "",
+    `- Product: ${recipe.title}`, `- Stack: ${a.stack}`, `- Theme: ${a.theme}${a.theme === "lime" ? " (default)" : ` (data-palette="${a.theme}")`}`, `- Mode: ${a.mode}`,
+    `- Trust behaviours: ${a.trust.join(", ") || "none"}`, `- Plan: ${a.plan}`, "",
+    "## Parts", ...parts.map((p) => `- ${p.name}${p.plan === "pro" ? " (Pro)" : ""}: ${p.why}`), "",
+    "## Rules", "- Import from the package index only.", "- Use tokens (`var(--surface)`), never hex values.", "- The AI colour (`--lime`) is a fill, never text. Amber means a person has to act.",
+    "- Every control has an accessible name. Status is never colour alone.", "- Run `review_code` on each file before finishing.",
+  ].join("\n");
+  return { answers: a, recipe: { product: a.product, title: recipe.title, screen: recipe.screen }, setup: setupSteps(a), commands: setupCommands(a), files: setupFiles(a, brief), parts, patterns: recipe.patterns, warnings, brief };
+}
+
+/**
+ * The one prompt a person pastes into an AI tool, from a plan. Written to the AI, not to the person.
+ * The Build brief page and the tests use this same function.
+ */
+export function buildPrompt(plan) {
+  const a = plan.answers;
+  const noCode = a.stack === "no-code";
+  const pro = plan.parts.filter((p) => p.plan === "pro");
+  const setup = noCode
+    ? [
+        `If you can install packages, run npm install @tattva/ui, put @import "@tattva/ui/tokens.css"; and @source "../node_modules/@tattva/ui/dist"; at the top of the main stylesheet (they replace @import "tailwindcss";), and import every part from "@tattva/ui". If you cannot install packages, read ${SITE}/downloads/tattva-free-source.md, which holds the source of every free part in one file, recreate the parts you need under src/tattva/ with the same file names, and import from there.`,
+        `If you used the source file, add the colours from ${SITE}/downloads/tokens.css to the project's global stylesheet.${a.theme && a.theme !== "lime" ? ` Set data-palette="${a.theme}" on the html element.` : ""}${a.mode === "both" ? " Toggle the dark class on the html element to follow the device's colour scheme." : a.mode === "dark" ? " Add the dark class to the html element." : ""}`,
+      ]
+    : plan.setup;
+  return [
+    `I want to build: ${plan.recipe.title}.`,
+    "",
+    `Use the Tattva design system. Read its guide first: ${SITE}/llms.txt (it links to a page for every part). Theme: ${a.theme}. Mode: ${a.mode === "both" ? "light and dark, following the device" : a.mode}.`,
+    "",
+    "Setup:",
+    ...setup.map((x, i) => `${i + 1}. ${x}`),
+    "",
+    "Use these parts, in this order:",
+    ...plan.parts.map((p) => `- ${p.name}${p.plan === "pro" ? " (Pro)" : ""}: ${p.why}`),
+    ...(pro.length ? ["", `Parts marked (Pro) have a free preview and guidance, but their code is not available to you. Build the screen from the free parts, and for each Pro part use a simple plain stand-in built from free parts, with a comment naming the Pro part so I can swap it in later.`] : []),
+    "",
+    "Rules:",
+    "- Import parts and icons only from the tattva folder, never from a deep path (icons are named like SendIcon and CopyIcon). Never write hex colours; use the tokens (var(--surface), var(--fg)).",
+    "- The AI colour marks AI only, and is never used as text. Amber means a person has to act.",
+    "- Every button and icon has a clear name. Status is never colour alone.",
+    "- If no part fits something I ask for, tell me and ask. Do not invent parts, props or colours.",
+    "",
+    "Project brief (save it as tattva.md and read it first next time):",
+    plan.brief,
+  ].join("\n");
+}
+
+/** The checks run by review_code. Each has a rule name, how serious it is, a test for one line, and how to fix it. */
+const CHECKS = [
+  { rule: "no-hex", level: "error", test: (l) => /(?<![\w&])#[0-9a-fA-F]{3,8}\b/.test(l.replace(/\b(?:href|to|xlinkHref)=["']#[^"']*["']/g, "").replace(/url\(#[^)]*\)/g, "")) && !/^\s*(\/\/|\*|\/\*)/.test(l) && /(color|bg-|text-|border|fill|stroke|background|style|className|#[0-9a-fA-F]{6}\b)/.test(l), fix: "Use a token: `var(--surface)`, `var(--fg)` or a class such as `bg-surface` and `text-fg-muted`. Ask get_tokens for the right name." },
+  { rule: "no-color-function", level: "error", test: (l) => /\b(rgb|rgba|hsl|hsla|oklch)\(/.test(l) && !/var\(|--/.test(l) && !/^\s*(\/\/|\*)/.test(l), fix: "Use a token instead of a raw colour function." },
+  { rule: "no-default-palette", level: "error", test: (l) => /\b(?:bg|text|border|ring|fill|stroke|from|to|via)-(?:red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone)-\d{2,3}\b/.test(l), fix: "Tailwind's default palette is not part of Tattva. Use classes built from tokens, such as `bg-surface`, `text-fg`, `border-line`, `bg-lime-soft`." },
+  { rule: "no-deep-import", level: "error", test: (l) => /from\s+["'][^"']*\/(?:atoms|molecules|organisms|templates|pages)\/[^"']*["']/.test(l), fix: "Import from the package index: `import { Message } from \"./index\"`." },
+  { rule: "no-div-click", level: "error", test: (l) => /<(?:div|span)\b[^>]*\bonClick=/.test(l) && !/role=["']button["']/.test(l), fix: "Use a real `<button>` (or Tattva's Button). A clickable div cannot be reached with the keyboard." },
+  { rule: "lime-as-text", level: "error", test: (l) => /\btext-lime\b|color:\s*var\(--lime\)/.test(l), fix: "The AI colour is a fill, never text colour. Put dark text on it (`text-on-lime`)." },
+  { rule: "focus-removed", level: "warn", test: (l) => /\b(?:focus:)?outline-none\b|outline:\s*none/.test(l) && !/focus-visible|ring/.test(l), fix: "Do not remove the focus outline. Tattva already draws one; keep it, or replace it with a visible ring." },
+  { rule: "vague-destructive", level: "warn", test: (l) => />\s*(?:Delete|Remove|Discard|Reset)\s*</.test(l), fix: "Say the effect: \"Delete project Atlas\", not \"Delete\"." },
+  { rule: "raw-html", level: "warn", test: (l) => /dangerouslySetInnerHTML/.test(l), fix: "Avoid raw HTML from the AI. Use Markdown, or put untrusted content in SandboxedFrame." },
+  { rule: "amber-check", level: "info", test: (l) => /\b(?:text|bg|border)-attention\b|var\(--attention/.test(l), fix: "Amber means a person has to act. Use it only for a \"needs you\" state, not for warnings or decoration." },
+  { rule: "colour-only-status", level: "info", test: (l) => /\b(?:text|bg)-(?:success|danger)\b/.test(l) && !/<(?:Icon|svg)|aria-label|sr-only/.test(l), fix: "Status must not rely on colour alone. Pair it with an icon and a word." },
+];
+
+/** Checks a piece of code against Tattva's rules. Returns findings with line numbers. */
+export function reviewCode(code, components = [], filename = "") {
+  const lines = String(code).split("\n");
+  const findings = [];
+  lines.forEach((line, i) => {
+    for (const c of CHECKS) if (c.test(line)) findings.push({ line: i + 1, rule: c.rule, level: c.level, text: line.trim().slice(0, 140), fix: c.fix });
+  });
+  // Tag checks: read the whole opening tag, so props on several lines are seen.
+  const src = String(code);
+  const tagOf = (from) => { let depth = 0; for (let k = from; k < src.length; k++) { const ch = src[k]; if (ch === "{") depth++; else if (ch === "}") depth--; else if (ch === ">" && depth === 0) return src.slice(from, k + 1); } return src.slice(from, from + 400); };
+  for (const [re, attr, rule, fix] of [
+    [/<IconButton\b/g, /\blabel=/, "icon-button-label", "Every IconButton needs a `label` that names what it does, such as `label=\"Copy reply\"`."],
+    [/<img\b/g, /\balt=/, "img-alt", "Give every image an `alt`, or `alt=\"\"` if it is decoration."],
+  ]) for (const m of src.matchAll(re)) { const tag = tagOf(m.index); if (!attr.test(tag) && !/\{\.\.\.\w+\}/.test(tag)) findings.push({ line: src.slice(0, m.index).split("\n").length, rule, level: "error", text: tag.split("\n")[0].trim().slice(0, 140), fix }); }
+  // Parts that are on their way out.
+  for (const c of components) {
+    const l = c.lifecycle; if (!l || (l.stage !== "deprecated" && l.stage !== "retired")) continue;
+    const re = new RegExp(`<${c.name}\\b`, "g");
+    for (const m of src.matchAll(re)) findings.push({ line: src.slice(0, m.index).split("\n").length, rule: `${l.stage}-part`, level: l.stage === "retired" ? "error" : "warn", text: `<${c.name}>`, fix: `${c.name} is ${l.stage}${l.removeIn ? ` (removed in ${l.removeIn})` : ""}. ${l.note ?? ""} Use ${components.find((x) => x.id === l.replacedBy)?.name ?? l.replacedBy} instead.` });
+  }
+  // Names imported from the package index must exist.
+  const names = new Set(components.map((c) => c.name));
+  const ids = components.map((c) => c.id);
+  for (const m of String(code).matchAll(/import\s*\{([^}]+)\}\s*from\s*["']([^"']+)["']/g)) {
+    if (!/(^|\/)(index|tattva)$/.test(m[2]) && !/tattva/.test(m[2])) continue;
+    const at = String(code).slice(0, m.index).split("\n").length;
+    for (const raw of m[1].split(",")) {
+      const n = raw.trim().split(/\s+as\s+/)[0];
+      if (!n || names.has(n) || !/^[A-Z]/.test(n)) continue;
+      const near = ids.map((id) => ({ id, d: lev(n.toLowerCase(), id.replace(/-/g, "")) })).sort((x, y) => x.d - y.d)[0];
+      findings.push({ line: at, rule: "unknown-part", level: "error", text: raw.trim(), fix: `"${n}" is not a Tattva part.${near && near.d <= 6 ? ` Did you mean "${components.find((c) => c.id === near.id).name}"?` : ""} Call search_components to find the right one.` });
+    }
+  }
+  findings.sort((x, y) => x.line - y.line);
+  const order = { error: 0, warn: 1, info: 2 };
+  return { filename, findings, counts: { error: findings.filter((f) => f.level === "error").length, warn: findings.filter((f) => f.level === "warn").length, info: findings.filter((f) => f.level === "info").length }, order };
+}
+
+function lev(a, b) {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+}

package/mcp-server.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// Tattva MCP server. Zero dependencies. Speaks newline-delimited JSON-RPC 2.0 over stdio.
+// Read-only: it reads public/components.json, public/tokens.dtcg.json, public/themes.json and public/llms.txt and never writes.
+// Run `node scripts/export-assets.mjs` first so those files exist.
+import { readFileSync, existsSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { QUESTIONS, planBuild, reviewCode } from "./mcp-guide.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PROTOCOL = "2025-06-18";
+const SITE = "https://lkb00.github.io/tattva/";
+// Settings are read as TATTVA_*; the names from before the rename (SANDSTONE_*) still work.
+for (const k of ["DATA", "API", "LICENSE_KEY"]) if (!process.env[`TATTVA_${k}`] && process.env[`SANDSTONE_${k}`]) process.env[`TATTVA_${k}`] = process.env[`SANDSTONE_${k}`];
+// Where the data files come from, in this order: a folder named in TATTVA_DATA; a `data` folder next to this file
+// (the Pro download ships one, with the full code); `../public` (inside the Tattva repo); the live site (the small
+// public download needs nothing else, so the free parts and every part's guidance still work).
+const DATA_DIRS = [process.env.TATTVA_DATA, join(here, "data"), join(here, "..", "public")].filter(Boolean);
+const FILES = ["components.json", "tokens.dtcg.json", "themes.json", "llms.txt"];
+const data = {};
+const dataDir = DATA_DIRS.find((d) => FILES.every((f) => existsSync(join(d, f))));
+for (const f of FILES) {
+  if (dataDir) { data[f] = readFileSync(join(dataDir, f), "utf8"); continue; }
+  try {
+    const r = await fetch(SITE + f);
+    if (!r.ok) throw new Error(String(r.status));
+    data[f] = await r.text();
+  } catch (e) {
+    process.stderr.write(`Tattva MCP: could not read ${f} locally or from ${SITE} (${e.message}). Check your internet connection, or set TATTVA_DATA to a folder holding the four data files.\n`);
+    process.exit(1);
+  }
+}
+// Pro and Team buyers can add their licence key instead of keeping the Pro download's data folder:
+// TATTVA_LICENSE_KEY=<key from the receipt email>, and TATTVA_API=<the Tattva API address>. The API checks the
+// key and sends every part with its full code. If the check fails, the server says why and carries on with the free data.
+if (process.env.TATTVA_LICENSE_KEY && process.env.TATTVA_API && !process.env.TATTVA_DATA) {
+  try {
+    const r = await fetch(new URL("v1/pro/components.json", process.env.TATTVA_API.replace(/\/?$/, "/")), { headers: { authorization: `Bearer ${process.env.TATTVA_LICENSE_KEY.trim()}` } });
+    const body = await r.text();
+    if (r.ok) data["components.json"] = body;
+    else process.stderr.write(`Tattva MCP: Pro code stays locked. ${JSON.parse(body).message ?? r.status}\n`);
+  } catch (e) {
+    process.stderr.write(`Tattva MCP: could not reach the Tattva API (${e.message}), so Pro code stays locked. The free parts and all guidance still work.\n`);
+  }
+}
+const readJson = (rel) => JSON.parse(data[rel.replace(/^public\//, "")]);
+const components = () => readJson("public/components.json").components;
+
+const lev = (a, b) => {
+  const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 1; j <= b.length; j++) d[0][j] = j;
+  for (let i = 1; i <= a.length; i++) for (let j = 1; j <= b.length; j++) d[i][j] = Math.min(d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+  return d[a.length][b.length];
+};
+const norm = (s) => String(s).toLowerCase().replace(/[^a-z0-9]/g, "");
+const suggest = (q, list) => {
+  const n = norm(q);
+  return list.map((c) => ({ c, s: norm(c.id).includes(n) || n.includes(norm(c.id)) ? 0 : lev(n, norm(c.id)) })).sort((a, b) => a.s - b.s).slice(0, 4).map((x) => x.c.id);
+};
+
+const fail = (message) => ({ isError: true, content: [{ type: "text", text: message }] });
+const ok = (text, structured) => ({ content: [{ type: "text", text }], structuredContent: structured });
+
+const tools = [
+  {
+    name: "search_components",
+    description: "Find Tattva components by what they are for. Searches names, summaries and descriptions. Use this first when you do not know the component id. Returns up to 15 matches with id, name, category, status and a one-line summary. Read-only.",
+    inputSchema: { type: "object", properties: {
+      query: { type: "string", description: "Words describing what you need, for example \"ask before deleting\" or \"chart\". Leave empty to list everything in a category." },
+      category: { type: "string", description: "Optional. One of: conversation, agents, trust, creating, numbers, states, controls, screens." },
+      status: { type: "string", enum: ["stable", "experimental"], description: "Optional. Experimental parts rest on design reasoning only and may change." },
+    }, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: "get_component",
+    description: "Get everything needed to use one Tattva component correctly: props with types and defaults, when to use it, what to avoid, accessibility rules, the exact import line, tokens it uses and one example. Call it with an id from search_components. Read-only.",
+    inputSchema: { type: "object", properties: {
+      id: { type: "string", description: "Component id in kebab-case, for example \"permission-prompt\". The component name (PermissionPrompt) also works." },
+      all_examples: { type: "boolean", description: "Return every example instead of the first one. Default false." },
+    }, required: ["id"], additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: "list_patterns",
+    description: "List Tattva's patterns: short answers to situations like \"the assistant wants to do something that cannot be undone\". Each has a question, an answer and a page link. Use this to choose an approach before choosing components. Read-only.",
+    inputSchema: { type: "object", properties: { query: { type: "string", description: "Optional word filter, for example \"source\" or \"undo\"." } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: "start_project",
+    description: "Call this FIRST when a person wants to build something with Tattva, unless a tattva.md brief already exists in their project (then read it instead). Returns a short list of questions to ask the person, each with options and a default. Ask them in plain words, skip any the person has already answered, and accept \"defaults\". Then call plan_build with the answers. Read-only.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: "plan_build",
+    description: "Turn the person's answers into a build plan: setup steps, the parts to use in build order (marking which are Pro), patterns to read, warnings, and a project brief to save as tattva.md in their project. Call it after start_project. Missing answers fall back to defaults. Read-only.",
+    inputSchema: { type: "object", properties: {
+      product: { type: "string", enum: ["chat-assistant", "agent-console", "creative-tool", "generative-ui", "ai-dashboard"], description: "What is being built." },
+      stack: { type: "string", enum: ["new-vite", "new-next", "existing"], description: "New or existing project, and framework." },
+      theme: { type: "string", enum: ["lime", "teal", "indigo", "harbor", "plum", "graphite"], description: "Colour theme. Default lime." },
+      mode: { type: "string", enum: ["both", "light", "dark"], description: "Light, dark or both. Default both." },
+      trust: { type: "array", items: { type: "string", enum: ["sources", "confidence", "approvals", "undo", "memory", "disclosure", "feedback", "errors"] }, description: "Trust behaviours the product needs." },
+      plan: { type: "string", enum: ["free", "pro"], description: "The person's plan. Default free." },
+    }, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: "review_code",
+    description: "Check code you wrote against Tattva's rules before you finish: typed hex colours, raw colour functions, Tailwind's default palette, deep imports, clickable divs, icon buttons with no label, images with no alt, lime used as text, removed focus outlines, vague destructive buttons, and parts that do not exist. Pass the file's code. Fix every error and re-run until none are left. Read-only; nothing is written.",
+    inputSchema: { type: "object", properties: {
+      code: { type: "string", description: "The full source of one file (TSX, JSX, CSS or HTML)." },
+      filename: { type: "string", description: "Optional file name, shown in the result." },
+    }, required: ["code"], additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: "get_themes",
+    description: "List Tattva's colour themes (lime, teal, indigo, harbor, plum, graphite, terminal) or get one in full: its AI color in light and dark, paper and ink, the two soft wash colors, how to switch to it, and every token that differs from the default. A theme changes the greys and the AI color only; amber and the status colors never change. Read-only.",
+    inputSchema: { type: "object", properties: { id: { type: "string", description: "Optional theme id, for example \"indigo\". Omit to list all themes." } }, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+  {
+    name: "get_tokens",
+    description: "Get Tattva design tokens (colors, timing, sizes, shadows) with what each is for. Use token names in CSS as var(--name) or as Tailwind classes. Never type a hex value in generated code. Read-only.",
+    inputSchema: { type: "object", properties: {
+      group: { type: "string", description: "Optional group: surfaces, lines, text, actions, attention, status, direction, reserved, code, charts, size, motion, shadow. Omit to list the group names with counts." },
+      mode: { type: "string", enum: ["light", "dark"], description: "Light or dark values. Default light." },
+      theme: { type: "string", description: "Optional colour theme id (see get_themes), for example \"indigo\". Returns that theme's colors. Default lime." },
+    }, additionalProperties: false },
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+  },
+];
+
+const handlers = {
+  search_components({ query = "", category, status } = {}) {
+    const all = components();
+    const cats = [...new Set(all.map((c) => c.category).filter(Boolean))];
+    if (category && !cats.includes(category)) return fail(`Unknown category "${category}". Use one of: ${cats.join(", ")}.`);
+    // Plain-language search: drop filler words, match word stems, and let rare words count for more than common ones.
+    const STOP = new Set("a an the and or of to for in on at by with from into is are be it its this that these those i we you your my our me us user users person people need needs want wants let lets make makes show shows showing display displays place way something thing things when while before after so can should would could will do does how what which where who ai".split(" "));
+    const stem = (w) => w.replace(/(ing|ed|es|s|ly)$/, (m, x, i) => (i > 3 ? "" : m));
+    const tok = (t) => String(t).toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/[\s-]+/).filter(Boolean);
+    const SAME = { got: "came", get: "come", gets: "comes", citation: "source", citations: "sources", cite: "source", reference: "source", references: "sources" };
+    const words = [...new Set(tok(query).filter((w) => !STOP.has(w)).map((w) => stem(SAME[w] ?? w)))].filter((w) => w.length > 1);
+    const field = (c) => ({
+      name: tok(`${c.id} ${c.name}`).map(stem),
+      head: tok(`${c.summary} ${c.purpose ?? ""} ${(c.useFor ?? []).join(" ")}`).map(stem),
+      body: tok(`${c.description} ${c.whenToUse.join(" ")}`).map(stem),
+    });
+    const pool = all.filter((c) => (!category || c.category === category) && (!status || c.status === status));
+    const fields = new Map(pool.map((c) => [c, field(c)]));
+    const df = (w) => pool.filter((c) => { const f = fields.get(c); return f.name.includes(w) || f.head.includes(w) || f.body.includes(w); }).length;
+    const idf = new Map(words.map((w) => [w, Math.log(1 + pool.length / (1 + df(w)))]));
+    const scored = pool.map((c) => {
+      const f = fields.get(c);
+      let s = 0;
+      for (const w of words) s += idf.get(w) * ((f.name.includes(w) ? 5 : 0) + (f.head.includes(w) ? 3 : 0) + (f.body.includes(w) ? 1 : 0));
+      return { c, s };
+    }).filter((x) => !words.length || x.s > 0).sort((a, b) => b.s - a.s);
+    const results = scored.slice(0, 15).map(({ c }) => ({ id: c.id, name: c.name, category: c.category, status: c.status, summary: c.summary }));
+    if (!results.length) return ok(`No components match "${query}". Try fewer or simpler words, or filter by category: ${cats.join(", ")}.`, { results: [], total: 0 });
+    const text = `${scored.length} match${scored.length === 1 ? "" : "es"}${scored.length > 15 ? " (showing 15)" : ""}:\n` + results.map((r) => `- ${r.id} (${r.name}, ${r.category}, ${r.status}): ${r.summary}`).join("\n") + "\nNext: call get_component with an id.";
+    return ok(text, { results, total: scored.length });
+  },
+  get_component({ id, all_examples = false } = {}) {
+    if (!id) return fail("Missing `id`. Call search_components first to find one, for example id: \"button\".");
+    const all = components();
+    const n = norm(id);
+    let c = all.find((x) => x.id === id) ?? all.find((x) => norm(x.id) === n || norm(x.name) === n);
+    if (!c) return fail(`No component called "${id}". Did you mean: ${suggest(id, all).join(", ")}? Call search_components to browse.`);
+    // The docs are written for the Tattva repo (./index). In a person's project free parts come from the npm package
+    // and Pro parts from the tattva folder of the Pro download.
+    const toKit = (x) => String(x).replace(/from "\.\/index"/g, c.plan === "pro" ? 'from "./tattva"' : 'from "@tattva/ui"');
+    c = { ...c, importPath: toKit(c.importPath) };
+    const examples = (all_examples ? c.examples : c.examples.slice(0, 1)).map((e) => ({ ...e, code: toKit(e.code) }));
+    const data = {
+      id: c.id, name: c.name, level: c.level, category: c.category, status: c.status, lifecycle: c.lifecycle ?? null, states: c.states ?? [], summary: c.summary, description: c.description,
+      importPath: c.importPath, sourcePath: c.sourcePath,
+      props: c.props, variantsHint: c.variantsHint,
+      purpose: c.purpose ?? null, useFor: c.useFor ?? [], notFor: c.notFor ?? [],
+      whenToUse: c.whenToUse, avoid: c.avoid, accessibility: c.accessibility, accessibilityYouDo: c.accessibilityYouDo ?? [],
+      tokens: c.tokens, related: c.related, composedOf: c.composedOf, examples, pageUrl: c.pageUrl, markdownUrl: c.markdownUrl,
+    };
+    const list = (a) => a.map((x) => `- ${x}`).join("\n");
+    const text = [
+      `${c.name} (${c.id}, ${c.level}, ${c.status})`, c.summary,
+      c.lifecycle && (c.lifecycle.stage === "deprecated" || c.lifecycle.stage === "retired") ? `WARNING: ${c.name} is ${c.lifecycle.stage}. ${c.lifecycle.note ?? ""} Use ${c.lifecycle.replacedBy} instead.` : "",
+      "", c.importPath, "",
+      "Props:", ...c.props.map((p) => `- ${p.name}${p.required ? " (required)" : ""}: ${p.type}${p.default ? ` = ${p.default}` : ""}. ${p.description}`), "",
+      c.purpose ? `When to use it: ${c.purpose}` : "", c.notFor?.length ? `Not for:\n${list(c.notFor.map((n) => n.use ? `${n.text}: use ${n.use}` : n.text))}` : "",
+      "Do:", list(c.whenToUse), "Avoid:", list(c.avoid), "Accessibility (built in):", list(c.accessibility),
+      c.accessibilityYouDo?.length ? `Accessibility (you must):\n${list(c.accessibilityYouDo)}` : "",
+      c.states?.length ? `States:\n${list(c.states.map((x) => `${x.name}: ${x.note}`))}` : "",
+      c.related.length ? `Related: ${c.related.join(", ")}` : "",
+      "", ...examples.flatMap((e) => [`Example: ${e.title}`, "```tsx", e.code, "```"]),
+    ].filter((x) => x !== "").join("\n");
+    return ok(text, data);
+  },
+  list_patterns({ query = "" } = {}) {
+    const txt = data["llms.txt"];
+    const sec = txt.split(/^## /m).find((s) => s.startsWith("Patterns")) ?? "";
+    let patterns = sec.split("\n").filter((l) => l.startsWith("- ")).map((l) => {
+      const m = l.match(/^- ([^:]+): (.*) \((https?:\/\/[^)]+)\)$/);
+      if (!m) return null;
+      const url = m[3]; const q = m[2].match(/^(.*?\?)\s*(.*)$/);
+      return { id: url.split("#pattern-")[1] ?? "", title: m[1], question: q ? q[1] : "", answer: q ? q[2] : m[2], url };
+    }).filter(Boolean);
+    const words = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+    if (words.length) patterns = patterns.filter((p) => words.some((w) => `${p.title} ${p.question} ${p.answer}`.toLowerCase().includes(w)));
+    if (!patterns.length) return ok(`No patterns match "${query}". Call list_patterns with no query to see all of them.`, { patterns: [] });
+    return ok(patterns.map((p) => `- ${p.title}: ${p.question} ${p.answer}\n  ${p.url}`).join("\n"), { patterns });
+  },
+  start_project() {
+    const lines = QUESTIONS.map((q, i) => `${i + 1}. ${q.question}\n${q.options.map((o) => `   - ${o.value}: ${o.label}${(Array.isArray(q.default) ? q.default.includes(o.value) : q.default === o.value) ? "  [default]" : ""}`).join("\n")}`);
+    return ok(["Before building, ask the person these questions in plain words (one message, not one at a time). Skip any they have already answered. If they say \"defaults\", use the defaults.", "", ...lines, "", "Then call plan_build with the answers. If the project already has a tattva.md brief, read it and only ask what is missing."].join("\n"), { questions: QUESTIONS });
+  },
+  plan_build(args = {}) {
+    const r = planBuild(args, components());
+    if (r.error) return fail(r.error);
+    const groups = [...new Set(r.parts.map((p) => p.group))];
+    const text = [
+      `Plan: ${r.recipe.title}. Theme ${r.answers.theme}, ${r.answers.mode} mode, ${r.answers.plan} plan.`, "",
+      "Setup:", ...r.setup.map((x, i) => `${i + 1}. ${x}`), "",
+      "Run these commands, in order:", ...r.commands.map((c) => `  ${c}`), "",
+      "Write these files exactly as given (overwrite the ones the template created):", ...r.files.flatMap((f) => ["", `--- ${f.path} (${f.why}) ---`, f.content.trimEnd()]), "",
+      "Setup is not finished until the commands have run and every file above is written. Then you write src/App.tsx, importing parts from \"./tattva\". On the free plan the kit holds the free parts only: if the plan lists Pro parts, their code is not installed, so tell the person and do not pretend they are there. On Pro or Team, ask the person where their tattva-pro.zip is.", "",
+      "Parts, in build order:", ...groups.flatMap((g) => [`${g}:`, ...r.parts.filter((p) => p.group === g).map((p) => `- ${p.name} (${p.id})${p.plan === "pro" ? " [Pro]" : ""}: ${p.why}`)]), "",
+      `Patterns to read first: call list_patterns with the words ${r.patterns.map((x) => `"${x}"`).join(", ")}.`,
+      ...(r.warnings.length ? ["", "Heads up:", ...r.warnings.map((w) => `- ${w}`)] : []),
+      "", "Next: for each part call get_component for its props and an example, then build. When a file is done, call review_code on it and fix every error.", "", "(The brief is written to tattva.md above.)",
+    ].join("\n");
+    return ok(text, r);
+  },
+  review_code({ code, filename = "" } = {}) {
+    if (typeof code !== "string" || !code.trim()) return fail("Pass the file's source as `code`.");
+    const r = reviewCode(code, components(), filename);
+    const label = filename ? ` in ${filename}` : "";
+    if (!r.findings.length) return ok(`No problems found${label}. The code follows the Tattva rules this checker can see. It cannot judge layout or wording, so still check the result on screen.`, r);
+    const text = [`${r.counts.error} error${r.counts.error === 1 ? "" : "s"}, ${r.counts.warn} warning${r.counts.warn === 1 ? "" : "s"}, ${r.counts.info} note${r.counts.info === 1 ? "" : "s"}${label}. Fix the errors and run review_code again.`, "", ...r.findings.map((f) => `line ${f.line} [${f.level}] ${f.rule}: ${f.text}\n   Fix: ${f.fix}`)].join("\n");
+    return ok(text, r);
+  },
+  get_themes({ id } = {}) {
+    const all = readJson("public/themes.json").themes;
+    if (!id) {
+      const lines = all.map((t) => `- ${t.id}${t.default ? " (default)" : ""}: ${t.name}, ${t.note}. AI color ${t.ai.light} (light) / ${t.ai.dark} (dark). Use: ${t.use}`);
+      return ok(`Tattva colour themes. A theme changes the greys and the AI color (--lime) in light and dark. Amber and the status colors never change. Switch with data-palette on the html element.\n${lines.join("\n")}\nCall get_themes with an id for the full set of values.`, { themes: all.map(({ colors, ...t }) => t) });
+    }
+    const t = all.find((x) => x.id === String(id).toLowerCase());
+    if (!t) return fail(`No theme called "${id}". Use one of: ${all.map((x) => x.id).join(", ")}.`);
+    const n = (o) => Object.keys(o).length;
+    const lines = [`${t.name}${t.default ? " (default)" : ""}: ${t.note}`, `Use: ${t.use}`, `AI color (--lime): ${t.ai.light} light, ${t.ai.dark} dark`, `Paper (--bg): ${t.paper.light} light, ${t.paper.dark} dark`, `Ink (--fg): ${t.ink.light} light, ${t.ink.dark} dark`, `Soft wash (--ai-wash-1, --ai-wash-2): ${t.wash.light?.join(", ")} light${t.wash.dark ? `; ${t.wash.dark.join(", ")} dark` : ""}`, `Tokens that differ from the default: ${n(t.colors.light)} light, ${n(t.colors.dark)} dark. Call get_tokens with theme "${t.id}" to read them. In code, keep using var(--name); never type these hex values.`];
+    return ok(lines.join("\n"), t);
+  },
+  get_tokens({ group, mode = "light", theme } = {}) {
+    if (!["light", "dark"].includes(mode)) return fail(`Unknown mode "${mode}". Use "light" or "dark".`);
+    const t = readJson("public/tokens.dtcg.json");
+    let themeColors = null;
+    if (theme) {
+      const th = readJson("public/themes.json").themes.find((x) => x.id === String(theme).toLowerCase());
+      if (!th) return fail(`No theme called "${theme}". Call get_themes to see the ids.`);
+      themeColors = th.colors[mode];
+    }
+    const cols = t.color[mode];
+    const names = { surfaces: "color", lines: "color", text: "color", actions: "color", attention: "color", status: "color", code: "color", charts: "color", other: "color", size: "size", fontSize: "fontSize", motion: "duration", shadow: "shadow" };
+    const flat = (g, kind, o) => Object.entries(o).filter(([k]) => !k.startsWith("$")).map(([k, v]) => {
+      const val = v.$type === "color" ? v.$value.hex : v.$type === "duration" || v.$type === "dimension" ? `${v.$value.value}${v.$value.unit}` : v.$type === "cubicBezier" ? `cubic-bezier(${v.$value.join(", ")})` : v.$type === "shadow" ? (v.$extensions?.css ?? JSON.stringify(v.$value)) : JSON.stringify(v.$value);
+      return { name: `--${k}`, type: v.$type, value: val, description: v.$description ?? "", group: g };
+    });
+    const groups = {};
+    for (const [g, o] of Object.entries(cols)) groups[g] = flat(g, "color", o).map((x) => (themeColors?.[x.name] ? { ...x, value: themeColors[x.name] } : x));
+    groups.size = [...flat("size", "dimension", t.size ?? {}), ...flat("size", "dimension", t.fontSize ?? {})];
+    groups.motion = [...flat("motion", "duration", t.duration ?? {}), ...flat("motion", "cubicBezier", t.easing ?? {})];
+    groups.shadow = flat("shadow", "shadow", t.shadow?.[mode] ?? {});
+    if (!group) {
+      const summary = Object.entries(groups).map(([g, a]) => ({ group: g, count: a.length }));
+      return ok(`Token groups (${mode}): ${summary.map((s) => `${s.group} (${s.count})`).join(", ")}.\nCall get_tokens with a group to see names and values. Use names as var(--name). Never write hex values in components.`, { mode, groups: summary });
+    }
+    if (!groups[group]) return fail(`No token group called "${group}". Use one of: ${Object.keys(groups).join(", ")}.`);
+    return ok(groups[group].map((x) => `${x.name} = ${x.value}${x.description ? `  (${x.description})` : ""}`).join("\n"), { mode, group, tokens: groups[group] });
+  },
+};
+
+const send = (m) => process.stdout.write(JSON.stringify(m) + "\n");
+const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+const error = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+function handle(msg) {
+  const { id, method, params } = msg;
+  const isNote = id === undefined || id === null;
+  if (method === "initialize") {
+    return reply(id, { protocolVersion: params?.protocolVersion ?? PROTOCOL, capabilities: { tools: { listChanged: false }, prompts: { listChanged: false } }, serverInfo: { name: "tattva", version: "0.1.0" },
+      instructions: "Tattva is a design system for AI products. To build something: (1) if the project has a tattva.md brief, read it; otherwise call start_project and ask the person its questions, then call plan_build, then run its commands and write its files exactly as given before anything else. (2) For each part call get_component, then import from the package index. (3) Use tokens, never hex values. The AI colour (--lime) is a fill, never text; amber means a person has to act. (4) If nothing fits what the person asked for, say so and ask; never invent a part, a prop or a colour. (5) Before finishing, call review_code on every file you wrote and fix all errors. Parts marked Pro have free previews but code that needs a Pro or Team plan; tell the person before using them." });
+  }
+  if (method === "notifications/initialized" || method?.startsWith("notifications/")) return;
+  if (method === "ping") return reply(id, {});
+  if (method === "tools/list") return reply(id, { tools });
+  if (method === "prompts/list") return reply(id, { prompts: [{ name: "build", title: "Build with Tattva", description: "Start a guided build: a few questions, then a plan, then a check of the code.", arguments: [{ name: "idea", description: "Optional: what you want to build, in a sentence.", required: false }] }] });
+  if (method === "prompts/get") {
+    if (params?.name !== "build") return error(id, -32602, `Unknown prompt "${params?.name}". Available: build.`);
+    const idea = params?.arguments?.idea ? ` The person wants to build: ${params.arguments.idea}.` : "";
+    return reply(id, { description: "Build with Tattva", messages: [{ role: "user", content: { type: "text", text: `Help me build a product with the Tattva design system.${idea} Start by calling the start_project tool and ask me its questions, then call plan_build, then build it part by part, and run review_code on every file before you finish.` } }] });
+  }
+  if (method === "tools/call") {
+    const h = handlers[params?.name];
+    if (!h) return reply(id, fail(`Unknown tool "${params?.name}". Available tools: ${tools.map((t) => t.name).join(", ")}.`));
+    try { return reply(id, h(params.arguments ?? {})); } catch (e) { return reply(id, fail(String(e.message ?? e))); }
+  }
+  if (!isNote) error(id, -32601, `Method not found: ${method}`);
+}
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return error(null, -32700, "Parse error: send one JSON-RPC message per line."); }
+  try { handle(msg); } catch (e) { if (msg.id !== undefined) error(msg.id, -32603, String(e.message ?? e)); }
+});

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@tattva/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.11.1",
+  "description": "The Tattva MCP server: lets Claude Code, Cursor and other AI tools look up Tattva parts, plan a build and check code.",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://lkb00.github.io/tattva/connect-ai/",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "design-system",
+    "tattva",
+    "claude",
+    "cursor"
+  ],
+  "type": "module",
+  "bin": {
+    "tattva-mcp": "mcp-server.mjs"
+  },
+  "files": [
+    "mcp-server.mjs",
+    "mcp-guide.mjs",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}