ottoport 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# OttoPort
+
+**One API for every model.** A unified, OpenAI-compatible gateway that routes
+LLM, image, video, and speech generation through a single surface. Calls are
+dispatched through Provider Adapters, so the same public model can use an
+official API, a reseller, or a backup provider without changing the client
+contract.
+
+Design language is shared with Ottofy: Inter + Space Grotesk, lime-on-slate
+brand, soft shadows, hairline borders.
+
+## Stack
+
+- **Next.js 14** (App Router) + TypeScript
+- **Tailwind CSS** + daisyui (`ottoport` theme)
+- **Supabase** — auth, accounts, API keys, usage ledger
+- **Stripe** — prepaid credits / plans
+- Provider SDKs: `openai`, `@anthropic-ai/sdk`
+
+## Unified API
+
+Base URL: `/api/v1` · Auth: `Authorization: Bearer <key>`
+
+| Endpoint | Modality | Notes |
+| --- | --- | --- |
+| `POST /v1/chat/completions` | LLM | OpenAI-compatible, streaming supported. Routes GPT → OpenAI, Claude → Anthropic. |
+| `POST /v1/images/generations` | Image | `{ model, prompt, size?, n?, image_url? }` → `{ data: [{ url }] }`. |
+| `POST /v1/videos/generations` | Video | Submits `{ model, prompt, duration?, aspect_ratio?, webhook_url?, webhook_secret? }` and returns `202` with an OttoPort job ID. |
+| `GET /v1/videos/generations` | Video | Lists the authenticated project's persisted video generation history. |
+| `GET /v1/videos/generations/:id` | Video | Fetches the latest persisted and provider status. |
+| `POST /v1/videos/generations/:id/webhook` | Video | Retries a terminal job's webhook delivery. |
+| `POST /v1/audio/speech` | Speech | `{ model, input, voice?, format? }`; directly calls OpenAI, ElevenLabs, or Google. |
+| `GET  /v1/models` | — | Catalog with pricing + modality. |
+
+The gateway is the heart of the product:
+
+```
+app/api/v1/*            route handlers (thin)
+libs/gateway/
+  registry.ts           model catalog — single source of truth
+  router.ts             dispatch by model → Provider Adapter
+  auth.ts               API-key verification (+ dev escape hatch)
+  types.ts              normalized request/response shapes
+  providers/
+    index.ts            adapter registry + model route policy + fallback
+    openrouter.ts       unified LLM transport (except Kimi)
+    moonshot.ts         official Kimi chat API
+    openai.ts           official OpenAI image API
+    google.ts           official Gemini image API
+    video.ts            official Veo / Kling / Volcengine video APIs
+    modelark.ts         official Seedance 2.0 / Seedream 5.0 APIs
+    atlascloud.ts       optional Atlas Cloud transport for Seedance / Seedream
+    legnext.ts          Midjourney image generation via Legnext
+    audio.ts            official OpenAI / ElevenLabs / Google speech APIs
+```
+
+**Adding a model** is a one-line entry in `libs/gateway/registry.ts`. The
+model's `provider` remains its original vendor; runtime transport selection is
+separate. Configure model-specific transport routes and fallbacks in
+`libs/gateway/provider-config.ts`.
+For synchronous requests, routes are tried in order on provider failures. Video
+jobs persist their chosen route so later status polling always reaches the API
+that owns the upstream job ID.
+
+## Getting started
+
+```bash
+cp .env.example .env.local   # add OpenRouter and official media-provider keys
+npm install
+npm run dev                  # http://localhost:3014
+```
+
+The landing-page playground requires a Supabase session. Run
+[`sql/schema.sql`](sql/schema.sql), then [`sql/billing-wallet-migration.sql`](sql/billing-wallet-migration.sql)
+and [`sql/projects-migration.sql`](sql/projects-migration.sql), then [`sql/wallet-holds-migration.sql`](sql/wallet-holds-migration.sql)
+in the Supabase SQL editor, configure the
+three Supabase environment variables from `.env.example`, then sign in with
+email magic link or Google. Every new account receives the $5 free balance
+defined by the `accounts.credits_cents` default.
+
+### Async video jobs and webhooks
+
+Run [`sql/generation-jobs-migration.sql`](sql/generation-jobs-migration.sql), then
+[`sql/generation-queue-migration.sql`](sql/generation-queue-migration.sql), then
+[`sql/account-concurrency-limits-migration.sql`](sql/account-concurrency-limits-migration.sql), after the project migration.
+Video submissions are persisted and queued, so the returned job ID can be queried after a process restart. Add an HTTPS
+`webhook_url` and a caller-held `webhook_secret` to receive a signed `video.completed` or `video.failed` event.
+The signature header is `x-ottoport-signature` and uses `HMAC-SHA256(secret, "timestamp.payload")`.
+
+Set `GENERATION_JOBS_CRON_SECRET`, then configure a trusted scheduler to call
+`GET /api/internal/generation-jobs/dispatch` every minute with `Authorization: Bearer <secret>`.
+The dispatcher atomically leases queued jobs, limits in-flight jobs per account and provider, retries provider
+failures with exponential backoff, and sends terminal webhooks even when the API client is no longer polling.
+
+### Dynamic account concurrency
+
+Video concurrency is evaluated per account at the moment a job is claimed.
+`concurrency_limit_tiers` maps successful paid cash top-ups in the current UTC
+month to capacities; `account_concurrency_overrides` provides expiring
+per-account adjustments. Update either table in Supabase to change capacity
+without deploying. The migration seeds starter, growth, scale, and enterprise
+defaults; treat their thresholds and limits as product configuration.
+
+For example, to temporarily grant one account five in-flight video jobs for a
+week, upsert `account_concurrency_overrides` with `video_concurrency = 5` and
+an `expires_at` timestamp. The next worker claim uses that value immediately.
+
+### Request reservations and idempotency
+
+Chat and video calls require an `Idempotency-Key` request header. OttoPort atomically reserves the worst-case
+cost before submitting upstream, then settles the reservation from actual usage. Reuse the same key only when
+retrying the identical request; a new key represents a new billable generation. Configure the gateway caps in
+`.env.example` before production traffic.
+
+### Stripe prepaid wallet
+
+Set `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`, and `NEXT_PUBLIC_APP_URL`.
+The required billing migration adds paid-vs-bonus
+balances, a tamper-resistant wallet ledger, saved payment methods, and
+automatic top-up settings.
+
+For an environment where `billing-wallet-migration.sql` was already applied,
+run [`sql/auto-topup-safety-migration.sql`](sql/auto-topup-safety-migration.sql)
+as well. Then configure a Stripe webhook for:
+
+- `checkout.session.completed`
+- `checkout.session.async_payment_succeeded`
+- `payment_intent.succeeded`
+
+pointing to `https://your-domain/api/billing/webhook`. The dashboard creates a
+one-time Checkout Session (not a subscription). Users can also save a card and
+enable automatic top-up after explicit consent. Credits are added only after
+the webhook verifies Stripe's raw-body signature and records the Checkout
+Session or PaymentIntent ID, so webhook retries cannot duplicate a top-up. Use
+Stripe CLI during local testing to forward events to
+`http://localhost:3014/api/billing/webhook`.
+
+## Access surfaces
+
+The `/api/v1` gateway is the product; every other surface is a thin client over
+it. Point them at a running gateway with two env vars: `OTTOPORT_BASE_URL` and
+`OTTOPORT_API_KEY` (the `op-…` key, or `OTTOPORT_KEY_SECRET` in dev).
+
+- **HTTP** — OpenAI-compatible. Point any OpenAI SDK's `baseURL` at
+  `${OTTOPORT_BASE_URL}/api/v1`.
+- **CLI** — [`cli/ottoport.mjs`](cli/ottoport.mjs), zero-dependency (Node 20+).
+  `npm run cli -- models` · `chat` · `image` · `video` · `speech` · `music`. Installs as the
+  `ottoport` bin. Streams chat, `--out` downloads image/video results.
+- **MCP** — [`mcp/server.mjs`](mcp/server.mjs), a dependency-free stdio server
+  exposing `ottoport_list_models`, `ottoport_chat`, `ottoport_generate_image`,
+  `ottoport_generate_video`, `ottoport_generate_speech`, and `ottoport_generate_music`. Register with
+  `claude mcp add ottoport -- node $PWD/mcp/server.mjs`.
+- **Skill** — [`skills/ottoport/SKILL.md`](skills/ottoport/SKILL.md) teaches an
+  agent to drive OttoPort via the CLI/MCP.
+
+Shared TS client for embedding in your own code: [`libs/client.ts`](libs/client.ts).
+
+## What's wired vs. stubbed
+
+- ✅ Landing page, docs, playground, model catalog, unified gateway + adapters
+- ✅ CLI, MCP server, and Skill — all thin clients over `/api/v1`
+- ✅ Supabase sign-in requirement + metered landing-page playground (schema in `sql/schema.sql`)
+- ✅ Stripe Checkout top-ups with verified, idempotent webhook crediting
+- ✅ Hashed `api_keys` lookup in `libs/gateway/auth.ts` for the public `/api/v1` gateway
+- 🔲 Dashboard key management UI
+
+See the SQL migrations for the accounts / workspaces (projects) / api_keys / usage_events tables and RLS.

