@marlinjai/studio-mcp 0.1.0

package/examples/claude-code.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Register the Lumitra Studio MCP server with Claude Code.
+# Pick ONE of the blocks below. Never paste the key into a chat; set it in your
+# shell (or let cc.sh inject LUMITRA_STUDIO_SERVICE_TOKEN) and pass it by reference.
+set -euo pipefail
+
+# 1) stdio via npx (published package), key from the current shell
+claude mcp add lumitra-studio \
+  --env "LUMITRA_STUDIO_API_KEY=${LUMITRA_STUDIO_API_KEY:-${LUMITRA_STUDIO_SERVICE_TOKEN:?set LUMITRA_STUDIO_API_KEY}}" \
+  -- npx -y @marlinjai/studio-mcp
+
+# 2) stdio from a local monorepo build
+# pnpm --filter @marlinjai/studio-mcp build
+# claude mcp add lumitra-studio -- node "$(pwd)/packages/studio-mcp/dist/cli.js"
+
+# 3) Streamable HTTP (server started elsewhere with: studio-mcp --http --port 3939)
+# claude mcp add --transport http lumitra-studio http://127.0.0.1:3939/mcp

package/examples/cursor-mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "lumitra-studio": {
+      "command": "npx",
+      "args": ["-y", "@marlinjai/studio-mcp"],
+      "env": {
+        "LUMITRA_STUDIO_API_KEY": "sk_live_REPLACE_ME",
+        "LUMITRA_STUDIO_BASE_URL": "https://studio.lumitra.co"
+      }
+    }
+  }
+}

package/examples/smoke-http.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Smoke test for the Streamable HTTP transport: starts the server on a random
+// port with a throwaway key, lists tools over JSON-RPC, and exits non-zero if
+// the tool list does not match. Hits no real Studio endpoint.
+//
+//   node examples/smoke-http.mjs
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cli = join(here, '..', 'dist', 'cli.js');
+
+const child = spawn(process.execPath, [cli, '--http', '--port', '0'], {
+  env: { ...process.env, LUMITRA_STUDIO_API_KEY: 'smoke-test-key-not-real' },
+  stdio: ['ignore', 'ignore', 'pipe'],
+});
+
+const port = await new Promise((resolve, reject) => {
+  let buf = '';
+  child.stderr.on('data', (d) => {
+    buf += String(d);
+    const m = buf.match(/http:\/\/127\.0\.0\.1:(\d+)\/mcp/);
+    if (m) resolve(Number(m[1]));
+  });
+  child.on('exit', (code) => reject(new Error(`server exited early (${code}): ${buf}`)));
+  setTimeout(() => reject(new Error(`server did not start: ${buf}`)), 5000);
+});
+
+try {
+  const health = await fetch(`http://127.0.0.1:${port}/healthz`).then((r) => r.json());
+  if (!health.ok) throw new Error('healthz not ok');
+
+  const init = await fetch(`http://127.0.0.1:${port}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'smoke', version: '0' } },
+    }),
+  });
+  if (!init.ok) throw new Error(`initialize -> ${init.status}: ${await init.text()}`);
+
+  const res = await fetch(`http://127.0.0.1:${port}/mcp`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }),
+  });
+  const text = await res.text();
+  // Stateless mode may answer as JSON or as a single SSE event; handle both.
+  const jsonLine = text.startsWith('event:') || text.startsWith('data:')
+    ? text.split('\n').find((l) => l.startsWith('data:')).slice(5).trim()
+    : text;
+  const body = JSON.parse(jsonLine);
+  const names = body.result.tools.map((t) => t.name);
+  const expected = [
+    'studio_list_projects', 'studio_generate_image', 'studio_get_job', 'studio_list_characters',
+    'studio_get_character', 'studio_create_character', 'studio_mint_character', 'studio_create_brand',
+    'studio_upload_brand_reference', 'studio_run_workflow', 'studio_get_run', 'studio_get_run_output',
+    'studio_replace_character_in_video', 'studio_get_spend',
+    'studio_workflow_describe', 'studio_workflow_get', 'studio_workflow_create', 'studio_workflow_apply',
+    'studio_workflow_validate',
+  ];
+  if (JSON.stringify(names) !== JSON.stringify(expected)) {
+    throw new Error(`tool list mismatch: ${names.join(', ')}`);
+  }
+  console.log(`ok: ${names.length} tools over Streamable HTTP on port ${port}`);
+} finally {
+  child.kill('SIGTERM');
+}

package/examples/workflow-character-sheet.json

