image-enhancer-mcp 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# image-enhancer-mcp
+
+stdio [MCP](https://modelcontextprotocol.io/) server that lets a merchant's
+Claude (Desktop or Code) drive **Image Enhancer** — generate Shopify-ready
+apparel photography (ghost mannequin, AI model, detail, lifestyle, flat lay,
+premium, video, banner), iterate results, and give feedback — with strict
+product-identity preservation.
+
+It bridges stdio JSON-RPC to the Image Enhancer app's HTTP `/mcp` endpoint using
+the merchant's linking token.
+
+## Usage
+
+Get your linking token from **Image Enhancer → Settings → Connect with Claude**
+("Rotate token"). Then:
+
+**Claude Desktop** — add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "image-enhancer": {
+      "command": "npx",
+      "args": ["-y", "image-enhancer-mcp"],
+      "env": {
+        "IE_API_URL": "https://your-app.up.railway.app",
+        "IE_MCP_TOKEN": "ie_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add image-enhancer \
+  --env IE_API_URL=https://your-app.up.railway.app \
+  --env IE_MCP_TOKEN=ie_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
+  -- npx -y image-enhancer-mcp
+```
+
+### Environment
+
+| Var | Required | Description |
+|---|---|---|
+| `IE_API_URL` | yes | Base URL of your Image Enhancer app. |
+| `IE_MCP_TOKEN` | yes | Your `ie_<32hex>` linking token. |
+
+## Publishing (maintainers)
+
+This package is build-ready (`tsup` → `dist/index.js`, executable, deps kept
+external). The actual publish is a deliberate, manual step:
+
+```bash
+pnpm --filter image-enhancer-mcp build   # prepack runs this automatically
+npm pack --dry-run                        # verify the tarball (dist + package.json)
+npm publish                               # unscoped public package — needs npm auth only
+```
+
+> Published unscoped as `image-enhancer-mcp` (no npm org required). If you ever
+> rename it, update the `npx` command in the Settings → "Connect with Claude"
+> panel (`apps/app/app/routes/app.settings.tsx`).

package/dist/index.js

@@ -0,0 +1,728 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/config.ts
+var TOKEN_RE = /^ie_[0-9a-f]{32}$/;
+function resolveConfig(env = process.env) {
+  const rawUrl = (env.IE_API_URL ?? "").trim();
+  const token = (env.IE_MCP_TOKEN ?? "").trim();
+  if (!rawUrl) {
+    throw new Error(
+      "IE_API_URL is not set. Add it to your MCP server config \u2014 it is the base URL of your Image Enhancer app (e.g. https://your-app.up.railway.app)."
+    );
+  }
+  let apiUrl;
+  try {
+    const u = new URL(rawUrl);
+    if (u.protocol !== "https:" && u.protocol !== "http:") {
+      throw new Error("protocol");
+    }
+    apiUrl = `${u.origin}${u.pathname.replace(/\/+$/, "").replace(/\/mcp$/, "")}`;
+  } catch {
+    throw new Error(
+      `IE_API_URL is not a valid http(s) URL: "${rawUrl}". Use the base URL of your Image Enhancer app, e.g. https://your-app.up.railway.app`
+    );
+  }
+  if (!token) {
+    throw new Error(
+      'IE_MCP_TOKEN is not set. Copy your linking token (starts with "ie_") from Image Enhancer \u2192 Settings \u2192 Connect with Claude.'
+    );
+  }
+  if (!TOKEN_RE.test(token)) {
+    throw new Error(
+      'IE_MCP_TOKEN is malformed. It must look like "ie_" followed by 32 hex characters. Re-copy it from Image Enhancer \u2192 Settings \u2192 Connect with Claude (use "Rotate token" if it was revoked).'
+    );
+  }
+  return { apiUrl, token };
+}
+
+// src/http-client.ts
+var HttpBridgeClient = class {
+  endpoint;
+  token;
+  nextId = 1;
+  constructor(config) {
+    this.endpoint = `${config.apiUrl}/mcp`;
+    this.token = config.token;
+  }
+  async callTool(name, args) {
+    let res;
+    try {
+      res = await fetch(this.endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.token}`
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: this.nextId++,
+          method: "tools/call",
+          params: { name, arguments: args }
+        })
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(
+        `Could not reach Image Enhancer at ${this.endpoint}. Check IE_API_URL and that the app is running. (${msg})`
+      );
+    }
+    if (res.status === 401 || res.status === 403) {
+      throw new Error(
+        "Image Enhancer rejected the linking token (401/403). Re-copy IE_MCP_TOKEN from Settings \u2192 Connect with Claude, or rotate it if it was revoked."
+      );
+    }
+    if (!res.ok) {
+      throw new Error(
+        `Image Enhancer returned HTTP ${res.status} ${res.statusText} for tool "${name}".`
+      );
+    }
+    let envelope;
+    try {
+      envelope = await res.json();
+    } catch {
+      throw new Error(`Image Enhancer returned a non-JSON response for tool "${name}".`);
+    }
+    if (envelope.error) {
+      if (envelope.error.code === -32001) {
+        throw new Error(
+          `Authentication failed: ${envelope.error.message}. Re-copy IE_MCP_TOKEN from Settings \u2192 Connect with Claude.`
+        );
+      }
+      throw new Error(envelope.error.message || `Image Enhancer error on tool "${name}".`);
+    }
+    return parseToolResult(envelope.result, name);
+  }
+};
+function parseToolResult(result, name) {
+  const text = result?.content?.find((c) => c.type === "text")?.text;
+  if (text === void 0) {
+    throw new Error(`Image Enhancer returned no content for tool "${name}".`);
+  }
+  if (result?.isError) {
+    throw new Error(text);
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object") return parsed;
+    return { value: parsed };
+  } catch {
+    return { message: text };
+  }
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools.ts
+import { z } from "zod";
+function toNumericProductId(raw) {
+  const v = raw.trim();
+  const gid = v.match(/^gid:\/\/shopify\/Product\/(\d+)$/);
+  if (gid?.[1]) return gid[1];
+  const url = v.match(/\/products\/(\d{6,})(?:[/?#]|$)/);
+  if (url?.[1]) return url[1];
+  return v;
+}
+var productIdField = z.string().min(1).describe(
+  'Shopify product id. Numeric is preferred (e.g. "15002236518511"); a full gid://shopify/Product/<id> or admin /products/<id> URL is also accepted.'
+);
+var additionalImageUrlsField = z.array(z.string().url()).max(8).optional().describe(
+  "Optional already-hosted https image URLs (detail close-ups / reference views) passed as extra context to the generator. Attaching raw image bytes from the chat is handled by the agent in a later phase; for now pass URLs."
+);
+var READ = { readOnlyHint: true, openWorldHint: true };
+var WRITE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+var STATE_CHANGE = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+var jobAcceptedShape = {
+  ok: z.boolean().optional(),
+  image_job_id: z.string().optional(),
+  job_id: z.string().optional(),
+  product_id: z.string().optional(),
+  derivation: z.string().optional(),
+  mode: z.string().optional(),
+  also_generate_back: z.boolean().optional(),
+  parent_image_job_id: z.string().optional(),
+  next: z.string().optional()
+};
+var jobStatusShape = {
+  image_job_id: z.string().optional(),
+  status: z.string().optional(),
+  current_phase: z.string().nullable().optional(),
+  version_count: z.number().optional(),
+  latest_version_id: z.string().nullable().optional(),
+  latest_version_status: z.string().nullable().optional(),
+  blocking_validator_failures: z.number().optional()
+};
+var productListShape = {
+  count: z.number().optional(),
+  products: z.array(z.record(z.unknown())).optional()
+};
+var productStatusShape = {
+  state: z.string().optional(),
+  product_id: z.string().optional(),
+  gm_image_job_id: z.string().nullable().optional(),
+  ghost_mannequin: z.record(z.unknown()).optional(),
+  ai_model: z.record(z.unknown()).optional(),
+  detail: z.record(z.unknown()).optional(),
+  lifestyle: z.record(z.unknown()).optional(),
+  flat_lay: z.record(z.unknown()).optional()
+};
+var pendingListShape = {
+  count: z.number().optional(),
+  pending: z.array(z.record(z.unknown())).optional()
+};
+var approveShape = {
+  ok: z.boolean().optional(),
+  version_id: z.string().optional(),
+  status: z.string().optional()
+};
+var productDiscoveryShape = {
+  count: z.number().optional(),
+  metric: z.string().optional(),
+  window_days: z.number().optional(),
+  products: z.array(z.record(z.unknown())).optional()
+};
+function buildTools() {
+  return [
+    // 0a. Best-sellers — the first step of the merchant flow: pick a test set.
+    {
+      name: "enhancer_suggest_products",
+      title: "Suggest best-selling products",
+      description: "Suggest the merchant's top products by revenue over a recent window, with each product's current Image Enhancer derivation status. Use this to propose a test set to start with.",
+      inputSchema: {
+        limit: z.number().int().min(1).max(50).optional().describe("How many products to suggest (default 10)."),
+        window_days: z.number().int().min(1).max(365).optional().describe("Look-back window in days for the revenue ranking (default 90).")
+      },
+      outputSchema: productDiscoveryShape,
+      annotations: { title: "Suggest best-selling products", ...READ },
+      resolve: (input) => ({
+        mcpName: "suggest_products",
+        args: { limit: input.limit, window_days: input.window_days }
+      })
+    },
+    // 0b. Search — swap helper.
+    {
+      name: "enhancer_search_products",
+      title: "Search products",
+      description: "Free-text search the merchant's catalog (by title / handle / vendor / etc.) to find products to add or swap into a test set.",
+      inputSchema: {
+        query: z.string().min(1).describe("Search text (Shopify product search syntax supported)."),
+        limit: z.number().int().min(1).max(50).optional().describe("Max results (default 10).")
+      },
+      outputSchema: productDiscoveryShape,
+      annotations: { title: "Search products", ...READ },
+      resolve: (input) => ({
+        mcpName: "search_products",
+        args: { query: input.query, limit: input.limit }
+      })
+    },
+    // 0c. By SKU — swap helper.
+    {
+      name: "enhancer_list_by_sku",
+      title: "List products by SKU",
+      description: "Look up products by one or more exact SKUs. Use to assemble or swap a test set by SKU.",
+      inputSchema: {
+        skus: z.array(z.string().min(1)).min(1).max(50).describe("One or more exact SKUs to look up (max 50).")
+      },
+      outputSchema: productDiscoveryShape,
+      annotations: { title: "List products by SKU", ...READ },
+      resolve: (input) => ({
+        mcpName: "list_by_sku",
+        args: { skus: input.skus }
+      })
+    },
+    // 0d. Pre-flight analysis (harness): quality prediction + LOGO resolution
+    //     before generating. Read-only.
+    {
+      name: "enhancer_analyze",
+      title: "Analyze a product before generating",
+      description: `Pre-flight check on a product before you generate: predicts whether the main image will enhance well (with suggestions) and resolves a brand-logo reference (the product's own detail close-up, a "LOGO" product, or none with a suggestion). Run this first to preserve logos and catch bad source photos early.`,
+      inputSchema: {
+        product_id: productIdField
+      },
+      outputSchema: {
+        product_id: z.string().optional(),
+        title: z.string().optional(),
+        pre_analysis: z.record(z.unknown()).optional(),
+        logo: z.record(z.unknown()).optional(),
+        notes: z.array(z.string()).optional()
+      },
+      annotations: { title: "Analyze a product before generating", ...READ },
+      resolve: (input) => ({
+        mcpName: "analyze_product",
+        args: { product_id: toNumericProductId(input.product_id) }
+      })
+    },
+    // 1. Root Ghost Mannequin — the entry point of the whole flow. Takes a
+    //    product's main image (fetched server-side via the merchant's OAuth
+    //    token) and renders the garment on an invisible body.
+    {
+      name: "enhancer_ghost_mannequin",
+      title: "Generate Ghost Mannequin",
+      description: "Start a Ghost Mannequin from a Shopify product. Fetches the product's main image via the merchant's connection and renders the garment as if worn by an invisible body. Returns image_job_id \u2014 poll enhancer_job_status until it completes. This is the root image; AI-model / detail / lifestyle / flat-lay / premium derivations all build on the approved Ghost Mannequin.",
+      inputSchema: {
+        product_id: productIdField,
+        also_generate_back: z.boolean().optional().describe("Also auto-generate the back view if a back photo is detected (default true)."),
+        front_image_url: z.string().url().optional().describe(
+          "Override the front source. Must be one of the product's own Shopify image URLs."
+        ),
+        back_image_url: z.string().url().optional().describe(
+          "Explicit back-view source. Must be one of the product's own Shopify image URLs."
+        ),
+        additional_image_urls: additionalImageUrlsField,
+        style_reference_url: z.string().url().optional().describe(
+          'Optional "make it look like this" reference image (desired lighting / mood / composition). The garment identity still comes from the product.'
+        ),
+        logo_reference_url: z.string().url().optional().describe(
+          'Optional brand-logo reference image (e.g. from enhancer_analyze) so the logo is preserved. May come from another product (a "LOGO" product).'
+        )
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate Ghost Mannequin", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "generate_ghost_mannequin",
+        args: {
+          product_id: toNumericProductId(input.product_id),
+          also_generate_back: input.also_generate_back,
+          front_image_url: input.front_image_url,
+          back_image_url: input.back_image_url,
+          additional_image_urls: input.additional_image_urls,
+          style_reference_url: input.style_reference_url,
+          logo_reference_url: input.logo_reference_url
+        }
+      })
+    },
+    // 2. AI Model
+    {
+      name: "enhancer_ai_model",
+      title: "Generate AI Model shot",
+      description: "Render the product worn by a curated virtual model in a chosen pose. Requires an approved Ghost Mannequin for the product. model_id and pose_id are preset ids from the studio. Returns image_job_id.",
+      inputSchema: {
+        product_id: productIdField,
+        model_id: z.string().min(1).describe("Curated model profile id."),
+        pose_id: z.string().min(1).describe("Pose preset id.")
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate AI Model shot", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "generate_derivation",
+        args: {
+          product_id: toNumericProductId(input.product_id),
+          derivation: "ai_model",
+          model_id: input.model_id,
+          pose_id: input.pose_id
+        }
+      })
+    },
+    // 3. Detail
+    {
+      name: "enhancer_detail",
+      title: "Generate Detail close-up",
+      description: "Render a close-up of a specific region of the product (collar, cuff, hem, print, etc.). Requires an approved Ghost Mannequin. region_slug is a detail-region preset slug. Returns image_job_id.",
+      inputSchema: {
+        product_id: productIdField,
+        region_slug: z.string().min(1).describe('Detail-region preset slug (e.g. "collar", "cuff").')
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate Detail close-up", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "generate_derivation",
+        args: {
+          product_id: toNumericProductId(input.product_id),
+          derivation: "detail",
+          region_slug: input.region_slug
+        }
+      })
+    },
+    // 4. Lifestyle
+    {
+      name: "enhancer_lifestyle",
+      title: "Generate Lifestyle scene",
+      description: "Render the product worn by a model in a lifestyle scene (cafe, street, at home, \u2026). Requires an approved Ghost Mannequin. Needs model_id, pose_id, and a lifestyle scene_slug. Returns image_job_id.",
+      inputSchema: {
+        product_id: productIdField,
+        model_id: z.string().min(1).describe("Curated model profile id."),
+        pose_id: z.string().min(1).describe("Pose preset id."),
+        scene_slug: z.string().min(1).describe("Lifestyle scene preset slug.")
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate Lifestyle scene", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "generate_derivation",
+        args: {
+          product_id: toNumericProductId(input.product_id),
+          derivation: "lifestyle",
+          model_id: input.model_id,
+          pose_id: input.pose_id,
+          scene_slug: input.scene_slug
+        }
+      })
+    },
+    // 5. Flat lay
+    {
+      name: "enhancer_flat_lay",
+      title: "Generate Flat Lay",
+      description: "Render the product as a top-down flat lay in a curated scene. Requires an approved Ghost Mannequin. scene_slug is a flat-lay scene preset slug. Returns image_job_id.",
+      inputSchema: {
+        product_id: productIdField,
+        scene_slug: z.string().min(1).describe("Flat-lay scene preset slug.")
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate Flat Lay", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "generate_derivation",
+        args: {
+          product_id: toNumericProductId(input.product_id),
+          derivation: "flat_lay",
+          scene_slug: input.scene_slug
+        }
+      })
+    },
+    // 6. AI Model Premium
+    {
+      name: "enhancer_premium_model",
+      title: "Generate AI Model Premium",
+      description: "Editorial model shot: model + pose + a curated premium scene OR a free-form scene description. Requires an approved Ghost Mannequin (resolved automatically). Provide scene_slug OR refined_prompt (at least one). Returns image_job_id.",
+      inputSchema: {
+        product_id: productIdField,
+        model_id: z.string().min(1).describe("Curated model profile id."),
+        pose_id: z.string().min(1).describe("Pose preset id."),
+        scene_slug: z.string().min(1).optional().describe("Premium scene preset slug. Provide this OR refined_prompt."),
+        refined_prompt: z.string().min(20).optional().describe(
+          "Free-form editorial scene description (\u226520 chars). Provide this OR scene_slug."
+        ),
+        framing: z.enum(["auto", "full_body", "upper_body", "head_to_knees", "close_up"]).optional().describe("Framing of the shot (default auto).")
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate AI Model Premium", ...WRITE },
+      resolve: (input) => {
+        const sceneSlug = input.scene_slug;
+        const refinedPrompt = input.refined_prompt;
+        if (!sceneSlug && !refinedPrompt) {
+          throw new Error(
+            "enhancer_premium_model needs either scene_slug (a curated premium scene) or refined_prompt (a free-form scene description, \u226520 chars)."
+          );
+        }
+        return {
+          mcpName: "generate_ai_model_premium",
+          args: {
+            product_id: toNumericProductId(input.product_id),
+            model_id: input.model_id,
+            pose_id: input.pose_id,
+            scene_slug: sceneSlug,
+            refined_prompt: refinedPrompt,
+            framing: input.framing
+          }
+        };
+      }
+    },
+    // 7. Video
+    {
+      name: "enhancer_video",
+      title: "Generate product Video",
+      description: "Animate an approved still of the product into a short marketing video. By default uses the approved Ghost Mannequin as the first frame; pass source_version_id to start from another approved still, and final_version_id to interpolate to an end frame (e.g. front\u2192back rotation). Returns image_job_id.",
+      inputSchema: {
+        product_id: productIdField,
+        prompt: z.string().min(20).max(2e3).describe('Motion description (\u226520 chars), e.g. "slow 360\xB0 turn, soft studio light".'),
+        duration_seconds: z.union([z.literal(5), z.literal(8), z.literal(10)]).optional().describe("Clip length in seconds: 5, 8, or 10 (default 5)."),
+        resolution: z.enum(["720p", "1080p"]).optional().describe("Output resolution (default 720p)."),
+        engine: z.enum(["seedance", "kling"]).optional().describe("Video engine A/B (default seedance)."),
+        source_version_id: z.string().min(1).optional().describe(
+          "Approved still version to use as the first frame. Defaults to the Ghost Mannequin."
+        ),
+        final_version_id: z.string().min(1).optional().describe("Optional approved still to interpolate to as the end frame.")
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate product Video", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "generate_video",
+        args: {
+          product_id: toNumericProductId(input.product_id),
+          prompt: input.prompt,
+          duration_seconds: input.duration_seconds,
+          resolution: input.resolution,
+          engine: input.engine,
+          source_version_id: input.source_version_id,
+          final_version_id: input.final_version_id
+        }
+      })
+    },
+    // 8. Banner
+    {
+      name: "enhancer_banner",
+      title: "Generate Banner (outpaint)",
+      description: "Outpaint an approved still of the product to a wide / tall banner aspect ratio (16:9, 4:1, or 9:16). Defaults to the approved Ghost Mannequin; pass source_version_id to expand a different approved still. Returns image_job_id.",
+      inputSchema: {
+        product_id: productIdField,
+        aspect_ratio: z.enum(["16:9", "4:1", "9:16"]).describe("Target banner aspect ratio."),
+        source_version_id: z.string().min(1).optional().describe("Approved still version to expand. Defaults to the Ghost Mannequin.")
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Generate Banner (outpaint)", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "generate_banner",
+        args: {
+          product_id: toNumericProductId(input.product_id),
+          aspect_ratio: input.aspect_ratio,
+          source_version_id: input.source_version_id
+        }
+      })
+    },
+    // 9. Iterate
+    {
+      name: "enhancer_iterate",
+      title: "Iterate on a result",
+      description: "Re-run an existing image job with a text adjustment (and optionally a marked-up screenshot showing exactly what to change). Creates a new image_job that inherits the source + spec and applies the adjustment. Returns the new image_job_id.",
+      inputSchema: {
+        image_job_id: z.string().min(1).describe("The image_job_id to iterate on (from a previous generation)."),
+        adjustment: z.string().min(1).max(2e3).describe(
+          'What to change, in plain language, e.g. "make the background warmer, keep the logo crisp".'
+        ),
+        annotation_image_url: z.string().url().optional().describe(
+          "Optional https URL of a marked-up screenshot (arrows/circles) indicating the exact edits."
+        )
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Iterate on a result", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "iterate_version",
+        args: {
+          image_job_id: input.image_job_id,
+          adjustment: input.adjustment,
+          annotation_image_url: input.annotation_image_url
+        }
+      })
+    },
+    // 10. Job status
+    {
+      name: "enhancer_job_status",
+      title: "Check job status",
+      description: "Poll the status of an image_job created by any enhancer_* generation tool. Returns the current phase (extract / generate / validate / publish), the status, and the latest version id when generation completed. Typical end-to-end duration is 30\u201390s.",
+      inputSchema: {
+        image_job_id: z.string().min(1).describe("The image_job_id to poll.")
+      },
+      outputSchema: jobStatusShape,
+      annotations: { title: "Check job status", ...READ },
+      resolve: (input) => ({
+        mcpName: "get_job_status",
+        args: { image_job_id: input.image_job_id }
+      })
+    },
+    // 11. List products by status
+    {
+      name: "enhancer_list_products",
+      title: "List products by derivation status",
+      description: "List the merchant's products filtered by Image Enhancer derivation status (no_gm | gm_ready | partial | complete | all), optionally narrowing to those missing a specific derivation.",
+      inputSchema: {
+        status: z.enum(["no_gm", "gm_ready", "partial", "complete", "all"]).optional().describe("Filter by overall derivation status (default all)."),
+        missing_mode: z.enum(["ai_model", "detail", "lifestyle", "flat_lay"]).optional().describe("Only products missing this derivation."),
+        limit: z.number().int().min(1).max(100).optional().describe("Max rows (default 20).")
+      },
+      outputSchema: productListShape,
+      annotations: { title: "List products by derivation status", ...READ },
+      resolve: (input) => ({
+        mcpName: "list_products_by_status",
+        args: {
+          status: input.status,
+          missing_mode: input.missing_mode,
+          limit: input.limit
+        }
+      })
+    },
+    // 12. Product studio status
+    {
+      name: "enhancer_product_status",
+      title: "Get product studio status",
+      description: "Get the full derivation status for one product (which of ghost_mannequin / ai_model / detail / lifestyle / flat_lay are approved).",
+      inputSchema: {
+        product_id: productIdField
+      },
+      outputSchema: productStatusShape,
+      annotations: { title: "Get product studio status", ...READ },
+      resolve: (input) => ({
+        mcpName: "get_product_studio_status",
+        args: { product_id: toNumericProductId(input.product_id) }
+      })
+    },
+    // 13. List pending approvals
+    {
+      name: "enhancer_list_pending",
+      title: "List pending approvals",
+      description: "List generated image versions waiting for merchant approval, optionally filtered by mode.",
+      inputSchema: {
+        mode: z.enum(["ghost_mannequin", "ai_model", "detail", "lifestyle", "flat_lay"]).optional().describe("Only versions of this mode."),
+        limit: z.number().int().min(1).max(100).optional().describe("Max rows (default 20).")
+      },
+      outputSchema: pendingListShape,
+      annotations: { title: "List pending approvals", ...READ },
+      resolve: (input) => ({
+        mcpName: "list_pending_approvals",
+        args: { mode: input.mode, limit: input.limit }
+      })
+    },
+    // 14. Approve
+    {
+      name: "enhancer_approve",
+      title: "Approve a version",
+      description: "Approve a pending image version. It transitions to pending_publish and the publish phase pushes it to the Shopify CDN as a product image.",
+      inputSchema: {
+        version_id: z.string().min(1).describe("The image version id to approve.")
+      },
+      outputSchema: approveShape,
+      annotations: { title: "Approve a version", ...STATE_CHANGE },
+      resolve: (input) => ({
+        mcpName: "approve_version",
+        args: { version_id: input.version_id }
+      })
+    },
+    // 15. Reject
+    {
+      name: "enhancer_reject",
+      title: "Reject a version",
+      description: "Reject a pending image version. It transitions to rejected; you can regenerate with enhancer_iterate.",
+      inputSchema: {
+        version_id: z.string().min(1).describe("The image version id to reject."),
+        reason: z.string().optional().describe("Optional rejection reason (audit / retry hint).")
+      },
+      outputSchema: approveShape,
+      annotations: { title: "Reject a version", ...STATE_CHANGE },
+      resolve: (input) => ({
+        mcpName: "reject_version",
+        args: { version_id: input.version_id, reason: input.reason }
+      })
+    },
+    // 16. Feedback submit (carita)
+    {
+      name: "enhancer_feedback_submit",
+      title: "Rate a result (carita)",
+      description: "Rate a generated result with a carita \u{1F61E}\u{1F610}\u{1F642}\u{1F604} \u2192 1..4 (1 worst, 4 best), with an optional comment. Re-rating the same version updates the score; low caritas feed the improvement points in enhancer_feedback_report.",
+      inputSchema: {
+        version_id: z.string().min(1).describe("The image version id being rated."),
+        rating: z.number().int().min(1).max(4).describe("1=\u{1F61E} (worst) \xB7 2=\u{1F610} \xB7 3=\u{1F642} \xB7 4=\u{1F604} (best)."),
+        comment: z.string().optional().describe("Optional note on what to improve.")
+      },
+      outputSchema: {
+        ok: z.boolean().optional(),
+        version_id: z.string().optional(),
+        rating: z.number().optional(),
+        comment: z.string().nullable().optional()
+      },
+      annotations: { title: "Rate a result (carita)", ...STATE_CHANGE },
+      resolve: (input) => ({
+        mcpName: "feedback_submit",
+        args: { version_id: input.version_id, rating: input.rating, comment: input.comment }
+      })
+    },
+    // 17. Feedback report
+    {
+      name: "enhancer_feedback_report",
+      title: "Feedback report",
+      description: "Aggregate your result ratings: total, average, distribution per carita, per-mode averages (worst first), and the improvement points (low-rated results with comments).",
+      inputSchema: {
+        window_days: z.number().int().min(1).max(365).optional().describe("Only ratings from the last N days (default: all time).")
+      },
+      outputSchema: {
+        total: z.number().optional(),
+        average: z.number().nullable().optional(),
+        distribution: z.record(z.unknown()).optional(),
+        by_mode: z.array(z.record(z.unknown())).optional(),
+        improvement_points: z.array(z.record(z.unknown())).optional()
+      },
+      annotations: { title: "Feedback report", ...READ },
+      resolve: (input) => ({
+        mcpName: "feedback_report",
+        args: { window_days: input.window_days }
+      })
+    },
+    // 18. Result iterate (feedback-driven re-run)
+    {
+      name: "enhancer_result_iterate",
+      title: "Iterate a result with new params",
+      description: "Re-run a result with new params after a low rating: spawns a fresh attempt from the result's job, optionally with a text adjustment, a different model/pose, and/or a style reference. Returns the new image_job_id.",
+      inputSchema: {
+        image_job_id: z.string().min(1).describe("The image_job_id of the result to iterate on."),
+        adjustment: z.string().max(2e3).optional().describe("Optional plain-language change (\u22642000 chars)."),
+        model_id: z.string().min(1).optional().describe("Optional different model profile id."),
+        pose_id: z.string().min(1).optional().describe("Optional different pose preset id."),
+        style_reference_url: z.string().url().optional().describe('Optional "make it look like this" reference image.')
+      },
+      outputSchema: jobAcceptedShape,
+      annotations: { title: "Iterate a result with new params", ...WRITE },
+      resolve: (input) => ({
+        mcpName: "result_iterate",
+        args: {
+          image_job_id: input.image_job_id,
+          adjustment: input.adjustment,
+          model_id: input.model_id,
+          pose_id: input.pose_id,
+          style_reference_url: input.style_reference_url
+        }
+      })
+    }
+  ];
+}
+
+// src/server.ts
+var SERVER_INFO = { name: "image-enhancer", version: "0.1.0" };
+function createServer(client) {
+  const server = new McpServer(SERVER_INFO, {
+    instructions: "Image Enhancer \u2014 generate Shopify-ready apparel photography (Ghost Mannequin, AI model, detail, lifestyle, flat lay, premium, video, banner) with strict product-identity preservation. Start with enhancer_ghost_mannequin on a product, poll enhancer_job_status, then derive other shots from the approved Ghost Mannequin. Use enhancer_iterate to refine a result."
+  });
+  for (const tool of buildTools()) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations
+      },
+      async (args) => {
+        try {
+          const { mcpName, args: mcpArgs } = tool.resolve(args ?? {});
+          const data = await client.callTool(mcpName, mcpArgs);
+          return {
+            structuredContent: data,
+            content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          return {
+            isError: true,
+            content: [{ type: "text", text: message }]
+          };
+        }
+      }
+    );
+  }
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const config = resolveConfig();
+  const client = new HttpBridgeClient(config);
+  const server = createServer(client);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write("[image-enhancer-mcp] connected over stdio\n");
+}
+main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[image-enhancer-mcp] fatal: ${message}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "image-enhancer-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "stdio MCP server — the merchant's Claude (Desktop + Code) talks to Image Enhancer through this. Bridges stdio JSON-RPC to the app's HTTP /mcp endpoint with the merchant's ie_ token.",
+  "keywords": ["mcp", "model-context-protocol", "shopify", "image-enhancer", "claude"],
+  "license": "UNLICENSED",
+  "bin": {
+    "image-enhancer-mcp": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepack": "tsup",
+    "typecheck": "tsc --noEmit",
+    "dev": "tsx watch src/index.ts",
+    "start": "tsx src/index.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.5",
+    "tsup": "8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.3"
+  }
+}