package/cli/ottoport.mjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// ── OttoPort CLI ─────────────────────────────────────────────────────
+// One command for every model. A thin, dependency-free client over the
+// unified /api/v1 gateway — the same HTTP surface an external customer uses.
+//
+//   ottoport models [--modality chat|image|video]
+//   ottoport chat   "prompt" [--model claude-sonnet-5] [--system "..."] [--no-stream]
+//   ottoport image  "prompt" [--model gpt-image-2] [--size 1024x1024] [--out img.png]
+//   ottoport video  "prompt" [--model kling-3.0] [--duration 5] [--out clip.mp4]
+//   ottoport speech "text" [--model gpt-4o-mini-tts] [--voice alloy] [--out speech.mp3]
+//   ottoport music  "prompt" [--model suno-v5] [--duration 15] [--out song.mp3]
+//   ottoport mcp
+//
+// Config (flags override env):
+//   OTTOPORT_API_KEY   your op-… key (or the dev OTTOPORT_KEY_SECRET)
+//   OTTOPORT_BASE_URL  gateway base URL (default http://localhost:3014)
+
+import { writeFile } from "node:fs/promises";
+
+const BASE = "http://localhost:3014";
+
+// ── arg parsing ──────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      if (key.startsWith("no-")) {
+        flags[key.slice(3)] = false;
+      } else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+        flags[key] = argv[++i];
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}
+
+function config(flags) {
+  const baseUrl = (flags.url || process.env.OTTOPORT_BASE_URL || process.env.NEXT_PUBLIC_APP_URL || BASE).replace(/\/+$/, "");
+  const apiKey = flags.key || process.env.OTTOPORT_API_KEY || process.env.OTTOPORT_KEY_SECRET;
+  return { baseUrl, apiKey };
+}
+
+function headers(apiKey, json = true) {
+  const h = {};
+  if (json) h["content-type"] = "application/json";
+  if (apiKey) h["authorization"] = `Bearer ${apiKey}`;
+  return h;
+}
+
+function die(msg, code = 1) {
+  process.stderr.write(`ottoport: ${msg}\n`);
+  process.exit(code);
+}
+
+async function readError(res) {
+  try {
+    const body = await res.json();
+    if (body?.error?.message) return `${body.error.message} (${body.error.code ?? res.status})`;
+  } catch {}
+  return `${res.status} ${res.statusText}`;
+}
+
+// ── commands ─────────────────────────────────────────────────────────
+async function cmdModels(flags) {
+  const { baseUrl, apiKey } = config(flags);
+  const qs = flags.modality ? `?modality=${encodeURIComponent(flags.modality)}` : "";
+  const res = await fetch(`${baseUrl}/api/v1/models${qs}`, { headers: headers(apiKey, false) });
+  if (!res.ok) die(await readError(res));
+  const { data } = await res.json();
+  if (flags.json) return console.log(JSON.stringify(data, null, 2));
+  const pad = (s, n) => String(s).padEnd(n);
+  console.log(pad("ID", 20) + pad("MODALITY", 10) + pad("PROVIDER", 12) + "PRICING");
+  for (const m of data) {
+    const price = Object.entries(m.pricing ?? {}).map(([k, v]) => `${k}=$${v}`).join(" ");
+    console.log(pad(m.id, 20) + pad(m.modality, 10) + pad(m.owned_by, 12) + price);
+  }
+}
+
+async function cmdChat(prompt, flags) {
+  if (!prompt) die("chat requires a prompt: ottoport chat \"hello\"");
+  const { baseUrl, apiKey } = config(flags);
+  const messages = [];
+  if (flags.system) messages.push({ role: "system", content: flags.system });
+  messages.push({ role: "user", content: prompt });
+
+  const stream = flags.stream !== false;
+  const body = {
+    model: flags.model || "claude-sonnet-5",
+    messages,
+    stream,
+    ...(flags.temperature ? { temperature: Number(flags.temperature) } : {}),
+    ...(flags["max-tokens"] ? { max_tokens: Number(flags["max-tokens"]) } : {}),
+  };
+
+  const res = await fetch(`${baseUrl}/api/v1/chat/completions`, {
+    method: "POST",
+    headers: { ...headers(apiKey), "idempotency-key": crypto.randomUUID() },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) die(await readError(res));
+
+  if (!stream) {
+    const json = await res.json();
+    console.log(json?.choices?.[0]?.message?.content ?? "");
+    return;
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+    for (const line of lines) {
+      const t = line.trim();
+      if (!t.startsWith("data:")) continue;
+      const payload = t.slice(5).trim();
+      if (payload === "[DONE]") {
+        process.stdout.write("\n");
+        return;
+      }
+      try {
+        const delta = JSON.parse(payload)?.choices?.[0]?.delta?.content;
+        if (delta) process.stdout.write(delta);
+      } catch {}
+    }
+  }
+  process.stdout.write("\n");
+}
+
+async function download(url, out) {
+  const res = await fetch(url);
+  if (!res.ok) die(`could not download ${url}: ${res.status}`);
+  const buf = Buffer.from(await res.arrayBuffer());
+  await writeFile(out, buf);
+  console.error(`saved → ${out} (${buf.length} bytes)`);
+}
+
+async function cmdImage(prompt, flags) {
+  if (!prompt) die("image requires a prompt: ottoport image \"a red fox\"");
+  const { baseUrl, apiKey } = config(flags);
+  const body = {
+    model: flags.model || "gpt-image-2",
+    prompt,
+    ...(flags.size ? { size: flags.size } : {}),
+    ...(flags.n ? { n: Number(flags.n) } : {}),
+    ...(flags.image ? { image_url: flags.image } : {}),
+  };
+  const res = await fetch(`${baseUrl}/api/v1/images/generations`, {
+    method: "POST",
+    headers: { ...headers(apiKey), "idempotency-key": crypto.randomUUID() },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) die(await readError(res));
+  const json = await res.json();
+  const urls = (json.data ?? []).map((d) => d.url).filter(Boolean);
+  urls.forEach((u) => console.log(u));
+  if (flags.out && urls[0]) await download(urls[0], flags.out);
+}
+
+async function cmdVideo(prompt, flags) {
+  if (!prompt) die("video requires a prompt: ottoport video \"a drone shot\"");
+  const { baseUrl, apiKey } = config(flags);
+  const body = {
+    model: flags.model || "kling-3.0",
+    prompt,
+    ...(flags.duration ? { duration: Number(flags.duration) } : {}),
+    ...(flags["aspect-ratio"] ? { aspect_ratio: flags["aspect-ratio"] } : {}),
+    ...(flags.image ? { image_url: flags.image } : {}),
+  };
+  console.error("submitting video job (this can take a minute)…");
+  const res = await fetch(`${baseUrl}/api/v1/videos/generations`, {
+    method: "POST",
+    headers: { ...headers(apiKey), "idempotency-key": crypto.randomUUID() },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) die(await readError(res));
+  let job = await res.json();
+  if (job.status === "failed") die(job.error || "video generation failed", 2);
+  if (!flags["no-wait"]) {
+    process.stderr.write(`job ${job.id} accepted; waiting for completion…\n`);
+    while (job.status === "queued" || job.status === "processing") {
+      await new Promise((resolve) => setTimeout(resolve, 3_000));
+      const status = await fetch(`${baseUrl}/api/v1/videos/generations/${encodeURIComponent(job.id)}`, { headers: headers(apiKey, false) });
+      if (!status.ok) die(await readError(status));
+      job = await status.json();
+    }
+  }
+  if (job.status === "failed") die(job.error || "video generation failed", 2);
+  const url = job.data?.[0]?.url;
+  if (url) {
+    console.log(url);
+    if (flags.out) await download(url, flags.out);
+  } else {
+    console.log(JSON.stringify(job, null, 2));
+  }
+}
+
+async function cmdAudio(kind, prompt, flags) {
+  if (!prompt) die(`${kind} requires a prompt: ottoport ${kind} "hello"`);
+  const { baseUrl, apiKey } = config(flags);
+  const body = {
+    model: flags.model || (kind === "speech" ? "gpt-4o-mini-tts" : "suno-v5"),
+    prompt,
+    ...(flags.voice ? { voice: flags.voice } : {}),
+    ...(flags.duration ? { duration: Number(flags.duration) } : {}),
+    ...(flags.format ? { format: flags.format } : {}),
+  };
+  const path = kind === "speech" ? "audio/speech" : "audio/music";
+  const res = await fetch(`${baseUrl}/api/v1/${path}`, {
+    method: "POST",
+    headers: headers(apiKey),
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) die(await readError(res));
+  const json = await res.json();
+  const item = json.data?.[0];
+  if (!item) die("no audio returned", 2);
+  if (item.url) console.log(item.url);
+  if (flags.out) {
+    if (item.b64_json) {
+      const bytes = Buffer.from(item.b64_json, "base64");
+      await writeFile(flags.out, bytes);
+      console.error(`saved → ${flags.out} (${bytes.length} bytes)`);
+    } else if (item.url) {
+      await download(item.url, flags.out);
+    }
+  }
+}
+
+const HELP = `OttoPort — one command for every model.
+
+Usage:
+  ottoport models [--modality chat|image|video|tts|music] [--json]
+  ottoport chat  "<prompt>" [--model claude-sonnet-5] [--system "..."] [--no-stream]
+                            [--temperature 0.7] [--max-tokens 512]
+  ottoport image "<prompt>" [--model gpt-image-2] [--size 1024x1024] [--n 1]
+                            [--image <url>] [--out file.png]
+  ottoport video "<prompt>" [--model kling-3.0] [--duration 5]
+                            [--aspect-ratio 16:9] [--image <url>] [--out clip.mp4]
+  ottoport speech "<text>" [--model gpt-4o-mini-tts] [--voice alloy] [--format mp3] [--out speech.mp3]
+  ottoport music  "<prompt>" [--model suno-v5] [--duration 15] [--format mp3] [--out song.mp3]
+  ottoport mcp
+
+Global flags:
+  --url <base>   gateway base URL       (env OTTOPORT_BASE_URL)
+  --key <key>    OttoPort API key       (env OTTOPORT_API_KEY)
+
+Examples:
+  export OTTOPORT_API_KEY=op-... OTTOPORT_BASE_URL=https://ottoport.dev
+  ottoport models --modality image
+  ottoport chat "explain MCP in one line" --model claude-haiku-4.5
+  ottoport image "isometric city at dusk" --model gpt-image-2 --out city.png
+  ottoport video "cinematic product reveal" --model seedance-2.0-fast
+  ottoport speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
+  ottoport music "lo-fi focus beat" --duration 20 --out focus.mp3
+  ottoport mcp
+`;
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const [command, ...rest] = positional;
+  const prompt = rest.join(" ");
+  try {
+    switch (command) {
+      case "models": return await cmdModels(flags);
+      case "chat": return await cmdChat(prompt, flags);
+      case "image": return await cmdImage(prompt, flags);
+      case "video": return await cmdVideo(prompt, flags);
+      case "speech": return await cmdAudio("speech", prompt, flags);
+      case "music": return await cmdAudio("music", prompt, flags);
+      case "mcp": return await import(new URL("../mcp/server.mjs", import.meta.url));
+      case undefined:
+      case "help":
+      case "--help":
+      case "-h": return void process.stdout.write(HELP);
+      default: die(`unknown command "${command}". Run \`ottoport help\`.`);
+    }
+  } catch (err) {
+    die(err?.message || String(err));
+  }
+}
+
+main();

package/mcp/server.mjs

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+// ── OttoPort MCP server ──────────────────────────────────────────────
+// Exposes the unified OttoPort gateway as Model Context Protocol tools so any
+// MCP client (Claude Desktop, Claude Code, Cursor, …) can call every model
+// through one surface. Dependency-free: implements the stdio JSON-RPC 2.0
+// transport directly (newline-delimited messages).
+//
+// Config via env:
+//   OTTOPORT_API_KEY   your op-… key (or the dev OTTOPORT_KEY_SECRET)
+//   OTTOPORT_BASE_URL  gateway base URL (default http://localhost:3014)
+//
+// Register with Claude Code:
+//   claude mcp add ottoport -- node /abs/path/to/mcp/server.mjs
+
+import { createInterface } from "node:readline";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const BASE = (process.env.OTTOPORT_BASE_URL || process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3014").replace(/\/+$/, "");
+const KEY = process.env.OTTOPORT_API_KEY || process.env.OTTOPORT_KEY_SECRET;
+
+function headers(json = true) {
+  const h = {};
+  if (json) h["content-type"] = "application/json";
+  if (KEY) h["authorization"] = `Bearer ${KEY}`;
+  return h;
+}
+
+async function gwError(res) {
+  try {
+    const body = await res.json();
+    if (body?.error?.message) return `${body.error.message} (${body.error.code ?? res.status})`;
+  } catch {}
+  return `${res.status} ${res.statusText}`;
+}
+
+// ── tool implementations ─────────────────────────────────────────────
+async function listModels({ modality } = {}) {
+  const qs = modality ? `?modality=${encodeURIComponent(modality)}` : "";
+  const res = await fetch(`${BASE}/api/v1/models${qs}`, { headers: headers(false) });
+  if (!res.ok) throw new Error(await gwError(res));
+  const { data } = await res.json();
+  return data
+    .map((m) => {
+      const price = Object.entries(m.pricing ?? {}).map(([k, v]) => `${k}=$${v}`).join(" ");
+      return `${m.id} — ${m.display_name} [${m.modality}, ${m.owned_by}]${price ? " · " + price : ""}`;
+    })
+    .join("\n");
+}
+
+async function chat({ prompt, model, system, temperature, max_tokens }) {
+  if (!prompt) throw new Error("`prompt` is required");
+  const messages = [];
+  if (system) messages.push({ role: "system", content: system });
+  messages.push({ role: "user", content: prompt });
+  const res = await fetch(`${BASE}/api/v1/chat/completions`, {
+    method: "POST",
+    headers: { ...headers(), "idempotency-key": crypto.randomUUID() },
+    body: JSON.stringify({
+      model: model || "claude-sonnet-5",
+      messages,
+      stream: false,
+      ...(temperature != null ? { temperature } : {}),
+      ...(max_tokens != null ? { max_tokens } : {}),
+    }),
+  });
+  if (!res.ok) throw new Error(await gwError(res));
+  const json = await res.json();
+  return json?.choices?.[0]?.message?.content ?? "";
+}
+
+async function generateImage({ prompt, model, size, n, image_url }) {
+  if (!prompt) throw new Error("`prompt` is required");
+  const res = await fetch(`${BASE}/api/v1/images/generations`, {
+    method: "POST",
+    headers: { ...headers(), "idempotency-key": crypto.randomUUID() },
+    body: JSON.stringify({
+      model: model || "gpt-image-2",
+      prompt,
+      ...(size ? { size } : {}),
+      ...(n ? { n } : {}),
+      ...(image_url ? { image_url } : {}),
+    }),
+  });
+  if (!res.ok) throw new Error(await gwError(res));
+  const json = await res.json();
+  const urls = (json.data ?? []).map((d) => d.url).filter(Boolean);
+  return urls.length ? urls.join("\n") : "(no image returned)";
+}
+
+async function generateVideo({ prompt, model, duration, aspect_ratio, image_url }) {
+  if (!prompt) throw new Error("`prompt` is required");
+  const res = await fetch(`${BASE}/api/v1/videos/generations`, {
+    method: "POST",
+    headers: { ...headers(), "idempotency-key": crypto.randomUUID() },
+    body: JSON.stringify({
+      model: model || "kling-3.0",
+      prompt,
+      ...(duration ? { duration } : {}),
+      ...(aspect_ratio ? { aspect_ratio } : {}),
+      ...(image_url ? { image_url } : {}),
+    }),
+  });
+  if (!res.ok) throw new Error(await gwError(res));
+  let job = await res.json();
+  if (job.status === "failed") throw new Error(job.error || "video generation failed");
+  // The public video endpoint is deliberately asynchronous. MCP tools should
+  // still fulfil their promise of returning usable output, so wait for the
+  // job rather than returning a queued-job JSON blob to the agent.
+  const deadline = Date.now() + 10 * 60_000;
+  while (job.status === "queued" || job.status === "processing") {
+    if (Date.now() >= deadline) return `Video job ${job.id} is still processing. Poll /api/v1/videos/generations/${job.id} for its result.`;
+    await new Promise((resolve) => setTimeout(resolve, 3_000));
+    const status = await fetch(`${BASE}/api/v1/videos/generations/${encodeURIComponent(job.id)}`, { headers: headers(false) });
+    if (!status.ok) throw new Error(await gwError(status));
+    job = await status.json();
+  }
+  if (job.status === "failed") throw new Error(job.error || "video generation failed");
+  const url = job.data?.[0]?.url;
+  return url || JSON.stringify(job);
+}
+
+async function generateAudio(kind, { prompt, model, voice, duration, format }) {
+  if (!prompt) throw new Error("`prompt` is required");
+  const res = await fetch(`${BASE}/api/v1/audio/${kind === "tts" ? "speech" : "music"}`, {
+    method: "POST",
+    headers: headers(),
+    body: JSON.stringify({
+      model: model || (kind === "tts" ? "gpt-4o-mini-tts" : "suno-v5"),
+      prompt,
+      ...(voice ? { voice } : {}),
+      ...(duration ? { duration } : {}),
+      ...(format ? { format } : {}),
+    }),
+  });
+  if (!res.ok) throw new Error(await gwError(res));
+  const json = await res.json();
+  const audio = json.data?.[0];
+  if (!audio) return "(no audio returned)";
+  return audio.url || (audio.b64_json ? `data:audio;base64,${audio.b64_json}` : "(no audio returned)");
+}
+
+// ── tool registry ────────────────────────────────────────────────────
+const TOOLS = [
+  {
+    name: "ottoport_list_models",
+    description: "List the models OttoPort exposes, with modality, provider, and pricing. Optionally filter by modality.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        modality: { type: "string", enum: ["chat", "image", "video", "tts", "music"], description: "Filter to one modality." },
+      },
+    },
+    handler: listModels,
+  },
+  {
+    name: "ottoport_chat",
+    description: "Chat completion through any OttoPort LLM (GPT, Claude, Gemini, …). Returns the assistant's reply text.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "The user message." },
+        model: { type: "string", description: "Model id, e.g. gpt-5.5, claude-sonnet-5, gemini-3.5-flash. Default claude-sonnet-5." },
+        system: { type: "string", description: "Optional system prompt." },
+        temperature: { type: "number" },
+        max_tokens: { type: "number" },
+      },
+      required: ["prompt"],
+    },
+    handler: chat,
+  },
+  {
+    name: "ottoport_generate_image",
+    description: "Generate an image from a text prompt through an OttoPort image model (GPT Image, Nano Banana, …). Returns image URL(s).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string" },
+        model: { type: "string", description: "Model id, e.g. gpt-image-2, nano-banana-2, nano-banana-pro. Default gpt-image-2." },
+        size: { type: "string", description: 'e.g. "1024x1024" or "16:9".' },
+        n: { type: "number" },
+        image_url: { type: "string", description: "Source image URL for image-to-image / edits." },
+      },
+      required: ["prompt"],
+    },
+    handler: generateImage,
+  },
+  {
+    name: "ottoport_generate_video",
+    description: "Generate a video from a text prompt (or an image) through an OttoPort video model (Veo, Kling, Seedance, …). Blocks on the queue and returns a video URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string" },
+        model: { type: "string", description: "Model id, e.g. veo-3.1, kling-3.0, seedance-2.0-fast. Default kling-3.0." },
+        duration: { type: "number", description: "Seconds." },
+        aspect_ratio: { type: "string", description: 'e.g. "16:9".' },
+        image_url: { type: "string", description: "Source image URL for image-to-video." },
+      },
+      required: ["prompt"],
+    },
+    handler: generateVideo,
+  },
+  {
+    name: "ottoport_generate_speech",
+    description: "Convert text to speech through an OttoPort TTS model. Returns an audio URL or data URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Text to synthesize." },
+        model: { type: "string", description: "TTS model id. Default gpt-4o-mini-tts." },
+        voice: { type: "string", description: "Optional provider voice id." },
+        format: { type: "string", description: 'e.g. "mp3" or "wav".' },
+      },
+      required: ["prompt"],
+    },
+    handler: (args) => generateAudio("tts", args),
+  },
+  {
+    name: "ottoport_generate_music",
+    description: "Generate music from a prompt through an OttoPort music model. Returns an audio URL or data URL.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Music-generation prompt." },
+        model: { type: "string", description: "Music model id. Default suno-v5." },
+        duration: { type: "number", description: "Requested duration in seconds." },
+        format: { type: "string", description: 'e.g. "mp3" or "wav".' },
+      },
+      required: ["prompt"],
+    },
+    handler: (args) => generateAudio("music", args),
+  },
+];
+
+const TOOL_MAP = new Map(TOOLS.map((t) => [t.name, t]));
+
+// ── JSON-RPC plumbing ────────────────────────────────────────────────
+function send(msg) {
+  process.stdout.write(JSON.stringify(msg) + "\n");
+}
+
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result });
+}
+
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+
+  switch (method) {
+    case "initialize":
+      return reply(id, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: { tools: {} },
+        serverInfo: { name: "ottoport", version: "0.1.0" },
+      });
+
+    case "notifications/initialized":
+    case "notifications/cancelled":
+      return; // notifications: no response
+
+    case "ping":
+      return reply(id, {});
+
+    case "tools/list":
+      return reply(id, {
+        tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+      });
+
+    case "tools/call": {
+      const tool = TOOL_MAP.get(params?.name);
+      if (!tool) return replyError(id, -32602, `Unknown tool: ${params?.name}`);
+      try {
+        const text = await tool.handler(params.arguments ?? {});
+        return reply(id, { content: [{ type: "text", text: String(text) }] });
+      } catch (err) {
+        // Tool errors are reported in-band so the model can react.
+        return reply(id, {
+          content: [{ type: "text", text: `Error: ${err?.message || String(err)}` }],
+          isError: true,
+        });
+      }
+    }
+
+    default:
+      if (id !== undefined) replyError(id, -32601, `Method not found: ${method}`);
+  }
+}
+
+const rl = createInterface({ input: process.stdin });
+rl.on("line", (line) => {
+  const text = line.trim();
+  if (!text) return;
+  let msg;
+  try {
+    msg = JSON.parse(text);
+  } catch {
+    return; // ignore non-JSON lines
+  }
+  Promise.resolve(handle(msg)).catch((err) => {
+    if (msg?.id !== undefined) replyError(msg.id, -32603, err?.message || "internal error");
+  });
+});
+
+process.stderr.write(`ottoport MCP server ready → ${BASE}${KEY ? "" : " (no OTTOPORT_API_KEY set)"}\n`);

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "ottoport",
+  "version": "0.1.0",
+  "description": "CLI and MCP server for OttoPort — one OpenAI-compatible API for every LLM, image, video, and speech model.",
+  "homepage": "https://ottoport.ai",
+  "keywords": [
+    "ai",
+    "llm",
+    "api-gateway",
+    "openai-compatible",
+    "image-generation",
+    "video-generation",
+    "text-to-speech",
+    "mcp",
+    "mcp-server",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "ottoport": "cli/ottoport.mjs"
+  },
+  "files": [
+    "cli",
+    "mcp",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "next dev -p 3014",
+    "build": "next build",
+    "start": "next start -p 3014",
+    "lint": "next lint",
+    "cli": "node cli/ottoport.mjs",
+    "mcp": "node mcp/server.mjs"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.65.0",
+    "@supabase/ssr": "^0.10.2",
+    "@supabase/supabase-js": "^2.43.0",
+    "@tailwindcss/typography": "^0.5.13",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.395.0",
+    "next": "^14.2.0",
+    "openai": "^4.104.0",
+    "react": "^18.3.0",
+    "react-dom": "^18.3.0",
+    "sonner": "^1.5.0",
+    "stripe": "^13.11.0",
+    "swr": "^2.2.5",
+    "tailwind-merge": "^2.3.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "autoprefixer": "^10.4.19",
+    "daisyui": "^4.12.0",
+    "eslint": "^8.57.0",
+    "eslint-config-next": "^14.2.0",
+    "postcss": "^8.4.38",
+    "tailwindcss": "^3.4.4",
+    "typescript": "^5.4.5"
+  }
+}