@pixeldojo/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,587 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { PixelDojoClient } from '@pixeldojo/sdk';
+import { z } from 'zod';
+
+// src/server.ts
+function makeAttributedClient(options) {
+  const { mcpVersion, skillName, baseFetch, ...sdkOptions } = options;
+  const real = baseFetch ?? globalThis.fetch.bind(globalThis);
+  const wrappedFetch = (input, init) => {
+    const headers = new Headers(init?.headers);
+    headers.set("x-pixeldojo-source", `mcp/${mcpVersion}`);
+    if (skillName) headers.set("x-pixeldojo-skill", skillName);
+    return real(input, { ...init, headers });
+  };
+  return new PixelDojoClient({
+    ...sdkOptions,
+    fetch: wrappedFetch
+  });
+}
+
+// src/poll.ts
+var DEFAULT_BACKOFF = [1e3, 2e3, 4e3, 8e3];
+var DEFAULT_MAX_INTERVAL = 8e3;
+var DEFAULT_SYNC_BUDGET_MS = 3e4;
+function defaultSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("aborted", "AbortError"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new DOMException("aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+async function pollJobUntilDoneOrHandoff(jobId, fetchJob, buildStatusUrl, options = {}) {
+  const {
+    syncBudgetMs = DEFAULT_SYNC_BUDGET_MS,
+    backoffSequenceMs = DEFAULT_BACKOFF,
+    maxIntervalMs = DEFAULT_MAX_INTERVAL,
+    now = Date.now,
+    sleep = (ms) => defaultSleep(ms, options.signal),
+    signal
+  } = options;
+  const start = now();
+  let attempt = 0;
+  while (true) {
+    if (signal?.aborted) throw new DOMException("aborted", "AbortError");
+    const job = await fetchJob(jobId);
+    if (job.status === "completed") return { kind: "completed", job };
+    if (job.status === "failed") return { kind: "failed", job };
+    const elapsed = now() - start;
+    const remaining = syncBudgetMs - elapsed;
+    if (remaining <= 0) {
+      return {
+        kind: "handoff",
+        jobId,
+        statusUrl: buildStatusUrl(jobId)
+      };
+    }
+    const interval = attempt < backoffSequenceMs.length ? backoffSequenceMs[attempt] : maxIntervalMs;
+    const wait = Math.min(interval, Math.max(remaining, 0));
+    if (wait > 0) await sleep(wait);
+    attempt++;
+  }
+}
+
+// src/skills/types.ts
+function pollResultToSkillResult(result, successText) {
+  if (result.kind === "completed") {
+    const urls = extractAssetUrls(result.job);
+    return {
+      kind: "assets",
+      text: successText(urls),
+      assetUrls: urls
+    };
+  }
+  if (result.kind === "failed") {
+    const errMsg = typeof result.job.error === "string" ? result.job.error : result.job.error?.message ?? "Unknown provider error";
+    return {
+      kind: "text",
+      text: `Job ${result.job.jobId} failed: ${errMsg}`
+    };
+  }
+  return {
+    kind: "handoff",
+    text: `Job ${result.jobId} is still running after the 30s sync window. Use pixeldojo:status with this jobId to check completion, or follow ${result.statusUrl}.`,
+    jobId: result.jobId,
+    statusUrl: result.statusUrl
+  };
+}
+function extractAssetUrls(job) {
+  if (job.assets && job.assets.length > 0) return job.assets.map((a) => a.url);
+  const output = job.output;
+  if (output?.images) return output.images;
+  if (output?.videos) return output.videos;
+  if (output?.image) return [output.image];
+  if (output?.video) return [output.video];
+  return [];
+}
+
+// src/skills/generate.ts
+var InputSchema = z.object({
+  prompt: z.string().min(1).max(8e3).describe("Prompt describing what to generate."),
+  model: z.string().optional().describe(
+    'Override the model. Any apiId from /api/v1/models (e.g. "flux", "google-nano-banana", "veo-3.1", "kling-video"). Omit to use the default.'
+  ),
+  aspect_ratio: z.string().optional().describe('Aspect ratio supported by the chosen model (e.g. "1:1", "16:9", "9:16").'),
+  duration: z.number().int().positive().optional().describe("Video duration in seconds, when applicable."),
+  image_url: z.string().url().optional().describe("Reference image URL for image-to-image / image-to-video tools.")
+});
+var DEFAULT_MODEL = "google-nano-banana";
+var InputJsonSchema = {
+  type: "object",
+  properties: {
+    prompt: { type: "string", description: "Prompt describing what to generate." },
+    model: {
+      type: "string",
+      description: 'Override the model. Any apiId from /api/v1/models (e.g. "flux", "google-nano-banana", "veo-3.1", "kling-video"). Omit to use the default.'
+    },
+    aspect_ratio: { type: "string" },
+    duration: { type: "integer" },
+    image_url: { type: "string", format: "uri" }
+  },
+  required: ["prompt"]
+};
+async function run(input, ctx) {
+  const apiId = input.model ?? DEFAULT_MODEL;
+  const body = { prompt: input.prompt };
+  if (input.aspect_ratio) body.aspect_ratio = input.aspect_ratio;
+  if (input.duration !== void 0) body.duration = input.duration;
+  if (input.image_url) body.image_url = input.image_url;
+  const submitted = await ctx.client.run(apiId, body);
+  const result = await pollJobUntilDoneOrHandoff(
+    submitted.jobId,
+    (id) => ctx.client.getJob(id),
+    ctx.buildStatusUrl,
+    {
+      now: ctx.pollOverrides?.now,
+      sleep: ctx.pollOverrides?.sleep
+    }
+  );
+  return pollResultToSkillResult(
+    result,
+    (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : urls.length === 1 ? `Generated. Asset: ${urls[0]}` : `Generated ${urls.length} assets. URLs: ${urls.join(", ")}`
+  );
+}
+var generateSkill = {
+  name: "pixeldojo:generate",
+  description: "Generate any image or video from a prompt. Auto-routes to a sensible default model; pass `model` to pick a specific apiId from the catalog.",
+  inputZod: InputSchema,
+  inputJsonSchema: InputJsonSchema,
+  allowedModels: null,
+  defaultModel: DEFAULT_MODEL,
+  run
+};
+var ALLOWED = ["ideogram-character", "flux-edit", "gpt-image-2-edit"];
+var DEFAULT_MODEL2 = "ideogram-character";
+var InputSchema2 = z.object({
+  prompt: z.string().min(1).max(8e3),
+  model: z.string().optional().describe(`One of: ${ALLOWED.join(", ")}. Defaults to ${DEFAULT_MODEL2}.`),
+  reference_image_url: z.string().url().optional().describe(
+    "Reference image of the character. Required by flux-edit and gpt-image-2-edit; optional for ideogram-character."
+  ),
+  aspect_ratio: z.string().optional()
+});
+var InputJsonSchema2 = {
+  type: "object",
+  properties: {
+    prompt: { type: "string" },
+    model: {
+      type: "string",
+      enum: ALLOWED,
+      description: `One of: ${ALLOWED.join(", ")}. Defaults to ${DEFAULT_MODEL2}.`
+    },
+    reference_image_url: { type: "string", format: "uri" },
+    aspect_ratio: { type: "string" }
+  },
+  required: ["prompt"]
+};
+async function run2(input, ctx) {
+  const requested = input.model ?? DEFAULT_MODEL2;
+  if (!ALLOWED.includes(requested)) {
+    return {
+      kind: "text",
+      text: `Unknown model "${requested}" for pixeldojo:character. Allowed: ${ALLOWED.join(", ")}.`
+    };
+  }
+  const apiId = requested;
+  const body = { prompt: input.prompt };
+  if (input.aspect_ratio) body.aspect_ratio = input.aspect_ratio;
+  if (input.reference_image_url) {
+    body.image_url = input.reference_image_url;
+    body.reference_image_url = input.reference_image_url;
+  }
+  const submitted = await ctx.client.run(apiId, body);
+  const result = await pollJobUntilDoneOrHandoff(
+    submitted.jobId,
+    (id) => ctx.client.getJob(id),
+    ctx.buildStatusUrl,
+    {
+      now: ctx.pollOverrides?.now,
+      sleep: ctx.pollOverrides?.sleep
+    }
+  );
+  return pollResultToSkillResult(
+    result,
+    (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Character shot ready. Asset: ${urls[0]}`
+  );
+}
+var characterSkill = {
+  name: "pixeldojo:character",
+  description: "Generate or edit consistent characters across shots. Pass a reference_image_url for edit-style models.",
+  inputZod: InputSchema2,
+  inputJsonSchema: InputJsonSchema2,
+  allowedModels: [...ALLOWED],
+  defaultModel: DEFAULT_MODEL2,
+  run: run2
+};
+var ALLOWED2 = ["veo-3.1", "kling-video", "seedance-2"];
+var DEFAULT_MODEL3 = "veo-3.1";
+var InputSchema3 = z.object({
+  brief: z.string().min(1).max(8e3).describe("Storyboard brief: scene, shots, mood, action."),
+  model: z.string().optional().describe(`One of: ${ALLOWED2.join(", ")}. Defaults to ${DEFAULT_MODEL3}.`),
+  aspect_ratio: z.string().optional(),
+  duration: z.number().int().positive().optional()
+});
+var InputJsonSchema3 = {
+  type: "object",
+  properties: {
+    brief: {
+      type: "string",
+      description: "Storyboard brief: scene, shots, mood, action."
+    },
+    model: {
+      type: "string",
+      enum: ALLOWED2,
+      description: `One of: ${ALLOWED2.join(", ")}. Defaults to ${DEFAULT_MODEL3}.`
+    },
+    aspect_ratio: { type: "string" },
+    duration: { type: "integer" }
+  },
+  required: ["brief"]
+};
+async function run3(input, ctx) {
+  const requested = input.model ?? DEFAULT_MODEL3;
+  if (!ALLOWED2.includes(requested)) {
+    return {
+      kind: "text",
+      text: `Unknown model "${requested}" for pixeldojo:storyboard. Allowed: ${ALLOWED2.join(", ")}.`
+    };
+  }
+  const apiId = requested;
+  const body = { prompt: input.brief };
+  if (input.aspect_ratio) body.aspect_ratio = input.aspect_ratio;
+  if (input.duration !== void 0) body.duration = input.duration;
+  const submitted = await ctx.client.run(apiId, body);
+  const result = await pollJobUntilDoneOrHandoff(
+    submitted.jobId,
+    (id) => ctx.client.getJob(id),
+    ctx.buildStatusUrl,
+    {
+      now: ctx.pollOverrides?.now,
+      sleep: ctx.pollOverrides?.sleep
+    }
+  );
+  return pollResultToSkillResult(
+    result,
+    (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Storyboard preview ready. Asset: ${urls[0]}`
+  );
+}
+var storyboardSkill = {
+  name: "pixeldojo:storyboard",
+  description: "Generate a video storyboard preview from a single brief. v1: single-shot preview; multi-shot orchestration coming.",
+  inputZod: InputSchema3,
+  inputJsonSchema: InputJsonSchema3,
+  allowedModels: [...ALLOWED2],
+  defaultModel: DEFAULT_MODEL3,
+  run: run3
+};
+var ALLOWED3 = ["magnific-upscaler", "creative-upscale", "face-enhance"];
+var DEFAULT_MODEL4 = "magnific-upscaler";
+var InputSchema4 = z.object({
+  image_url: z.string().url().describe("URL of the source image to upscale."),
+  model: z.string().optional().describe(`One of: ${ALLOWED3.join(", ")}. Defaults to ${DEFAULT_MODEL4}.`),
+  scale_factor: z.number().int().min(1).max(4).optional().describe("Magnific only: 1, 2, or 4. Defaults to 2."),
+  creativity: z.number().min(0).max(1).optional().describe("Magnific only: 0 (preserve) \u2192 1 (creative). Defaults to 0.")
+});
+var InputJsonSchema4 = {
+  type: "object",
+  properties: {
+    image_url: { type: "string", format: "uri" },
+    model: { type: "string", enum: ALLOWED3 },
+    scale_factor: { type: "integer", minimum: 1, maximum: 4 },
+    creativity: { type: "number", minimum: 0, maximum: 1 }
+  },
+  required: ["image_url"]
+};
+async function run4(input, ctx) {
+  const requested = input.model ?? DEFAULT_MODEL4;
+  if (!ALLOWED3.includes(requested)) {
+    return {
+      kind: "text",
+      text: `Unknown model "${requested}" for pixeldojo:upscale. Allowed: ${ALLOWED3.join(", ")}.`
+    };
+  }
+  const apiId = requested;
+  const body = {
+    prompt: "",
+    image_url: input.image_url
+  };
+  if (apiId === "magnific-upscaler") {
+    body.scale_factor = input.scale_factor ?? 2;
+    if (input.creativity !== void 0) body.creativity = input.creativity;
+  }
+  const submitted = await ctx.client.run(apiId, body);
+  const result = await pollJobUntilDoneOrHandoff(
+    submitted.jobId,
+    (id) => ctx.client.getJob(id),
+    ctx.buildStatusUrl,
+    {
+      now: ctx.pollOverrides?.now,
+      sleep: ctx.pollOverrides?.sleep
+    }
+  );
+  return pollResultToSkillResult(
+    result,
+    (urls) => urls.length === 0 ? `Job ${submitted.jobId} completed but returned no assets.` : `Upscaled. Asset: ${urls[0]}`
+  );
+}
+var upscaleSkill = {
+  name: "pixeldojo:upscale",
+  description: "Enhance an image. Magnific (default) supports configurable scale_factor and creativity; face-enhance for portraits.",
+  inputZod: InputSchema4,
+  inputJsonSchema: InputJsonSchema4,
+  allowedModels: [...ALLOWED3],
+  defaultModel: DEFAULT_MODEL4,
+  run: run4
+};
+var InputSchema5 = z.object({
+  jobId: z.string().min(1).max(200).describe("Job id returned from a prior pixeldojo:* skill handoff.")
+});
+var InputJsonSchema5 = {
+  type: "object",
+  properties: {
+    jobId: {
+      type: "string",
+      description: "Job id returned from a prior pixeldojo:* skill handoff."
+    }
+  },
+  required: ["jobId"]
+};
+async function run5(input, ctx) {
+  const job = await ctx.client.getJob(input.jobId);
+  if (job.status === "completed") {
+    const urls = extractAssetUrls2(job);
+    return {
+      kind: "assets",
+      text: urls.length === 0 ? `Job ${input.jobId} completed but returned no assets.` : urls.length === 1 ? `Job ${input.jobId} completed. Asset: ${urls[0]}` : `Job ${input.jobId} completed. Assets: ${urls.join(", ")}`,
+      assetUrls: urls
+    };
+  }
+  if (job.status === "failed") {
+    const errMsg = typeof job.error === "string" ? job.error : job.error?.message ?? "Unknown provider error";
+    return {
+      kind: "text",
+      text: `Job ${input.jobId} failed: ${errMsg}`
+    };
+  }
+  return {
+    kind: "handoff",
+    text: `Job ${input.jobId} is still ${job.status}. Try again in a few seconds, or follow ${ctx.buildStatusUrl(input.jobId)}.`,
+    jobId: input.jobId,
+    statusUrl: ctx.buildStatusUrl(input.jobId)
+  };
+}
+function extractAssetUrls2(job) {
+  if (job.assets && job.assets.length > 0) return job.assets.map((a) => a.url);
+  const output = job.output;
+  if (output?.images) return output.images;
+  if (output?.videos) return output.videos;
+  if (output?.image) return [output.image];
+  if (output?.video) return [output.video];
+  return [];
+}
+var statusSkill = {
+  name: "pixeldojo:status",
+  description: "Check the status of a long-running job after a 30s sync handoff. Returns assets when ready, failure reason if failed, or current state if still running.",
+  inputZod: InputSchema5,
+  inputJsonSchema: InputJsonSchema5,
+  // status is special — it doesn't dispatch to a model
+  allowedModels: [],
+  defaultModel: "",
+  run: run5
+};
+
+// src/skills/index.ts
+var ALL_SKILLS = [
+  generateSkill,
+  characterSkill,
+  storyboardSkill,
+  upscaleSkill,
+  statusSkill
+];
+function findSkill(name) {
+  return ALL_SKILLS.find((s) => s.name === name);
+}
+
+// src/redact.ts
+var PD_KEY_RE = /pd_[A-Za-z0-9_-]{8,}/g;
+var REDACTED = "[redacted]";
+function redactKeys(input) {
+  if (!input || typeof input !== "string") return input;
+  if (!input.includes("pd_")) return input;
+  return input.replace(PD_KEY_RE, REDACTED);
+}
+function redactValue(value, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value == null) return value;
+  if (typeof value === "string") return redactKeys(value);
+  if (typeof value !== "object") return value;
+  if (seen.has(value)) return "[circular]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((v) => redactValue(v, seen));
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = redactValue(v, seen);
+  }
+  return out;
+}
+function makeRedactedLogger(target = console) {
+  return {
+    error(msg, ...args) {
+      const redactedArgs = args.map((a) => redactValue(a));
+      target.error(`[pixeldojo-mcp] ${redactKeys(msg)}`, ...redactedArgs);
+    }
+  };
+}
+
+// src/server.ts
+var PACKAGE_VERSION = "0.1.0";
+function buildServer(options) {
+  if (!options.apiKey) {
+    throw new Error(
+      "apiKey is required. Set PIXELDOJO_API_KEY env var or pass apiKey to buildServer()."
+    );
+  }
+  const version = options.packageVersion ?? PACKAGE_VERSION;
+  const baseUrl = options.baseUrl ?? "https://pixeldojo.ai";
+  const logger = makeRedactedLogger();
+  const server = new Server(
+    {
+      name: "pixeldojo",
+      version
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: ALL_SKILLS.map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+        inputSchema: skill.inputJsonSchema
+      }))
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const skillName = req.params.name;
+    const skill = findSkill(skillName);
+    if (!skill) {
+      const available = ALL_SKILLS.map((s) => s.name).join(", ");
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Unknown skill "${skillName}". Available: ${available}.`
+          }
+        ]
+      };
+    }
+    const parsed = skill.inputZod.safeParse(req.params.arguments ?? {});
+    if (!parsed.success) {
+      const issues = parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Invalid input for ${skillName}: ${issues}`
+          }
+        ]
+      };
+    }
+    const client = makeAttributedClient({
+      apiKey: options.apiKey,
+      baseUrl,
+      mcpVersion: version,
+      skillName,
+      baseFetch: options.baseFetch
+    });
+    const ctx = {
+      client,
+      mcpVersion: version,
+      logger,
+      buildStatusUrl: (jobId) => `${baseUrl}/api/v1/jobs/${encodeURIComponent(jobId)}`
+    };
+    try {
+      const result = await skill.run(parsed.data, ctx);
+      return skillResultToMcpResponse(result);
+    } catch (err) {
+      const message = errorToActionableMessage(err);
+      logger.error(`Skill ${skillName} failed`, message);
+      return {
+        isError: true,
+        content: [{ type: "text", text: message }]
+      };
+    }
+  });
+  return server;
+}
+function skillResultToMcpResponse(result) {
+  if (result.kind === "assets") {
+    return {
+      content: [
+        { type: "text", text: result.text },
+        // Each URL on its own line so an LLM can copy individually.
+        ...result.assetUrls.map((url) => ({ type: "text", text: url }))
+      ]
+    };
+  }
+  if (result.kind === "handoff") {
+    return {
+      content: [
+        { type: "text", text: result.text },
+        { type: "text", text: `jobId: ${result.jobId}` },
+        { type: "text", text: `statusUrl: ${result.statusUrl}` }
+      ]
+    };
+  }
+  return {
+    content: [{ type: "text", text: result.text }]
+  };
+}
+function errorToActionableMessage(err) {
+  if (err == null) return "Unknown error";
+  if (typeof err === "string") return err;
+  const e = err;
+  if (e.status === 401 || e.code === "auth_required" || e.name === "AuthenticationError") {
+    return "Authentication failed. Check PIXELDOJO_API_KEY. Get a key at https://pixeldojo.ai/api-platform/api-keys.";
+  }
+  if (e.status === 402 || e.code === "insufficient_credits") {
+    return "Insufficient credits. Top up at https://pixeldojo.ai/api-platform/buy-credits.";
+  }
+  if (e.status === 429 || e.code === "rate_limit") {
+    return "Rate limit hit. Try again in a few seconds.";
+  }
+  if (e.status === 404 || e.code === "not_found") {
+    return e.message ?? "Resource not found.";
+  }
+  if (e.name === "TimeoutError") {
+    return e.message ?? "Request timed out. Try again.";
+  }
+  return e.message ?? "Unknown error";
+}
+async function runStdio(options) {
+  const server = buildServer(options);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+export { ALL_SKILLS, PACKAGE_VERSION, buildServer, findSkill, makeAttributedClient, makeRedactedLogger, pollJobUntilDoneOrHandoff, redactKeys, redactValue, runStdio };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map