shadertown 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,7 +6,57 @@ deploys, not by this file.
 This project follows [semantic versioning](https://semver.org). Before 1.0 the
 minor number carries breaking changes, so pin it if that matters to you.
 
-## 0.4.0 — 2026-08-30
+## 0.6.0 — 2026-08-30
+
+The CLI learns to talk to coding agents. `npx shadertown mcp` serves the
+catalogue over the Model Context Protocol, so an agent can search shaders,
+read every control with its range and meaning, and vendor tuned source into
+the project it is working on — through the same registry route and the same
+licence rules as `shadertown add`.
+
+### Added
+
+- **`shadertown mcp`.** A dependency-free MCP server over stdio with four
+  tools: `search_shaders`, `get_shader`, `install_shader`, and
+  `account_status`. Discovery and control schemas are answered locally from
+  the registry this package already ships; installing goes through
+  `/r/<slug>.json`, so Free shaders vendor for anyone and Professional
+  source asks for the paid plan exactly as the CLI does. Connect an agent
+  with `npx add-mcp "npx -y shadertown@latest mcp" -n shadertown`.
+
+## 0.5.0 — 2026-08-30
+
+Three shaders that remember: a `compute` kind whose state lives in GPU
+buffers and steps forward before every draw, so what you see is a
+simulation answering the pointer, not a picture pretending to.
+
+### Added
+
+- **`particles`.** 131,072 embers riding a curl-noise wind, deposited into a
+  long exposure that never quite forgets — trails are history and colour is
+  speed. The pointer is a vortex; push its charge below zero and the swarm
+  scatters instead.
+- **`fluid`.** The incompressible Navier–Stokes equations, solved for real:
+  semi-Lagrangian advection, twenty warm-started pressure sweeps, vorticity
+  confinement, and dye on a grid finer than the velocity that carries it.
+  Drag to splat force and ink together; idle, it throws plumes of its own.
+- **`cloth`.** A verlet sheet of two and a half thousand points relaxing
+  twelve distance constraints in parallel, hung from its pins in a two-speed
+  wind. With no vertex pipeline in the runtime it rasterises itself through
+  an atomic depth buffer, and the pointer carries an invisible sphere the
+  folds drape around.
+- The `compute` shader kind behind them. The runtime allocates each shader's
+  storage buffers, dispatches its `@compute` entry points ahead of the draw,
+  and rebinds what the fragment stage reads — through `ShaderCanvas` or
+  `createShaderRenderer` nothing changes on your side. Forty-five shaders in
+  total.
+
+### Changed
+
+- Grain now defaults to 0 across the whole catalogue. It was a texture
+  everything arrived wearing; it is now an effect you reach for.
+
+
 
 Ten shaders built around input: six that answer the pointer, four made for
 text, and a `{ text }` source so the text ones have something to answer.

package/README.md

@@ -27,10 +27,21 @@ repository, as files you own:
 npx shadertown add aurora
 ```
 
+## Give it to your coding agent
+
+The CLI is also an MCP server. One command configures Claude Code, Cursor,
+VS Code, Windsurf, Codex, and friends, and the agent can search the
+catalogue, read every control, and vendor tuned source into the project on
+its own:
+
+```bash
+npx add-mcp "npx -y shadertown@latest mcp" -n shadertown
+```
+
 ## Licensing
 
-This package is MIT, and it draws all 42 shaders. What a licence buys is the
-readable source: 3 shaders hand theirs to anyone, the other 15 need
+This package is MIT, and it draws all 45 shaders. What a licence buys is the
+readable source: 13 shaders hand theirs to anyone, the other 32 need
 [Professional](https://www.shadertown.com/pricing). Source you have already
 vendored keeps working either way.
 

package/cli/cli.mjs

@@ -1,19 +1,17 @@
-import { mkdir, readFile, writeFile, access, chmod, rm } from "node:fs/promises";
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
-import { homedir } from "node:os";
 import { spawn } from "node:child_process";
-
-const DEFAULT_REGISTRY = process.env.SHADERTOWN_REGISTRY ?? "https://www.shadertown.com";
-const DEFAULT_OUT = "src/shaders";
-
-const esc = (code, text) => `\u001b[${code}m${text}\u001b[0m`;
-const c = {
-  dim: (s) => esc(2, s),
-  bold: (s) => esc(1, s),
-  green: (s) => esc(32, s),
-  cyan: (s) => esc(36, s),
-  yellow: (s) => esc(33, s),
-};
+import {
+  c,
+  CREDENTIALS_PATH,
+  DEFAULT_OUT,
+  DEFAULT_REGISTRY,
+  exists,
+  readProjectConfig,
+  readToken,
+  relative,
+  writeToken,
+} from "./shared.mjs";
 
 export async function run(argv) {
   const [command, ...rest] = argv;
@@ -30,6 +28,10 @@ export async function run(argv) {
       return logout();
     case "whoami":
       return whoami();
+    // Imported when asked for: the MCP server is the rare path, and `add`
+    // should not pay for it at startup.
+    case "mcp":
+      return (await import("./mcp.mjs")).serve();
     case undefined:
     case "help":
     case "--help":
@@ -63,42 +65,6 @@ function parseFlags(args) {
   return { flags, positional };
 }
 
-/** Reads shadertown.config.ts without executing it - only the fields we need. */
-async function readProjectConfig(cwd) {
-  for (const file of ["shadertown.config.ts", "shadertown.config.js", "shadertown.config.mjs"]) {
-    try {
-      const source = await readFile(join(cwd, file), "utf8");
-      const pick = (key) => source.match(new RegExp(`${key}\\s*:\\s*["\'\`]([^"\'\`]+)`))?.[1];
-      return { outDir: pick("outDir"), registry: pick("registry"), license: pick("license") };
-    } catch {
-      // Try the next candidate.
-    }
-  }
-  return {};
-}
-
-// --- credentials ----------------------------------------------------------
-
-const CREDENTIALS_PATH = join(homedir(), ".shadertown", "credentials.json");
-
-async function readToken() {
-  // An explicit environment variable wins, so CI needs no interactive login.
-  if (process.env.SHADERTOWN_TOKEN) return process.env.SHADERTOWN_TOKEN;
-  try {
-    const raw = await readFile(CREDENTIALS_PATH, "utf8");
-    return JSON.parse(raw).token ?? undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-async function writeToken(token, licensee, registry) {
-  await mkdir(dirname(CREDENTIALS_PATH), { recursive: true });
-  await writeFile(CREDENTIALS_PATH, JSON.stringify({ token, licensee, registry }, null, 2));
-  // The token is a bearer credential; keep it off other accounts on the box.
-  await chmod(CREDENTIALS_PATH, 0o600);
-}
-
 function openBrowser(url) {
   const command =
     process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
@@ -198,15 +164,6 @@ async function fetchJson(url, key) {
   return response.json();
 }
 
-async function exists(path) {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function add(args) {
   const { flags, positional } = parseFlags(args);
   if (positional.length === 0) {
@@ -302,10 +259,6 @@ export default defineShadertownConfig({
   console.log(`\n  ${c.green("add")}   shadertown.config.ts\n`);
 }
 
-function relative(from, to) {
-  return to.startsWith(from) ? to.slice(from.length + 1) : to;
-}
-
 function help() {
   console.log(`
   ${c.bold("shadertown")} - vendor WebGPU shaders into your codebase
@@ -320,6 +273,7 @@ function help() {
     add <slug...>    Write a shader's WGSL and typed preset into your repo
     list             Print the catalogue
     init             Create shadertown.config.ts
+    mcp              Serve the catalogue to a coding agent over MCP (stdio)
 
   ${c.dim("Options")}
     --out <dir>      Output directory            ${c.dim(`(default: ${DEFAULT_OUT})`)}

package/cli/mcp.mjs

@@ -0,0 +1,438 @@
+import { createInterface } from "node:readline";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { shaderNames, shaderRegistry, isShaderName, shaderKind } from "../dist/registry.js";
+import { encodeParams } from "../dist/params.js";
+import {
+  DEFAULT_OUT,
+  DEFAULT_REGISTRY,
+  decodeTokenPayload,
+  exists,
+  readCredentials,
+  readProjectConfig,
+  readToken,
+  relative,
+} from "./shared.mjs";
+
+/**
+ * The MCP server: `npx shadertown mcp`, speaking JSON-RPC over stdio.
+ *
+ * It is a different door into the same building. Discovery and the control
+ * schemas are answered from the registry module this package already ships,
+ * so they need no network; installing goes through the same `/r/<slug>.json`
+ * route as `shadertown add`, so the paywall and the licence issuance cannot
+ * be different for an agent than for a person.
+ *
+ * Hand-rolled rather than pulling in an SDK: the protocol surface this server
+ * needs is four methods, and the CLI's one promise is that it stays
+ * dependency-free.
+ */
+
+const PROTOCOL_VERSIONS = new Set(["2024-11-05", "2025-03-26", "2025-06-18"]);
+const LATEST_PROTOCOL = "2025-06-18";
+
+// stdout is the protocol channel, so anything human goes to stderr.
+const send = (message) => process.stdout.write(`${JSON.stringify(message)}\n`);
+
+export async function serve() {
+  const rl = createInterface({ input: process.stdin, terminal: false });
+
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } });
+      return;
+    }
+    for (const single of Array.isArray(message) ? message : [message]) {
+      void handle(single);
+    }
+  });
+
+  // Serve until the client hangs up.
+  await new Promise((done) => rl.on("close", done));
+}
+
+async function handle(message) {
+  const { id, method, params } = message ?? {};
+
+  // Notifications get no reply, whatever they say.
+  if (id === undefined || id === null) return;
+
+  try {
+    switch (method) {
+      case "initialize": {
+        const requested = params?.protocolVersion;
+        return send({
+          jsonrpc: "2.0",
+          id,
+          result: {
+            protocolVersion: PROTOCOL_VERSIONS.has(requested) ? requested : LATEST_PROTOCOL,
+            capabilities: { tools: {} },
+            serverInfo: { name: "shadertown", version: await packageVersion() },
+            instructions: [
+              `shadertown is a catalogue of ${shaderNames.length} production WebGPU shaders: animated backgrounds and image effects with typed parameters.`,
+              "The flow: `search_shaders` to find candidates, `get_shader` for a shader's controls and usage, `install_shader` to vendor its source into this project.",
+              "Free-tier shaders install for anyone. Professional source needs the account this machine signed in with (`npx shadertown login`) to hold a paid plan.",
+            ].join(" "),
+          },
+        });
+      }
+      case "ping":
+        return send({ jsonrpc: "2.0", id, result: {} });
+      case "tools/list":
+        return send({ jsonrpc: "2.0", id, result: { tools: TOOLS } });
+      case "tools/call":
+        return send({ jsonrpc: "2.0", id, result: await callTool(params?.name, params?.arguments ?? {}) });
+      default:
+        return send({
+          jsonrpc: "2.0",
+          id,
+          error: { code: -32601, message: `Method not found: ${method}` },
+        });
+    }
+  } catch (error) {
+    // A tool that throws is a failed call, not a broken server.
+    send({
+      jsonrpc: "2.0",
+      id,
+      error: { code: -32603, message: error instanceof Error ? error.message : String(error) },
+    });
+  }
+}
+
+async function packageVersion() {
+  const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  return pkg.version;
+}
+
+// --- tools -----------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: "search_shaders",
+    description:
+      "Search the shadertown catalogue of WebGPU shaders (animated backgrounds and image effects). Matches name, tagline, description, family, and tags. Call with no query to list the whole catalogue. Returns slugs for use with get_shader and install_shader.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          description:
+            "Free-text filter, e.g. \"gradient\", \"pointer\", \"dark hero\". Omit to list everything.",
+        },
+      },
+    },
+  },
+  {
+    name: "get_shader",
+    description:
+      "Everything about one shader: what it looks like, every tunable control with its range, default and meaning, the colours it takes, framework usage, and a browser URL where a human can tune it live. Call this before installing or customizing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "The shader's slug, from search_shaders." },
+      },
+      required: ["slug"],
+    },
+  },
+  {
+    name: "install_shader",
+    description:
+      "Vendor a shader into this project: writes the complete WGSL, a typed preset pinned to the params you pass, a ready-to-paste example, a README, and the LICENSE. Free-tier shaders install for anyone; Professional ones need the signed-in account to hold a paid plan (the call explains how when it applies).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", description: "The shader's slug, from search_shaders." },
+        params: {
+          type: "object",
+          description:
+            "Tuned values to pin into the preset, keyed by control name from get_shader. Numbers for controls, hex strings for colorA/colorB/colorC. Omitted controls keep their defaults.",
+          additionalProperties: true,
+        },
+        directory: {
+          type: "string",
+          description: `Where to write, relative to the project root. Defaults to the shadertown.config outDir, or "${DEFAULT_OUT}".`,
+        },
+        force: {
+          type: "boolean",
+          description: "Overwrite files that already exist. Off by default.",
+        },
+      },
+      required: ["slug"],
+    },
+  },
+  {
+    name: "account_status",
+    description:
+      "Who this machine is signed in to shadertown as, on which plan, and what that unlocks. Use it to explain a licence error or to check before installing a Professional shader.",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+async function callTool(name, args) {
+  switch (name) {
+    case "search_shaders":
+      return searchShaders(args);
+    case "get_shader":
+      return getShader(args);
+    case "install_shader":
+      return installShader(args);
+    case "account_status":
+      return accountStatus();
+    default:
+      return failure(`No tool named "${name}".`);
+  }
+}
+
+const success = (text) => ({ content: [{ type: "text", text }] });
+const failure = (text) => ({ content: [{ type: "text", text }], isError: true });
+
+async function registryBase() {
+  const config = await readProjectConfig(process.cwd());
+  return config.registry ?? DEFAULT_REGISTRY;
+}
+
+/**
+ * Which shaders are free is a pricing decision, and pricing lives on the
+ * site, not in this package. Asked once per process; when the network is
+ * away, tiers are reported as unknown rather than guessed.
+ */
+let tierPromise;
+function tierMap(registry) {
+  tierPromise ??= (async () => {
+    try {
+      const response = await fetch(new URL("/r/", registry));
+      if (!response.ok) return null;
+      const index = await response.json();
+      return new Map(index.items.map((item) => [item.slug, item.tier]));
+    } catch {
+      return null;
+    }
+  })();
+  return tierPromise;
+}
+
+async function searchShaders({ query }) {
+  const registry = await registryBase();
+  const tiers = await tierMap(registry);
+
+  const needle = (query ?? "").trim().toLowerCase();
+  const matches = shaderNames.filter((name) => {
+    if (!needle) return true;
+    const def = shaderRegistry[name];
+    const haystack = [name, def.name, def.tagline, def.description, def.family, ...def.tags]
+      .join(" ")
+      .toLowerCase();
+    return needle.split(/\s+/).every((word) => haystack.includes(word));
+  });
+
+  if (matches.length === 0) {
+    return success(
+      `No shader matches "${query}". Families to try: ${[...new Set(shaderNames.map((n) => shaderRegistry[n].family))].join(", ")}. Call search_shaders without a query for the full catalogue.`,
+    );
+  }
+
+  const lines = matches.map((name) => {
+    const def = shaderRegistry[name];
+    const tier = tiers?.get(name);
+    const badge = tier === "free" ? " [free]" : tier === "professional" ? " [pro]" : "";
+    return `- ${name}${badge} — ${def.name}: ${def.tagline} (${def.family}, ${def.cost} cost; tags: ${def.tags.join(", ")})`;
+  });
+
+  const footer = tiers
+    ? "\n[free] installs for anyone; [pro] source needs a paid plan (browsing and tuning are always free)."
+    : "\nTiers unavailable offline: some of these need a paid plan for their source.";
+
+  return success(
+    `${matches.length} of ${shaderNames.length} shaders${needle ? ` match "${query}"` : ""}:\n${lines.join("\n")}\n${footer}\nNext: get_shader for controls, install_shader to vendor one.`,
+  );
+}
+
+async function getShader({ slug }) {
+  if (!isShaderName(slug)) {
+    return failure(`No shader named "${slug}". Use search_shaders to find the right slug.`);
+  }
+
+  const registry = await registryBase();
+  const def = shaderRegistry[slug];
+  const kind = shaderKind(slug);
+  const tiers = await tierMap(registry);
+  const tier = tiers?.get(slug);
+
+  const controls = Object.entries(def.controls).map(
+    ([key, control]) =>
+      `- ${key} ("${control.label}"): number, ${control.min} to ${control.max}, default ${control.default}.${control.hint ? ` ${control.hint}` : ""}`,
+  );
+  const colors = Object.entries(def.colors).map(
+    ([key, color]) =>
+      `- ${key} ("${color.label}"): hex color, default "${color.default}".${color.hint ? ` ${color.hint}` : ""}`,
+  );
+
+  const kindNote =
+    kind === "source"
+      ? "Kind: source — it renders on top of an image or layer you give it."
+      : kind === "compute"
+        ? "Kind: compute — a GPU simulation that carries state between frames."
+        : "Kind: generative — it draws its picture from the params alone.";
+
+  const tierNote =
+    tier === "professional"
+      ? "Tier: Professional — install_shader needs the signed-in account to hold a paid plan."
+      : tier === "free"
+        ? "Tier: Free — install_shader works without an account."
+        : "Tier: unknown (catalogue index unreachable).";
+
+  return success(
+    [
+      `# ${def.name} (${slug})`,
+      def.tagline,
+      "",
+      def.description,
+      "",
+      `Family: ${def.family}. Cost per frame: ${def.cost}. Tags: ${def.tags.join(", ")}.`,
+      kindNote,
+      tierNote,
+      "",
+      "## Controls (keys for the `params` argument and the runtime)",
+      ...controls,
+      ...colors,
+      "",
+      "## Using it",
+      `Tune it live in a browser: ${registry}/shaders/${slug} — the sliders write the same params, and the URL carries them.`,
+      `Install into this project: install_shader with slug "${slug}" and any tuned params.`,
+      `React (runtime from npm): <ShaderCanvas shader="${slug}" params={{ ... }} /> from "shadertown/react".`,
+      `Anything else: createShaderRenderer(canvas, { shader: "${slug}", params }) from "shadertown".`,
+    ].join("\n"),
+  );
+}
+
+async function installShader({ slug, params, directory, force }) {
+  if (!isShaderName(slug)) {
+    return failure(`No shader named "${slug}". Use search_shaders to find the right slug.`);
+  }
+
+  const def = shaderRegistry[slug];
+  const valid = new Set([...Object.keys(def.controls), ...Object.keys(def.colors)]);
+  const cleaned = {};
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (!valid.has(key)) {
+      return failure(
+        `"${key}" is not a control on ${slug}. Valid keys: ${[...valid].join(", ")}. Call get_shader for ranges and meanings.`,
+      );
+    }
+    const coerced = key.startsWith("color") ? String(value) : Number(value);
+    if (typeof coerced === "number" && !Number.isFinite(coerced)) {
+      return failure(`"${key}" must be a number; got ${JSON.stringify(value)}. Call get_shader for its range.`);
+    }
+    cleaned[key] = coerced;
+  }
+
+  const cwd = process.cwd();
+  const config = await readProjectConfig(cwd);
+  const registry = config.registry ?? DEFAULT_REGISTRY;
+  const outDir = resolve(cwd, directory ?? config.outDir ?? DEFAULT_OUT);
+  const token = await readToken();
+
+  const url = new URL(`/r/${slug}.json`, registry);
+  for (const [key, value] of new URLSearchParams(encodeParams(slug, cleaned))) {
+    url.searchParams.set(key, value);
+  }
+
+  const response = await fetch(url, {
+    headers: token ? { authorization: `Bearer ${token}` } : undefined,
+  });
+
+  if (response.status === 402) {
+    const body = await response.json().catch(() => ({}));
+    return failure(
+      [
+        body.message ?? `"${def.name}" is a Professional shader.`,
+        body.reason,
+        token
+          ? "This machine is signed in, but the account holds no paid plan (or the token predates one — sign in again after upgrading)."
+          : "This machine is not signed in.",
+        "To unlock it: run `npx shadertown login` in a terminal on this machine, with an account that holds a Silver or Gold plan — then call install_shader again.",
+        body.upgrade ? `Plans: ${body.upgrade}` : undefined,
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    );
+  }
+
+  if (!response.ok) {
+    const body = await response.json().catch(() => ({}));
+    return failure(body.message ?? `${url} responded ${response.status}.`);
+  }
+
+  const item = await response.json();
+  await mkdir(outDir, { recursive: true });
+
+  const written = [];
+  const skipped = [];
+  for (const file of item.files) {
+    const target = join(outDir, file.path);
+    if ((await exists(target)) && !force) {
+      skipped.push(relative(cwd, target));
+      continue;
+    }
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, file.content);
+    written.push(relative(cwd, target));
+  }
+
+  const tuned = encodeParams(slug, cleaned);
+  return success(
+    [
+      `Installed ${item.name} (${slug}).`,
+      written.length ? `Written:\n${written.map((f) => `- ${f}`).join("\n")}` : "Nothing written.",
+      skipped.length
+        ? `Skipped (already exist — pass force: true to overwrite):\n${skipped.map((f) => `- ${f}`).join("\n")}`
+        : undefined,
+      `Next: import the preset from ${slug}/${slug}.ts and pass it to <ShaderCanvas preset={...} /> (React) or createShaderRenderer. ${slug}/README.md documents every control; ${slug}/example.tsx is ready to paste.`,
+      `Preview in a browser: ${registry}/shaders/${slug}${tuned ? `?${tuned}` : ""}`,
+    ]
+      .filter(Boolean)
+      .join("\n\n"),
+  );
+}
+
+async function accountStatus() {
+  const credentials = await readCredentials();
+  if (!credentials) {
+    return success(
+      [
+        "Not signed in. Free-tier shaders still install; Professional source answers 402.",
+        "To sign in: run `npx shadertown login` in a terminal on this machine (it opens a browser). A Silver or Gold plan on that account unlocks Professional source.",
+        "Plans: https://www.shadertown.com/pricing",
+      ].join("\n"),
+    );
+  }
+
+  const payload = decodeTokenPayload(credentials.token);
+  const lines = [
+    credentials.viaEnv
+      ? "Signed in via the SHADERTOWN_TOKEN environment variable."
+      : `Signed in as ${credentials.licensee ?? payload?.licensee ?? "an account"} (registry: ${credentials.registry ?? DEFAULT_REGISTRY}).`,
+  ];
+
+  if (payload) {
+    lines.push(
+      payload.plan === "professional"
+        ? "Plan: paid — Professional shaders install from this machine."
+        : "Plan: free — Professional source will answer 402. Upgrading? Run `npx shadertown login` again afterwards; the plan is carried in the token.",
+    );
+    if (payload.exp) {
+      lines.push(
+        payload.exp < Date.now()
+          ? "The token has expired. Run `npx shadertown login` again."
+          : `Token valid until ${new Date(payload.exp).toISOString().slice(0, 10)}.`,
+      );
+    }
+  }
+
+  lines.push("This reads the stored token; the registry has the final say on every install.");
+  return success(lines.join("\n"));
+}