@genart-dev/mcp-server 0.1.1 → 0.2.0

package/dist/index.js

@@ -551,6 +551,7 @@ import { writeFile as writeFile3, stat as stat2, unlink } from "fs/promises";
 import { basename as basename2, dirname as dirname3, resolve as resolve2 } from "path";
 import {
   createDefaultRegistry,
+  resolveComponents,
   resolvePreset,
   serializeGenart as serializeGenart2,
   serializeWorkspace as serializeWorkspace3
@@ -647,10 +648,40 @@ async function createSketch(state, input) {
     const adapter = registry4.resolve(rendererType);
     algorithm = adapter.getAlgorithmTemplate();
   }
+  let resolvedComponents;
+  if (input.components && Object.keys(input.components).length > 0) {
+    const shorthand = {};
+    for (const [name, value] of Object.entries(input.components)) {
+      if (typeof value === "string") {
+        shorthand[name] = value;
+      } else if (value.version) {
+        shorthand[name] = value.version;
+      } else if (value.code) {
+        if (!resolvedComponents) resolvedComponents = {};
+        resolvedComponents[name] = {
+          ...value.version ? { version: value.version } : {},
+          code: value.code,
+          ...value.exports ? { exports: value.exports } : {}
+        };
+      }
+    }
+    if (Object.keys(shorthand).length > 0) {
+      const resolved = resolveComponents(shorthand, rendererType);
+      if (!resolvedComponents) resolvedComponents = {};
+      for (const rc of resolved) {
+        resolvedComponents[rc.name] = {
+          version: rc.version,
+          code: rc.code,
+          exports: [...rc.exports]
+        };
+      }
+    }
+  }
   const seed = input.seed ?? Math.floor(Math.random() * 1e5);
   const ts = now2();
+  const hasComponents = resolvedComponents && Object.keys(resolvedComponents).length > 0;
   const sketch = {
-    genart: "1.1",
+    genart: hasComponents ? "1.2" : "1.1",
     id: input.id,
     title: input.title,
     created: ts,
@@ -664,6 +695,7 @@ async function createSketch(state, input) {
     ...input.philosophy ? { philosophy: input.philosophy } : {},
     ...input.themes && input.themes.length > 0 ? { themes: input.themes } : {},
     ...input.skills && input.skills.length > 0 ? { skills: input.skills } : {},
+    ...hasComponents ? { components: resolvedComponents } : {},
     ...input.agent ? { agent: input.agent } : {},
     ...input.model ? { model: input.model } : {}
   };
@@ -847,10 +879,44 @@ async function updateAlgorithm(state, input) {
       );
     }
   }
+  let resolvedComponents;
+  if (input.components && Object.keys(input.components).length > 0) {
+    const renderer = def.renderer.type;
+    const shorthand = {};
+    for (const [name, value] of Object.entries(input.components)) {
+      if (typeof value === "string") {
+        shorthand[name] = value;
+      } else if (value.version) {
+        shorthand[name] = value.version;
+      } else if (value.code) {
+        if (!resolvedComponents) resolvedComponents = {};
+        resolvedComponents[name] = {
+          ...value.version ? { version: value.version } : {},
+          code: value.code,
+          ...value.exports ? { exports: value.exports } : {}
+        };
+      }
+    }
+    if (Object.keys(shorthand).length > 0) {
+      const resolved = resolveComponents(shorthand, renderer);
+      if (!resolvedComponents) resolvedComponents = {};
+      for (const rc of resolved) {
+        resolvedComponents[rc.name] = {
+          version: rc.version,
+          code: rc.code,
+          exports: [...rc.exports]
+        };
+      }
+    }
+  }
+  const updated = ["algorithm"];
+  const hasNewComponents = resolvedComponents && Object.keys(resolvedComponents).length > 0;
+  if (hasNewComponents) updated.push("components");
   const newDef = {
     ...def,
     modified: now2(),
     algorithm: input.algorithm,
+    ...hasNewComponents ? { genart: "1.2", components: resolvedComponents } : {},
     ...input.agent ? { agent: input.agent } : {},
     ...input.model ? { model: input.model } : {}
   };