@@ -0,0 +1,205 @@
+{
+  "definition": {
+    "version": {
+      "schema": 1
+    },
+    "id": "character-sheet",
+    "label": "Character Sheet (seed face -> turnaround)",
+    "params": [
+      {
+        "name": "seedPrompt",
+        "type": "string",
+        "required": true,
+        "label": "Seed face prompt"
+      },
+      {
+        "name": "threeQuarterPrompt",
+        "type": "string",
+        "required": true,
+        "label": "Three-quarter prompt"
+      },
+      {
+        "name": "profilePrompt",
+        "type": "string",
+        "required": true,
+        "label": "Profile prompt"
+      },
+      {
+        "name": "fullBodyPrompt",
+        "type": "string",
+        "required": true,
+        "label": "Full body prompt"
+      },
+      {
+        "name": "closeUpPrompt",
+        "type": "string",
+        "required": true,
+        "label": "Close-up prompt"
+      },
+      {
+        "name": "lightingWarmPrompt",
+        "type": "string",
+        "required": true,
+        "label": "Warm lighting prompt"
+      },
+      {
+        "name": "lightingCoolPrompt",
+        "type": "string",
+        "required": true,
+        "label": "Cool lighting prompt"
+      }
+    ],
+    "nodes": [
+      {
+        "id": "seed",
+        "task": "text-to-image",
+        "model": "fal/nano-banana-2",
+        "inputs": {
+          "prompt": {
+            "kind": "param",
+            "name": "seedPrompt"
+          },
+          "aspectRatio": {
+            "kind": "literal",
+            "value": "1:1"
+          }
+        }
+      },
+      {
+        "id": "view-three-quarter",
+        "task": "image-edit",
+        "model": "fal/nano-banana-2-edit",
+        "inputs": {
+          "prompt": {
+            "kind": "param",
+            "name": "threeQuarterPrompt"
+          },
+          "inputImages": {
+            "kind": "ref",
+            "node": "seed",
+            "path": "url",
+            "wrap": "array"
+          },
+          "aspectRatio": {
+            "kind": "literal",
+            "value": "1:1"
+          }
+        }
+      },
+      {
+        "id": "view-profile",
+        "task": "image-edit",
+        "model": "fal/nano-banana-2-edit",
+        "inputs": {
+          "prompt": {
+            "kind": "param",
+            "name": "profilePrompt"
+          },
+          "inputImages": {
+            "kind": "ref",
+            "node": "seed",
+            "path": "url",
+            "wrap": "array"
+          },
+          "aspectRatio": {
+            "kind": "literal",
+            "value": "1:1"
+          }
+        }
+      },
+      {
+        "id": "view-full-body",
+        "task": "image-edit",
+        "model": "fal/nano-banana-2-edit",
+        "inputs": {
+          "prompt": {
+            "kind": "param",
+            "name": "fullBodyPrompt"
+          },
+          "inputImages": {
+            "kind": "ref",
+            "node": "seed",
+            "path": "url",
+            "wrap": "array"
+          },
+          "aspectRatio": {
+            "kind": "literal",
+            "value": "3:4"
+          }
+        }
+      },
+      {
+        "id": "view-close-up",
+        "task": "image-edit",
+        "model": "fal/nano-banana-2-edit",
+        "inputs": {
+          "prompt": {
+            "kind": "param",
+            "name": "closeUpPrompt"
+          },
+          "inputImages": {
+            "kind": "ref",
+            "node": "seed",
+            "path": "url",
+            "wrap": "array"
+          },
+          "aspectRatio": {
+            "kind": "literal",
+            "value": "1:1"
+          }
+        }
+      },
+      {
+        "id": "view-lighting-warm",
+        "task": "image-edit",
+        "model": "fal/nano-banana-2-edit",
+        "inputs": {
+          "prompt": {
+            "kind": "param",
+            "name": "lightingWarmPrompt"
+          },
+          "inputImages": {
+            "kind": "ref",
+            "node": "seed",
+            "path": "url",
+            "wrap": "array"
+          },
+          "aspectRatio": {
+            "kind": "literal",
+            "value": "1:1"
+          }
+        }
+      },
+      {
+        "id": "view-lighting-cool",
+        "task": "image-edit",
+        "model": "fal/nano-banana-2-edit",
+        "inputs": {
+          "prompt": {
+            "kind": "param",
+            "name": "lightingCoolPrompt"
+          },
+          "inputImages": {
+            "kind": "ref",
+            "node": "seed",
+            "path": "url",
+            "wrap": "array"
+          },
+          "aspectRatio": {
+            "kind": "literal",
+            "value": "1:1"
+          }
+        }
+      }
+    ]
+  },
+  "exampleParams": {
+    "seedPrompt": "Character identity (keep identical in every view): A woman in her late 30s, short curly auburn hair, freckles, round tortoiseshell glasses, athletic build.\n\nGenerate a clean front-facing reference portrait of this character: head-and-shoulders framing, neutral expression, looking straight at the camera. Square 1:1 crop.\n\nEven, soft, neutral studio lighting.\n\nWardrobe: the character is wearing a plain heather-gray crew-neck t-shirt, unbranded, with no logos, graphics, prints, or patterns.\n\nPlain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.\n\nThis is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face.",
+    "threeQuarterPrompt": "Character identity (keep identical in every view): A woman in her late 30s, short curly auburn hair, freckles, round tortoiseshell glasses, athletic build.\n\nThree-quarter (45 degree) view: turn the head and upper body slightly to one side. Chest-up framing, square 1:1 crop. Even neutral studio lighting.\n\nWardrobe: the character is wearing a plain heather-gray crew-neck t-shirt, unbranded, with no logos, graphics, prints, or patterns.\n\nPlain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.\n\nThis is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face.",
+    "profilePrompt": "Character identity (keep identical in every view): A woman in her late 30s, short curly auburn hair, freckles, round tortoiseshell glasses, athletic build.\n\nFull side profile (90 degree) view. Chest-up framing, square 1:1 crop. Even neutral studio lighting.\n\nWardrobe: the character is wearing a plain heather-gray crew-neck t-shirt, unbranded, with no logos, graphics, prints, or patterns.\n\nPlain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.\n\nThis is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face.",
+    "fullBodyPrompt": "Character identity (keep identical in every view): A woman in her late 30s, short curly auburn hair, freckles, round tortoiseshell glasses, athletic build.\n\nFull-body head-to-toe view: the character standing in a relaxed neutral pose, facing forward. 3:4 portrait crop with the whole figure in frame. Even neutral studio lighting.\n\nWardrobe: the character is wearing a plain heather-gray crew-neck t-shirt and plain dark straight-leg trousers, unbranded, with no logos, graphics, prints, or patterns.\n\nPlain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.\n\nThis is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face.",
+    "closeUpPrompt": "Character identity (keep identical in every view): A woman in her late 30s, short curly auburn hair, freckles, round tortoiseshell glasses, athletic build.\n\nTight front-facing close-up of the face, capturing fine facial detail. Square 1:1 crop. Even neutral studio lighting.\n\nWardrobe: the character is wearing a plain heather-gray crew-neck t-shirt, unbranded, with no logos, graphics, prints, or patterns.\n\nPlain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.\n\nThis is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face.",
+    "lightingWarmPrompt": "Character identity (keep identical in every view): A woman in her late 30s, short curly auburn hair, freckles, round tortoiseshell glasses, athletic build.\n\nFront-facing head-and-shoulders portrait, square 1:1 crop, under warm golden-hour key lighting.\n\nWardrobe: the character is wearing a plain heather-gray crew-neck t-shirt, unbranded, with no logos, graphics, prints, or patterns.\n\nPlain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.\n\nThis is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face.",
+    "lightingCoolPrompt": "Character identity (keep identical in every view): A woman in her late 30s, short curly auburn hair, freckles, round tortoiseshell glasses, athletic build.\n\nFront-facing head-and-shoulders portrait, square 1:1 crop, under cool blue-toned key lighting.\n\nWardrobe: the character is wearing a plain heather-gray crew-neck t-shirt, unbranded, with no logos, graphics, prints, or patterns.\n\nPlain light-gray seamless studio background, no props, no text, no watermark, photorealistic, sharp focus.\n\nThis is the same person, same face, same identity as the reference image: keep the facial structure, features, hair, and proportions identical. Do not invent a new face."
+  }
+}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@marlinjai/studio-mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Model Context Protocol (MCP) server over the Lumitra Studio HTTP API: generate images, mint characters, run workflows, swap characters into video.",
+  "license": "MIT",
+  "author": "Marlin Jai Pohl <marlin@lumitra.co> (https://lumitra.co)",
+  "homepage": "https://studio.lumitra.co",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marlinjai/lumitra-studio-plugin.git",
+    "directory": "."
+  },
+  "bugs": {
+    "url": "https://github.com/marlinjai/lumitra-studio-plugin/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "image-generation",
+    "video-generation",
+    "character-consistency",
+    "brand",
+    "lumitra",
+    "ai-agents"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "studio-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "examples",
+    "!dist/**/*.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "node dist/cli.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.1"
+  },
+  "devDependencies": {
+    "@marlinjai/studio-core": "workspace:*",
+    "@types/node": "^20",
+    "tsup": "^8.5.0",
+    "typescript": "^5",
+    "vitest": "^4.1.5"
+  }
+}