@warlok-net/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# @warlok-net/mcp-server
+
+MCP server for [Warlok](https://warlok.net) — gives agents the ability to summon
+game-ready, auto-rigged 3D assets from images or text prompts.
+
+## Setup
+
+Create an API key at [warlok.net/settings/api-keys](https://warlok.net/settings/api-keys), then:
+
+```json
+{
+  "mcpServers": {
+    "warlok": {
+      "command": "npx",
+      "args": ["-y", "@warlok-net/mcp-server"],
+      "env": {
+        "WARLOK_API_KEY": "<your_key>"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `generate_3d_model` | Summon a 3D asset from a prompt or image URL (1 credit = $1) |
+| `get_model_status` | Poll stage/progress (~8 min end-to-end; poll every 10–15 s) |
+| `list_models` | List the account's generations |
+| `get_model_download_url` | Signed GLB/preview URLs for a completed asset |
+| `delete_model` | Remove a generation |
+| `capture_ui_screenshot` | Optional; requires a local Playwright install |
+
+## Alpha limits
+
+Prepaid credits ($1/summon), 5 summons per rolling day, failed summons auto-refunded.
+`402` → buy credits at [warlok.net/settings](https://warlok.net/settings); `429` → daily cap reached.
+
+Docs: [warlok.net/docs/mcp](https://warlok.net/docs/mcp) · License: MIT

package/dist/chunk-HTA6LITF.mjs

@@ -0,0 +1,678 @@
+// src/index.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError
+} from "@modelcontextprotocol/sdk/types.js";
+import {
+  WarlokClient
+} from "@warlok-net/sdk";
+
+// src/screenshot.ts
+import fs from "fs/promises";
+import path from "path";
+async function loadChromium() {
+  try {
+    const playwright = await import("playwright");
+    return playwright.chromium;
+  } catch {
+    throw new Error(
+      "capture_ui_screenshot requires Playwright. Install it with: npm i playwright && npx playwright install chromium"
+    );
+  }
+}
+var DEFAULT_VIEWPORT_WIDTH = 1440;
+var DEFAULT_VIEWPORT_HEIGHT = 900;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_WAIT_MS = 250;
+var DEFAULT_FORMAT = "png";
+async function captureUiScreenshot(input) {
+  const startedAt = Date.now();
+  const url = parseHttpUrl(input.url);
+  const width = clampInteger(input.viewportWidth, 320, 7680, DEFAULT_VIEWPORT_WIDTH);
+  const height = clampInteger(
+    input.viewportHeight,
+    240,
+    4320,
+    DEFAULT_VIEWPORT_HEIGHT
+  );
+  const timeoutMs = clampInteger(input.timeoutMs, 5e3, 12e4, DEFAULT_TIMEOUT_MS);
+  const waitForMs = clampInteger(input.waitForMs, 0, 3e4, DEFAULT_WAIT_MS);
+  const fullPage = input.fullPage ?? true;
+  const colorScheme = input.colorScheme ?? "dark";
+  const format = input.format ?? inferFormatFromOutputPath(input.outputPath);
+  const outputPath = resolveOutputPath(url, input.outputPath, format);
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  const chromium = await loadChromium();
+  const browser = await chromium.launch({ headless: true });
+  try {
+    const context = await browser.newContext({
+      viewport: { width, height },
+      colorScheme,
+      deviceScaleFactor: 1
+    });
+    const page = await context.newPage();
+    page.setDefaultTimeout(timeoutMs);
+    await page.goto(url.toString(), { waitUntil: "networkidle", timeout: timeoutMs });
+    if (input.waitForSelector) {
+      await page.waitForSelector(input.waitForSelector, {
+        state: "visible",
+        timeout: timeoutMs
+      });
+    }
+    if (waitForMs > 0) {
+      await page.waitForTimeout(waitForMs);
+    }
+    if (input.selector) {
+      const locator = page.locator(input.selector).first();
+      await locator.waitFor({ state: "visible", timeout: timeoutMs });
+      await locator.screenshot({
+        path: outputPath,
+        type: format
+      });
+    } else {
+      await page.screenshot({
+        path: outputPath,
+        fullPage,
+        type: format
+      });
+    }
+    await context.close();
+  } finally {
+    await browser.close();
+  }
+  const stat = await fs.stat(outputPath);
+  return {
+    outputPath,
+    bytes: stat.size,
+    width,
+    height,
+    url: url.toString(),
+    selector: input.selector ?? null,
+    fullPage,
+    colorScheme,
+    format,
+    durationMs: Date.now() - startedAt
+  };
+}
+function parseHttpUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("Invalid URL. Expected a valid absolute URL.");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error("Invalid URL protocol. Only http/https URLs are supported.");
+  }
+  return parsed;
+}
+function resolveOutputPath(url, requestedPath, format) {
+  if (requestedPath) {
+    const absolute = path.isAbsolute(requestedPath) ? requestedPath : path.resolve(outputRoot(), requestedPath);
+    return ensureExt(absolute, format);
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+  const host = sanitizeSegment(url.host);
+  const pathname = sanitizeSegment(url.pathname.replace(/\//g, "_") || "root");
+  const filename = `${now}-${host}-${pathname}.${format}`;
+  return path.join(outputRoot(), filename);
+}
+function outputRoot() {
+  const configured = process.env.WARLOK_SCREENSHOT_DIR;
+  if (configured && configured.trim()) {
+    return path.resolve(configured.trim());
+  }
+  return path.resolve(process.cwd(), "tmp", "mcp-screenshots");
+}
+function ensureExt(value, format) {
+  const ext = path.extname(value).toLowerCase();
+  if (ext === ".png" || ext === ".jpg" || ext === ".jpeg" || ext === ".webp") {
+    return value;
+  }
+  return `${value}.${format}`;
+}
+function sanitizeSegment(value) {
+  return value.toLowerCase().replace(/[^a-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "capture";
+}
+function inferFormatFromOutputPath(pathname) {
+  if (!pathname) return DEFAULT_FORMAT;
+  const ext = path.extname(pathname).toLowerCase();
+  if (ext === ".jpg" || ext === ".jpeg") return "jpeg";
+  return "png";
+}
+function clampInteger(value, min, max, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  const rounded = Math.round(value);
+  if (rounded < min) return min;
+  if (rounded > max) return max;
+  return rounded;
+}
+
+// src/index.ts
+var TOOLS = [
+  {
+    name: "generate_3d_model",
+    description: "Generate a 3D model from text description or image. Returns an asset_id to track status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Name for the generation (max 100 characters)"
+        },
+        type: {
+          type: "string",
+          enum: [
+            "character",
+            "creature",
+            "environment",
+            "prop",
+            "weapon",
+            "vehicle",
+            "material",
+            "noun",
+            "person",
+            "place",
+            "thing"
+          ],
+          description: "Entity or legacy asset type"
+        },
+        prompt: {
+          type: "string",
+          description: "Text prompt describing what to generate"
+        },
+        image_url: {
+          type: "string",
+          description: "Optional URL to a reference image"
+        },
+        auto_rig: {
+          type: "boolean",
+          description: "Whether to rig for Mixamo when generating a person",
+          default: true
+        }
+      },
+      required: ["type"]
+    }
+  },
+  {
+    name: "get_model_status",
+    description: "Check generation status by asset_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        asset_id: {
+          type: "string",
+          description: "The generation ID"
+        }
+      },
+      required: ["asset_id"]
+    }
+  },
+  {
+    name: "list_models",
+    description: "List generations for the current account.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        limit: {
+          type: "number",
+          description: "Maximum rows to return (default: 20)",
+          default: 20
+        },
+        type: {
+          type: "string",
+          enum: [
+            "character",
+            "creature",
+            "environment",
+            "prop",
+            "weapon",
+            "vehicle",
+            "material",
+            "noun",
+            "person",
+            "place",
+            "thing"
+          ],
+          description: "Filter by entity/legacy type"
+        },
+        status: {
+          type: "string",
+          enum: [
+            "pending",
+            "preprocessing",
+            "generating",
+            "rigging",
+            "complete",
+            "failed"
+          ],
+          description: "Filter by generation status"
+        }
+      }
+    }
+  },
+  {
+    name: "get_model_download_url",
+    description: "Get the best available download URL for a completed generation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        asset_id: {
+          type: "string",
+          description: "The generation ID"
+        },
+        format: {
+          type: "string",
+          enum: ["model", "rigged"],
+          description: "Preferred format (default: best available)"
+        }
+      },
+      required: ["asset_id"]
+    }
+  },
+  {
+    name: "delete_model",
+    description: "Delete a generation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        asset_id: {
+          type: "string",
+          description: "The generation ID to delete"
+        }
+      },
+      required: ["asset_id"]
+    }
+  },
+  {
+    name: "capture_ui_screenshot",
+    description: "Capture a deterministic Playwright screenshot for UI/design iteration.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description: "HTTP/HTTPS URL to capture"
+        },
+        output_path: {
+          type: "string",
+          description: "Optional output file path. Relative paths are resolved in tmp/mcp-screenshots."
+        },
+        selector: {
+          type: "string",
+          description: "Optional CSS selector to capture only a specific element."
+        },
+        wait_for_selector: {
+          type: "string",
+          description: "Optional selector to wait for before capture (useful for async UI)."
+        },
+        wait_for_ms: {
+          type: "number",
+          description: "Extra delay before capture in milliseconds (default: 250).",
+          default: 250
+        },
+        timeout_ms: {
+          type: "number",
+          description: "Navigation and selector timeout in milliseconds (default: 30000).",
+          default: 3e4
+        },
+        full_page: {
+          type: "boolean",
+          description: "Capture full page when selector is not set (default: true).",
+          default: true
+        },
+        viewport_width: {
+          type: "number",
+          description: "Viewport width in px (default: 1440).",
+          default: 1440
+        },
+        viewport_height: {
+          type: "number",
+          description: "Viewport height in px (default: 900).",
+          default: 900
+        },
+        color_scheme: {
+          type: "string",
+          enum: ["light", "dark", "no-preference"],
+          description: "Preferred color scheme (default: dark).",
+          default: "dark"
+        },
+        format: {
+          type: "string",
+          enum: ["png", "jpeg"],
+          description: "Screenshot format (default inferred from output_path, else png)."
+        }
+      },
+      required: ["url"]
+    }
+  }
+];
+function createServer(apiKey, baseUrl) {
+  const client = new WarlokClient({ apiKey, baseUrl });
+  const server = new Server(
+    {
+      name: "warlok-mcp",
+      version: "0.1.0"
+    },
+    {
+      capabilities: {
+        tools: {}
+      }
+    }
+  );
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS
+  }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      switch (name) {
+        case "generate_3d_model": {
+          const generation = await client.generate({
+            name: stringOrUndefined(args, "name"),
+            type: requiredType(args),
+            prompt: stringOrUndefined(args, "prompt"),
+            imageUrl: stringOrUndefined(args, "image_url"),
+            options: {
+              autoRig: booleanOrUndefined(args, "auto_rig")
+            }
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: true,
+                    asset_id: generation.id,
+                    name: generation.name,
+                    entity_type: generation.entityType,
+                    status: generation.status,
+                    message: `Generation started. Use get_model_status with asset_id "${generation.id}".`
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        case "get_model_status": {
+          const generation = await client.getGeneration(requiredAssetId(args));
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(formatGenerationStatus(generation), null, 2)
+              }
+            ]
+          };
+        }
+        case "list_models": {
+          const generations = await client.listGenerations({
+            limit: numberOrUndefined(args, "limit") || 20,
+            type: typeOrUndefined(args),
+            status: statusOrUndefined(args)
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    total: generations.length,
+                    models: generations.map((generation) => ({
+                      id: generation.id,
+                      name: generation.name,
+                      entity_type: generation.entityType,
+                      status: generation.status,
+                      created_at: generation.createdAt
+                    }))
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        case "get_model_download_url": {
+          const generation = await client.getGeneration(requiredAssetId(args));
+          if (generation.status !== "complete") {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: `Generation is not complete. Current status: ${generation.status}`
+                  })
+                }
+              ]
+            };
+          }
+          const format = downloadFormatOrUndefined(args);
+          const url = format === "model" ? generation.outputs.modelUrl : format === "rigged" ? generation.outputs.riggedModelUrl : generation.outputs.riggedModelUrl || generation.outputs.modelUrl;
+          if (!url) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    success: false,
+                    error: "No download URL available for this generation"
+                  })
+                }
+              ]
+            };
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: true,
+                    asset_id: generation.id,
+                    name: generation.name,
+                    download_url: url,
+                    format: format || "best_available",
+                    prompt: generation.input.prompt || null,
+                    preview_png_url: generation.outputs.previewPngUrl || null,
+                    nanobanana_png_url: generation.outputs.promptImageUrl || generation.provenance?.preprocessPromptImageUrl || null
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        case "delete_model": {
+          const assetId = requiredAssetId(args);
+          await client.deleteGeneration(assetId);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  success: true,
+                  message: `Generation ${assetId} deleted successfully`
+                })
+              }
+            ]
+          };
+        }
+        case "capture_ui_screenshot": {
+          const screenshot = await captureUiScreenshot({
+            url: requiredUrl(args),
+            outputPath: stringOrUndefined(args, "output_path"),
+            selector: stringOrUndefined(args, "selector"),
+            waitForSelector: stringOrUndefined(args, "wait_for_selector"),
+            waitForMs: numberOrUndefined(args, "wait_for_ms"),
+            timeoutMs: numberOrUndefined(args, "timeout_ms"),
+            fullPage: booleanOrUndefined(args, "full_page"),
+            viewportWidth: numberOrUndefined(args, "viewport_width"),
+            viewportHeight: numberOrUndefined(args, "viewport_height"),
+            colorScheme: colorSchemeOrUndefined(args),
+            format: screenshotFormatOrUndefined(args)
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    success: true,
+                    ...screenshot
+                  },
+                  null,
+                  2
+                )
+              }
+            ]
+          };
+        }
+        default:
+          throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+      }
+    } catch (error) {
+      if (error instanceof McpError) {
+        throw error;
+      }
+      const message = error instanceof Error ? error.message : "Unknown error";
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ success: false, error: message })
+          }
+        ],
+        isError: true
+      };
+    }
+  });
+  return server;
+}
+function requiredAssetId(args) {
+  const value = stringOrUndefined(args, "asset_id");
+  if (!value) {
+    throw new McpError(ErrorCode.InvalidParams, "asset_id is required");
+  }
+  return value;
+}
+function requiredType(args) {
+  const value = stringOrUndefined(args, "type");
+  if (!value) {
+    throw new McpError(ErrorCode.InvalidParams, "type is required");
+  }
+  return value;
+}
+function requiredUrl(args) {
+  const value = stringOrUndefined(args, "url");
+  if (!value) {
+    throw new McpError(ErrorCode.InvalidParams, "url is required");
+  }
+  return value;
+}
+function typeOrUndefined(args) {
+  const value = stringOrUndefined(args, "type");
+  return value;
+}
+function statusOrUndefined(args) {
+  const value = stringOrUndefined(args, "status");
+  return value;
+}
+function downloadFormatOrUndefined(args) {
+  const value = stringOrUndefined(args, "format");
+  if (value === "model" || value === "rigged") {
+    return value;
+  }
+  return void 0;
+}
+function stringOrUndefined(args, key) {
+  const value = args?.[key];
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function booleanOrUndefined(args, key) {
+  const value = args?.[key];
+  return typeof value === "boolean" ? value : void 0;
+}
+function numberOrUndefined(args, key) {
+  const value = args?.[key];
+  return typeof value === "number" ? value : void 0;
+}
+function colorSchemeOrUndefined(args) {
+  const value = stringOrUndefined(args, "color_scheme");
+  if (value === "light" || value === "dark" || value === "no-preference") {
+    return value;
+  }
+  return void 0;
+}
+function screenshotFormatOrUndefined(args) {
+  const value = stringOrUndefined(args, "format");
+  if (value === "png" || value === "jpeg") {
+    return value;
+  }
+  return void 0;
+}
+function formatGenerationStatus(generation) {
+  const base = {
+    success: true,
+    asset_id: generation.id,
+    name: generation.name,
+    entity_type: generation.entityType,
+    status: generation.status,
+    progress: generation.progress,
+    prompt: generation.input.prompt || null,
+    preview_png_url: generation.outputs.previewPngUrl || null,
+    nanobanana_png_url: generation.outputs.promptImageUrl || generation.provenance?.preprocessPromptImageUrl || null,
+    created_at: generation.createdAt,
+    updated_at: generation.updatedAt
+  };
+  if (generation.status === "complete") {
+    return {
+      ...base,
+      model_url: generation.outputs.modelUrl,
+      rigged_model_url: generation.outputs.riggedModelUrl,
+      mixamo_ready: generation.outputs.mixamoReady
+    };
+  }
+  if (generation.status === "failed") {
+    return {
+      ...base,
+      error: generation.error
+    };
+  }
+  return {
+    ...base,
+    message: getStatusMessage(generation.status, generation.progress)
+  };
+}
+function getStatusMessage(status, progress) {
+  const messages = {
+    pending: "Queued for processing",
+    preprocessing: "Preparing specialized PNG",
+    generating: "Generating 3D mesh",
+    rigging: "Rigging for Mixamo"
+  };
+  return `${messages[status] || "Processing"} (${progress}% complete)`;
+}
+async function runServer(apiKey, baseUrl) {
+  const server = createServer(apiKey, baseUrl);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.on("SIGINT", async () => {
+    await server.close();
+    process.exit(0);
+  });
+}
+
+export {
+  createServer,
+  runServer
+};