@@ -864,7 +930,7 @@ async function updateAlgorithm(state, input) {
   }
   state.emitMutation("sketch:updated", {
     id: input.sketchId,
-    updated: ["algorithm"]
+    updated
   });
   return {
     success: true,
@@ -872,6 +938,7 @@ async function updateAlgorithm(state, input) {
     renderer: def.renderer.type,
     algorithmLength: input.algorithm.length,
     validationPassed,
+    ...hasNewComponents ? { componentsUpdated: true } : {},
     fileContent: json
   };
 }
@@ -2173,8 +2240,219 @@ ${guidelines}`,
   };
 }
 
-// src/tools/capture.ts
+// src/tools/components.ts
 import { writeFile as writeFile5 } from "fs/promises";
+import {
+  COMPONENT_REGISTRY,
+  resolveComponents as resolveComponents2,
+  serializeGenart as serializeGenart4
+} from "@genart-dev/core";
+var VALID_RENDERERS2 = [
+  "p5",
+  "three",
+  "glsl",
+  "canvas2d",
+  "svg"
+];
+var RENDERER_TARGET = {
+  p5: "js",
+  three: "js",
+  canvas2d: "js",
+  svg: "js",
+  glsl: "glsl"
+};
+async function listComponents(_state, input) {
+  let entries = Object.values(COMPONENT_REGISTRY);
+  if (input.renderer) {
+    const renderer = input.renderer;
+    const target = RENDERER_TARGET[renderer];
+    if (!target) {
+      throw new Error(
+        `Unknown renderer type: '${input.renderer}'. Valid types: ${VALID_RENDERERS2.join(", ")}`
+      );
+    }
+    entries = entries.filter(
+      (e) => e.target === target && (e.renderers.length === 0 || e.renderers.includes(renderer))
+    );
+  }
+  if (input.category) {
+    const cat = input.category;
+    entries = entries.filter((e) => e.category === cat);
+  }
+  entries.sort((a, b) => {
+    const catCmp = a.category.localeCompare(b.category);
+    if (catCmp !== 0) return catCmp;
+    return a.name.localeCompare(b.name);
+  });
+  const components = entries.map((e) => ({
+    name: e.name,
+    version: e.version,
+    category: e.category,
+    target: e.target,
+    exports: [...e.exports],
+    dependencies: [...e.dependencies],
+    description: e.description
+  }));
+  return {
+    count: components.length,
+    components
+  };
+}
+async function addComponent(state, input) {
+  const loaded = state.requireSketch(input.sketchId);
+  const def = loaded.definition;
+  const renderer = def.renderer.type;
+  const entry = COMPONENT_REGISTRY[input.component];
+  if (!entry) {
+    throw new Error(`Unknown component: "${input.component}"`);
+  }
+  const target = RENDERER_TARGET[renderer];
+  if (entry.target !== target) {
+    throw new Error(
+      `Component "${input.component}" has target "${entry.target}" but renderer "${renderer}" requires target "${target}"`
+    );
+  }
+  if (entry.renderers.length > 0 && !entry.renderers.includes(renderer)) {
+    throw new Error(
+      `Component "${input.component}" is not compatible with renderer "${renderer}". Compatible: ${entry.renderers.join(", ")}`
+    );
+  }
+  const existingComponents = {};
+  if (def.components) {
+    for (const [name, value] of Object.entries(def.components)) {
+      if (typeof value === "string") {
+        existingComponents[name] = value;
+      } else if (value.version) {
+        existingComponents[name] = value.version;
+      }
+    }
+  }
+  if (existingComponents[input.component]) {
+    throw new Error(
+      `Component "${input.component}" is already present in sketch "${input.sketchId}"`
+    );
+  }
+  existingComponents[input.component] = input.version ?? "^1.0.0";
+  const resolved = resolveComponents2(existingComponents, renderer);
+  const resolvedRecord = {};
+  for (const rc of resolved) {
+    resolvedRecord[rc.name] = {
+      version: rc.version,
+      code: rc.code,
+      exports: [...rc.exports]
+    };
+  }
+  const previousNames = new Set(
+    def.components ? Object.keys(def.components) : []
+  );
+  const added = resolved.map((rc) => rc.name).filter((name) => !previousNames.has(name));
+  const newDef = {
+    ...def,
+    genart: "1.2",
+    modified: (/* @__PURE__ */ new Date()).toISOString(),
+    components: resolvedRecord
+  };
+  state.sketches.set(input.sketchId, {
+    definition: newDef,
+    path: loaded.path
+  });
+  const json = serializeGenart4(newDef);
+  if (!state.remoteMode) {
+    await writeFile5(loaded.path, json, "utf-8");
+  }
+  state.emitMutation("sketch:updated", {
+    id: input.sketchId,
+    updated: ["components"]
+  });
+  return {
+    success: true,
+    sketchId: input.sketchId,
+    components: resolvedRecord,
+    added,
+    fileContent: json
+  };
+}
+async function removeComponent(state, input) {
+  const loaded = state.requireSketch(input.sketchId);
+  const def = loaded.definition;
+  if (!def.components || !def.components[input.component]) {
+    throw new Error(
+      `Component "${input.component}" is not present in sketch "${input.sketchId}"`
+    );
+  }
+  const remaining = { ...def.components };
+  delete remaining[input.component];
+  for (const [name, value] of Object.entries(remaining)) {
+    const entry = COMPONENT_REGISTRY[name];
+    if (entry && entry.dependencies.includes(input.component)) {
+      throw new Error(
+        `Cannot remove "${input.component}": component "${name}" depends on it`
+      );
+    }
+  }
+  let warning;
+  const removedValue = def.components[input.component];
+  const exports = typeof removedValue === "string" ? COMPONENT_REGISTRY[input.component]?.exports ?? [] : removedValue.exports ?? [];
+  const usedExports = exports.filter((exp) => def.algorithm.includes(exp));
+  if (usedExports.length > 0) {
+    warning = `Algorithm may reference these exports from "${input.component}": ${usedExports.join(", ")}. Review your algorithm after removal.`;
+  }
+  const removed = [input.component];
+  const neededDeps = /* @__PURE__ */ new Set();
+  for (const name of Object.keys(remaining)) {
+    const entry = COMPONENT_REGISTRY[name];
+    if (entry) {
+      collectTransitiveDeps(name, neededDeps);
+    }
+  }
+  for (const name of Object.keys(remaining)) {
+    if (!neededDeps.has(name) && !isDirectComponent(name, remaining)) {
+      delete remaining[name];
+      removed.push(name);
+    }
+  }
+  const hasRemaining = Object.keys(remaining).length > 0;
+  const newDef = {
+    ...def,
+    modified: (/* @__PURE__ */ new Date()).toISOString(),
+    ...hasRemaining ? { components: remaining } : { components: void 0 }
+  };
+  state.sketches.set(input.sketchId, {
+    definition: newDef,
+    path: loaded.path
+  });
+  const json = serializeGenart4(newDef);
+  if (!state.remoteMode) {
+    await writeFile5(loaded.path, json, "utf-8");
+  }
+  state.emitMutation("sketch:updated", {
+    id: input.sketchId,
+    updated: ["components"]
+  });
+  return {
+    success: true,
+    sketchId: input.sketchId,
+    removed,
+    ...warning ? { warning } : {},
+    fileContent: json
+  };
+}
+function collectTransitiveDeps(name, deps) {
+  const entry = COMPONENT_REGISTRY[name];
+  if (!entry) return;
+  deps.add(name);
+  for (const dep of entry.dependencies) {
+    if (!deps.has(dep)) {
+      collectTransitiveDeps(dep, deps);
+    }
+  }
+}
+function isDirectComponent(name, components) {
+  return name in components;
+}
+
+// src/tools/capture.ts
+import { writeFile as writeFile6 } from "fs/promises";
 import {
   createDefaultRegistry as createDefaultRegistry2
 } from "@genart-dev/core";
@@ -2352,7 +2630,7 @@ async function buildScreenshotMetadata(state, multi, info) {
     previewPath: info.previewPath
   };
   if (!state.remoteMode) {
-    await writeFile5(info.previewPath, multi.previewPng);
+    await writeFile6(info.previewPath, multi.previewPng);
     metadata.savedPreviewTo = info.previewPath;
   }
   return metadata;
@@ -2413,12 +2691,12 @@ async function captureBatch(state, input) {
 
 // src/tools/export.ts
 import { createWriteStream } from "fs";
-import { stat as stat4, writeFile as writeFile6 } from "fs/promises";
+import { stat as stat4, writeFile as writeFile7 } from "fs/promises";
 import { dirname as dirname6 } from "path";
 import archiver from "archiver";
 import {
   createDefaultRegistry as createDefaultRegistry3,
-  serializeGenart as serializeGenart4
+  serializeGenart as serializeGenart5
 } from "@genart-dev/core";
 var registry3 = createDefaultRegistry3();
 async function validateOutputPath(outputPath) {
@@ -2488,7 +2766,7 @@ async function exportHtml(sketch, outputPath) {
   const adapter = registry3.resolve(sketch.renderer.type);
   const html = adapter.generateStandaloneHTML(sketch);
   const content = Buffer.from(html, "utf-8");
-  await writeFile6(outputPath, content);
+  await writeFile7(outputPath, content);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2504,7 +2782,7 @@ async function exportPng(sketch, input) {
   const width = input.width ?? sketch.canvas.width;
   const height = input.height ?? sketch.canvas.height;
   const result = await captureHtml({ html, width, height });
-  await writeFile6(input.outputPath, result.bytes);
+  await writeFile7(input.outputPath, result.bytes);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2519,7 +2797,7 @@ async function exportSvg(sketch, input) {
   const height = input.height ?? sketch.canvas.height;
   if (sketch.renderer.type === "svg") {
     const content2 = Buffer.from(sketch.algorithm, "utf-8");
-    await writeFile6(input.outputPath, content2);
+    await writeFile7(input.outputPath, content2);
     return {
       success: true,
       sketchId: sketch.id,
@@ -2541,7 +2819,7 @@ async function exportSvg(sketch, input) {
          href="data:image/png;base64,${b64}"/>
 </svg>`;
   const content = Buffer.from(svg, "utf-8");
