makeables 0.4.1 → 0.5.0

package/dist/mcp-LKLESPJC.js

@@ -0,0 +1,398 @@
+import {
+  InputError,
+  applyDesignEdits,
+  badgeDesignObjectSchema,
+  badgeDesignSchema,
+  cardStyles,
+  designCatalog,
+  designEditsSchema,
+  draftFromPackage,
+  getSkill,
+  localSubmissionDraft,
+  packageJson,
+  readPackageJson,
+  renderSubmission,
+  stickerStyles,
+  version,
+  writeAtomic
+} from "./chunk-WVXA65H6.js";
+
+// src/mcp.ts
+import { readFile as readFile2 } from "fs/promises";
+import {
+  getUiCapability,
+  RESOURCE_MIME_TYPE,
+  registerAppResource,
+  registerAppTool
+} from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+
+// src/mcp-documents.ts
+import { createHash } from "crypto";
+import { constants } from "fs";
+import { lstat, open, readFile, realpath } from "fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "path";
+import lockfile from "proper-lockfile";
+var maxBytes = 32e6;
+var hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+var McpDocuments = class _McpDocuments {
+  constructor(root) {
+    this.root = root;
+  }
+  root;
+  queue = Promise.resolve();
+  static async open(root) {
+    const directory = await realpath(resolve(root));
+    if (!(await lstat(directory)).isDirectory())
+      throw new InputError("--root must be a directory.");
+    return new _McpDocuments(directory);
+  }
+  inside(path) {
+    const child = relative(this.root, path);
+    if (child === ".." || child.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) || isAbsolute(child))
+      throw new InputError("Choose a file inside the configured Makeables root.");
+    return path;
+  }
+  async path(file2, create = false) {
+    const path = this.inside(resolve(this.root, file2));
+    if (extname(path).toLowerCase() !== ".json")
+      throw new InputError("Use a design .json or portable .makeables.json file.");
+    const parent = this.inside(await realpath(dirname(path)));
+    const target = join(parent, relative(dirname(path), path));
+    try {
+      if ((await lstat(target)).isSymbolicLink())
+        throw new InputError("Design files must not be symbolic links.");
+      this.inside(await realpath(target));
+    } catch (error) {
+      if (!create || error.code !== "ENOENT") throw error;
+    }
+    return target;
+  }
+  async read(file2) {
+    const path = await this.path(file2);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let bytes;
+    try {
+      const info = await handle.stat();
+      if (!info.isFile() || info.size > maxBytes)
+        throw new InputError("Choose a regular JSON file below 32 MB.");
+      bytes = await handle.readFile();
+    } finally {
+      await handle.close();
+    }
+    const value = JSON.parse(bytes.toString("utf8"));
+    if (value && typeof value === "object" && "format" in value && value.format === "makeables-bundle")
+      throw new InputError(
+        "Export this legacy badge bundle as a portable .makeables.json package before editing it here."
+      );
+    const portable = Boolean(
+      value && typeof value === "object" && "format" in value && value.format === "makeables-package"
+    );
+    const pkg = portable ? await readPackageJson(value) : void 0;
+    const draft = pkg ? draftFromPackage(pkg) : await localSubmissionDraft(value);
+    if (draft.design.product !== "sticker" && draft.design.front.layers.some((layer) => layer.kind === "portrait") && (!draft.participant?.name || !draft.portrait))
+      throw new InputError(
+        "Include the user's name and portrait in a portable badge package. No example person is used."
+      );
+    return {
+      file: relative(this.root, path),
+      path,
+      revision: hash(bytes),
+      draft,
+      ...pkg ? { package: pkg } : {},
+      wrapped: Boolean(value && typeof value === "object" && "design" in value)
+    };
+  }
+  async preview(document, side2 = "front") {
+    if (side2 === "back" && document.draft.design.product === "sticker")
+      throw new InputError("A sticker has one editable front.");
+    const pkg = document.package ?? await renderSubmission(document.draft);
+    const path = side2 === "front" ? pkg.manifest.front : pkg.manifest.back;
+    if (!path) throw new InputError("This design has no back preview.");
+    return { png: Buffer.from(pkg.files[path]), package: pkg };
+  }
+  /** Serialize cooperating writes and compare revisions while holding the file lock. */
+  async edit(file2, expected, change, side2 = "front") {
+    const operation = this.queue.catch(() => {
+    }).then(async () => {
+      const path = await this.path(file2);
+      const release = await lockfile.lock(path, { realpath: false, retries: 0 });
+      try {
+        const current = await this.read(file2);
+        if (current.revision !== expected)
+          throw new InputError(
+            "STALE_REVISION: Inspect the file again before applying this edit."
+          );
+        if (side2 === "back" && current.draft.design.product === "sticker")
+          throw new InputError("A sticker has one editable front.");
+        const next = change.design ? badgeDesignSchema.parse(change.design) : applyDesignEdits(current.draft.design, change.edits);
+        if ((next.product ?? "badge") !== (current.draft.design.product ?? "badge"))
+          throw new InputError("Create a new file to change the product.");
+        const draft = { ...current.draft, design: next };
+        const pkg = await renderSubmission(draft);
+        const body = `${JSON.stringify(
+          current.package ? packageJson(pkg) : current.wrapped ? {
+            design: next,
+            ...draft.participant ? { participant: draft.participant } : {}
+          } : next,
+          null,
+          2
+        )}
+`;
+        if (hash(await readFile(path)) !== expected)
+          throw new InputError("STALE_REVISION: The file changed while preparing this edit.");
+        await writeAtomic(path, body);
+        return { ...current, revision: hash(body), draft, package: pkg };
+      } finally {
+        await release();
+      }
+    });
+    this.queue = operation;
+    return operation;
+  }
+  async create(file2, product, style, design) {
+    const path = await this.path(file2, true);
+    const catalog = product === "card" ? cardStyles : product === "sticker" ? stickerStyles : designCatalog;
+    const preset = catalog.find((entry) => entry.source === style);
+    if (!design && !preset) throw new InputError("Unknown style. Inspect the catalog first.");
+    const doc = badgeDesignSchema.parse(design ?? (preset ? structuredClone(preset) : void 0));
+    if ((doc.product ?? "badge") !== product)
+      throw new InputError("The selected design must match the requested product.");
+    const draft = await localSubmissionDraft(doc);
+    const pkg = await renderSubmission(draft);
+    await writeAtomic(path, `${JSON.stringify(doc, null, 2)}
+`, true);
+    const result = await this.read(file2);
+    return { ...result, package: pkg };
+  }
+};
+
+// src/mcp.ts
+var makeablesAppUri = "ui://makeables/studio-v1.html";
+var file = z.string().min(1).max(4096).describe("Design JSON path inside the configured root.");
+var side = z.enum(["front", "back"]).default("front");
+var revision = z.string().regex(/^[a-f0-9]{64}$/).describe("Revision from the latest preview or inspection.");
+var ui = { resourceUri: makeablesAppUri, visibility: ["model", "app"] };
+var readOnly = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+var write = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+async function createMakeablesMcp(root, html) {
+  const documents = await McpDocuments.open(root);
+  const server = new McpServer(
+    { name: "makeables", version },
+    {
+      capabilities: { tools: {}, resources: {} },
+      instructions: "Create and edit local Makeables documents. Load the core guide with makeables_inspect(section: guide, guide: core), then the relevant product guide. Prefer the embedded app when available. Inspect before editing and use the returned revision. These tools never publish or open a browser. If UI is unavailable, show the PNG result; use the CLI or an available built-in browser for further work."
+    }
+  );
+  const supportsUi = () => Boolean(
+    getUiCapability(server.server.getClientCapabilities())?.mimeTypes?.includes(
+      RESOURCE_MIME_TYPE
+    )
+  );
+  async function result(document, face) {
+    const preview = await documents.preview(document, face);
+    const design = document.draft.design;
+    const data = {
+      file: document.file,
+      revision: document.revision,
+      name: design.name,
+      product: design.product ?? "badge",
+      side: face,
+      preview: design.product === "sticker" ? "material" : "flat artwork",
+      layers: { front: design.front.layers.length, back: design.back.layers.length },
+      surface: supportsUi() ? "mcp-app" : "image"
+    };
+    const png = preview.png.toString("base64");
+    return {
+      content: [
+        { type: "text", text: JSON.stringify(data) },
+        ...!supportsUi() ? [{ type: "image", mimeType: "image/png", data: png }] : []
+      ],
+      structuredContent: data,
+      _meta: { makeables: { ...data, design, png } }
+    };
+  }
+  async function guarded(action) {
+    try {
+      return await action();
+    } catch (error) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: error instanceof Error ? error.message : "The operation failed. Inspect before retrying."
+          }
+        ]
+      };
+    }
+  }
+  server.registerTool(
+    "makeables_inspect",
+    {
+      description: "Inspect a local design and its revision, or load the bundled guides, catalog and shared document/patch schema.",
+      inputSchema: {
+        section: z.enum(["document", "catalog", "schema", "guide"]).default("document"),
+        guide: z.enum(["core", "cards", "badges", "stickers", "design", "images", "wallet"]).optional(),
+        file: file.optional()
+      },
+      annotations: readOnly
+    },
+    ({ section, file: path, guide }) => guarded(async () => {
+      let data;
+      if (section === "guide") {
+        const name = guide ?? "core";
+        const content = getSkill(name);
+        return {
+          content: [{ type: "text", text: content }],
+          structuredContent: { name, content }
+        };
+      }
+      if (section === "catalog")
+        data = {
+          styles: [...cardStyles, ...stickerStyles, ...designCatalog].map(
+            ({ source, name, product }) => ({ id: source, name, product: product ?? "badge" })
+          )
+        };
+      else if (section === "schema")
+        data = {
+          design: zodToJsonSchema(badgeDesignObjectSchema),
+          edits: zodToJsonSchema(designEditsSchema)
+        };
+      else {
+        if (!path) throw new Error("Supply file for document inspection.");
+        const current = await documents.read(path);
+        data = { file: current.file, revision: current.revision, design: current.draft.design };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(data) }], structuredContent: data };
+    })
+  );
+  registerAppTool(
+    server,
+    "makeables_preview",
+    {
+      description: "Show a local design in the embedded Makeables widget, or return a PNG when the host has no MCP Apps support. Opens no browser.",
+      inputSchema: { file, side },
+      annotations: readOnly,
+      _meta: { ui }
+    },
+    ({ file: file2, side: side2 }) => guarded(async () => result(await documents.read(file2), side2))
+  );
+  registerAppTool(
+    server,
+    "makeables_create",
+    {
+      description: "Create a new editable card or sticker file from a catalog style or supplied design. Existing files are never replaced. For a personalized badge, open a complete portable package containing the user's portrait and name.",
+      inputSchema: {
+        file,
+        product: z.enum(["card", "sticker"]),
+        style: z.string().default(""),
+        design: badgeDesignObjectSchema.optional()
+      },
+      annotations: write,
+      _meta: { ui }
+    },
+    ({ file: file2, product, style, design }) => guarded(async () => result(await documents.create(file2, product, style, design), "front"))
+  );
+  registerAppTool(
+    server,
+    "makeables_edit",
+    {
+      description: "Apply the same material/layer patch as the website to a local design. The expectedRevision must match the latest inspection. Upserts are complete layers. Returns the updated widget or PNG.",
+      inputSchema: { file, expectedRevision: revision, edits: designEditsSchema, side },
+      annotations: write,
+      _meta: { ui }
+    },
+    ({ file: file2, expectedRevision, edits, side: side2 }) => guarded(
+      async () => result(await documents.edit(file2, expectedRevision, { edits }, side2), side2)
+    )
+  );
+  registerAppTool(
+    server,
+    "makeables_replace",
+    {
+      description: "Replace a local design's full editable document with a validated document, preserving portable image assets. Requires the latest revision and the same product.",
+      inputSchema: { file, expectedRevision: revision, design: badgeDesignObjectSchema, side },
+      annotations: write,
+      _meta: { ui }
+    },
+    ({ file: file2, expectedRevision, design, side: side2 }) => guarded(
+      async () => result(await documents.edit(file2, expectedRevision, { design }, side2), side2)
+    )
+  );
+  server.registerTool(
+    "makeables_export",
+    {
+      description: "Prepare the current PNG, editable JSON or complete portable package for download. The widget can use the host's download capability; the CLI can also export the same document. Does not publish.",
+      inputSchema: {
+        file,
+        expectedRevision: revision,
+        format: z.enum(["png", "json", "package"]),
+        side
+      },
+      annotations: readOnly,
+      _meta: { ui: { visibility: ["app", "model"] } }
+    },
+    ({ file: file2, expectedRevision, format, side: side2 }) => guarded(async () => {
+      const current = await documents.read(file2);
+      if (current.revision !== expectedRevision)
+        throw new Error("STALE_REVISION: Refresh the preview before exporting.");
+      const preview = await documents.preview(current, side2);
+      const bytes = format === "png" ? preview.png : Buffer.from(
+        JSON.stringify(
+          format === "package" ? packageJson(preview.package) : current.draft.design,
+          null,
+          2
+        )
+      );
+      const stem = current.file.split(/[\\/]/).pop()?.replace(/(?:\.makeables)?\.json$/i, "") ?? "design";
+      const name = `${stem}${format === "png" ? `-${side2}.png` : format === "package" ? ".makeables.json" : ".json"}`;
+      const data = {
+        name,
+        mimeType: format === "png" ? "image/png" : "application/json",
+        bytes: bytes.length
+      };
+      return {
+        content: [{ type: "text", text: JSON.stringify(data) }],
+        structuredContent: data,
+        _meta: { download: { ...data, blob: bytes.toString("base64") } }
+      };
+    })
+  );
+  registerAppResource(
+    server,
+    "Makeables Studio",
+    makeablesAppUri,
+    {
+      _meta: { ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } } }
+    },
+    async () => ({
+      contents: [
+        {
+          uri: makeablesAppUri,
+          mimeType: RESOURCE_MIME_TYPE,
+          text: html ?? await readFile2(new URL("./mcp-app.html", import.meta.url), "utf8"),
+          _meta: { ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] } } }
+        }
+      ]
+    })
+  );
+  return server;
+}
+async function runMcp(root) {
+  const server = await createMakeablesMcp(root);
+  await server.connect(new StdioServerTransport());
+  const stop = () => {
+    void server.close();
+  };
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+}
+export {
+  createMakeablesMcp,
+  makeablesAppUri,
+  runMcp
+};