-  await writeFile6(input.outputPath, content);
+  await writeFile7(input.outputPath, content);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2554,7 +2832,7 @@ async function exportSvg(sketch, input) {
 }
 async function exportAlgorithm(sketch, outputPath) {
   const content = Buffer.from(sketch.algorithm, "utf-8");
-  await writeFile6(outputPath, content);
+  await writeFile7(outputPath, content);
   return {
     success: true,
     sketchId: sketch.id,
@@ -2569,7 +2847,7 @@ async function exportZip(sketch, input) {
   const width = input.width ?? sketch.canvas.width;
   const height = input.height ?? sketch.canvas.height;
   const html = adapter.generateStandaloneHTML(sketch);
-  const genartJson = serializeGenart4(sketch);
+  const genartJson = serializeGenart5(sketch);
   const algorithm = sketch.algorithm;
   const algExt = algorithmExtension(sketch.renderer.type);
   const captureResult = await captureHtml({ html, width, height });
@@ -3106,6 +3384,7 @@ function createServer(state) {
   );
   registerWorkspaceTools(server, state);
   registerSketchTools(server, state);
+  registerComponentTools(server, state);
   registerSelectionTools(server, state);
   registerParameterTools(server, state);
   registerArrangementTools(server, state);
@@ -3209,7 +3488,7 @@ function registerWorkspaceTools(server, state) {
 function registerSketchTools(server, state) {
   server.tool(
     "create_sketch",
-    "Create a new .genart sketch file from metadata, parameters, and algorithm",
+    'Create a new .genart sketch file from metadata, parameters, and algorithm. IMPORTANT: Do not embed common utilities (PRNG, noise, easing, color math, vector ops) inline in the algorithm. Instead, declare them as components: { "prng": "^1.0.0", "noise-2d": "^1.0.0" }. Then use the exported functions directly in your algorithm (e.g., mulberry32, fbm2D). Use list_components to see all available components for the current renderer.',
     {
       id: z2.string().describe("URL-safe kebab-case identifier"),
       title: z2.string().describe("Human-readable title"),
@@ -3247,6 +3526,16 @@ function registerSketchTools(server, state) {
       algorithm: z2.string().optional().describe("Algorithm source code (default: renderer template). For p5: must be `function sketch(p, state) { ... }` in instance mode. State provides: state.WIDTH, state.HEIGHT, state.SEED (number), state.PARAMS (keyed by param key), state.COLORS (keyed by color key, hex strings). Use p5 instance methods (p.createCanvas, p.background, etc)."),
       seed: z2.number().optional().describe("Initial random seed (default: random)"),
       skills: z2.array(z2.string()).optional().describe("Design skill references"),
+      components: z2.record(
+        z2.union([
+          z2.string(),
+          z2.object({
+            version: z2.string().optional(),
+            code: z2.string().optional(),
+            exports: z2.array(z2.string()).optional()
+          })
+        ])
+      ).optional().describe('Component dependencies. Use list_components to see available. Keys are component names, values are semver ranges (e.g. "^1.0.0") or objects with version/code/exports.'),
       addToWorkspace: z2.string().optional().describe("Path to workspace to add sketch to after creation"),
       agent: z2.string().optional().describe("Your CLI agent name (e.g. 'claude-code', 'codex-cli', 'gemini-cli', 'opencode', 'kiro')"),
       model: z2.string().optional().describe("Your AI model identifier (e.g. 'claude-opus-4-6', 'gpt-4o', 'gemini-2.5-pro')")
@@ -3326,11 +3615,21 @@ function registerSketchTools(server, state) {
   );
   server.tool(
     "update_algorithm",
-    "Replace the algorithm source code of a sketch",
+    "Replace the algorithm source code of a sketch. If adding/changing components, pass them in the components field alongside the algorithm.",
     {
       sketchId: z2.string().describe("ID of the sketch to update"),
       algorithm: z2.string().describe("New algorithm source code. For p5: must be `function sketch(p, state) { ... }` in instance mode. State provides: state.WIDTH, state.HEIGHT, state.SEED, state.PARAMS (keyed by param key), state.COLORS (keyed by color key)."),
       validate: z2.boolean().optional().describe("Run renderer-specific validation before saving (default: true)"),
+      components: z2.record(
+        z2.union([
+          z2.string(),
+          z2.object({
+            version: z2.string().optional(),
+            code: z2.string().optional(),
+            exports: z2.array(z2.string()).optional()
+          })
+        ])
+      ).optional().describe("Component dependencies to resolve alongside the algorithm update. Use list_components to see available."),
       agent: z2.string().optional().describe("Your CLI agent name (e.g. 'claude-code', 'codex-cli', 'gemini-cli', 'opencode', 'kiro')"),
       model: z2.string().optional().describe("Your AI model identifier (e.g. 'claude-opus-4-6', 'gpt-4o', 'gemini-2.5-pro')")
     },
@@ -3426,6 +3725,76 @@ function registerSketchTools(server, state) {
     }
   );
 }
+function registerComponentTools(server, state) {
+  server.tool(
+    "list_components",
+    "List available reusable components from the registry, filtered by renderer and/or category. Components provide common utilities (PRNG, noise, easing, color math, etc.) that can be declared as dependencies instead of inlining code in the algorithm.",
+    {
+      renderer: z2.enum(["p5", "three", "glsl", "canvas2d", "svg"]).optional().describe("Filter by renderer compatibility"),
+      category: z2.enum([
+        "randomness",
+        "noise",
+        "math",
+        "easing",
+        "color",
+        "vector",
+        "geometry",
+        "grid",
+        "particle",
+        "physics",
+        "distribution",
+        "pattern",
+        "sdf",
+        "transform",
+        "animation",
+        "string",
+        "data-structure",
+        "imaging"
+      ]).optional().describe("Filter by component category")
+    },
+    async (args) => {
+      try {
+        const result = await listComponents(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "add_component",
+    "Add a component dependency to an existing sketch. Resolves the component and any transitive dependencies from the registry, validates renderer compatibility, and writes the resolved form to the sketch file.",
+    {
+      sketchId: z2.string().describe("ID of the sketch to add the component to"),
+      component: z2.string().describe("Component name (e.g. 'prng', 'noise-2d', 'glsl-noise')"),
+      version: z2.string().optional().describe("Version range (default: '^1.0.0')")
+    },
+    async (args) => {
+      try {
+        const result = await addComponent(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+  server.tool(
+    "remove_component",
+    "Remove a component dependency from a sketch. Checks for dependent components and warns if the algorithm references the component's exports.",
+    {
+      sketchId: z2.string().describe("ID of the sketch to remove the component from"),
+      component: z2.string().describe("Component name to remove")
+    },
+    async (args) => {
+      try {
+        const result = await removeComponent(state, args);
+        return jsonResult(result);
+      } catch (e) {
+        return toolError(e instanceof Error ? e.message : String(e));
+      }
+    }
+  );
+}
 function registerSelectionTools(server, state) {
   server.tool(
     "get_selection",