ottoport 1.2.3 → 1.3.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "ottoport",
+  "description": "One API for every model. Call chat, image, video, speech and music models through the OttoPort gateway — as MCP tools, slash commands, or the bundled CLI.",
+  "version": "1.3.0",
+  "author": {
+    "name": "LITBOX LLC",
+    "email": "support@ottoport.ai"
+  },
+  "homepage": "https://ottoport.ai",
+  "repository": "https://github.com/Jet1217/OttoPort",
+  "license": "MIT",
+  "keywords": [
+    "ai",
+    "llm",
+    "api-gateway",
+    "openai-compatible",
+    "image-generation",
+    "video-generation",
+    "text-to-speech",
+    "mcp"
+  ]
+}

package/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "ottoport": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT:-.}/mcp/server.mjs"],
+      "env": {
+        "OTTOPORT_API_KEY": "${OTTOPORT_API_KEY}",
+        "OTTOPORT_BASE_URL": "${OTTOPORT_BASE_URL:-https://ottoport.ai}"
+      }
+    }
+  }
+}

package/README.md

@@ -1,167 +1,63 @@
-# OttoPort
+# OttoPort for Claude Code
 
-**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.
+One API for every model. This plugin bundles three things into a single
+install: the OttoPort **MCP server**, the **`ottoport` skill**, and a set of
+**slash commands** for chat, image, video, speech, and music generation.
 
-Design language is shared with Ottofy: Inter + Space Grotesk, lime-on-slate
-brand, soft shadows, hairline borders.
+## Install
 
-## Stack
+```
+/plugin marketplace add https://ottoport.ai/plugin/marketplace.json
+/plugin install ottoport@ottoport
+```
 
-- **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`
+Then set your key in the shell that launches Claude Code — the MCP server reads
+the environment it inherits, so a key exported inside a session is too late:
 
-## Unified API
+```bash
+export OTTOPORT_API_KEY=op-...          # create one at https://ottoport.ai/api-keys
+export OTTOPORT_BASE_URL=https://ottoport.ai   # optional; this is the default
+```
 
-Base URL: `/api/v1` · Auth: `Authorization: Bearer <key>`
+Run `/ottoport:setup` to confirm the key, the gateway, and the MCP tools are all
+live.
 
-| 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. |
+## Slash commands
 
-The gateway is the heart of the product:
+| Command | What it does |
+| --- | --- |
+| `/ottoport:models` | The catalog with live pricing, filterable by modality. |
+| `/ottoport:chat` | Send a prompt to any chat model (GPT, Claude, Gemini, Kimi, GLM …). |
+| `/ottoport:image` | Generate or edit an image. |
+| `/ottoport:video` | Submit a video job and wait for the URL. |
+| `/ottoport:speech` | Read text aloud, or generate music. |
+| `/ottoport:setup` | Diagnose key / gateway / MCP wiring. |
 
-```
-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
-```
+## MCP tools
+
+The bundled server exposes `ottoport_list_models`, `ottoport_chat`,
+`ottoport_generate_image`, `ottoport_generate_video`, `ottoport_generate_speech`,
+and `ottoport_generate_music`. Any agent in the session can call them directly —
+the slash commands are just convenient entry points over the same tools.
 
-**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.
+## CLI
 
-## Getting started
+The same package ships the `ottoport` CLI for terminal and CI use:
 
 ```bash
-cp .env.example .env.local   # add OpenRouter and official media-provider keys
-npm install
-npm run dev                  # http://localhost:3014
+npm install -g ottoport
+ottoport models --modality video
+ottoport image "isometric city at dusk" --out city.png
 ```
 
-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.
+## Notes
+
+- Image, video, and audio calls return **URLs**, and provider URLs expire.
+  Download anything worth keeping.
+- Video generation takes a minute or more and the call blocks until the job is
+  terminal. A retry is a second billable generation, not a resumption.
+- Requests are billed against the prepaid balance on your OttoPort account.
+
+Docs: <https://ottoport.ai/docs> · Support: support@ottoport.ai
+
+MIT © LITBOX LLC

package/cli/install.mjs

@@ -0,0 +1,169 @@
+// ── ottoport install <host> ──────────────────────────────────────────
+// Wires OttoPort into whatever agent the user actually runs. Only Claude Code
+// has a plugin format, so everywhere else the installable unit is the MCP
+// server plus — where the host understands one — the skill.
+//
+// The server is always registered as `npx -y ottoport mcp`, so the host
+// resolves it from npm rather than from a path that only exists on this
+// machine.
+
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const SKILL_SRC = join(PKG_ROOT, "skills/ottoport");
+const HOME = homedir();
+const CODEX_HOME = process.env.CODEX_HOME || join(HOME, ".codex");
+
+const COMMAND = "npx";
+const ARGS = ["-y", "ottoport", "mcp"];
+// Names forwarded from the user's environment. Writing the key itself into a
+// config file would leave an op-… secret in plain text on disk, and every host
+// below can read it from the environment instead.
+const ENV_NAMES = ["OTTOPORT_API_KEY", "OTTOPORT_BASE_URL"];
+
+let DRY = false;
+const done = [];
+const notes = [];
+
+function write(path, content) {
+  if (DRY) return void done.push(`would write ${path}`);
+  mkdirSync(dirname(path), { recursive: true });
+  if (existsSync(path)) copyFileSync(path, `${path}.bak`);  // never edit a config without a copy beside it
+  writeFileSync(path, content);
+  done.push(`wrote ${path}${existsSync(`${path}.bak`) ? " (backup: .bak)" : ""}`);
+}
+
+function installSkill(dir) {
+  const dest = join(dir, "ottoport");
+  if (!existsSync(SKILL_SRC)) {
+    notes.push(`skill not found in this package (${SKILL_SRC}) — install ottoport@1.3.0 or newer`);
+    return;
+  }
+  if (DRY) return void done.push(`would install skill → ${dest}`);
+  mkdirSync(dir, { recursive: true });
+  cpSync(SKILL_SRC, dest, { recursive: true });
+  done.push(`installed skill → ${dest}`);
+}
+
+function hostCli(bin, args) {
+  const probe = spawnSync(bin, ["--version"], { stdio: "ignore" });
+  if (probe.error) return false;
+  if (DRY) {
+    done.push(`would run: ${bin} ${args.join(" ")}`);
+    return true;
+  }
+  const run = spawnSync(bin, args, { stdio: "inherit" });
+  if (run.status !== 0) throw new Error(`${bin} ${args[0]} ${args[1]} exited ${run.status}`);
+  done.push(`registered with ${bin}`);
+  return true;
+}
+
+// ── hosts ────────────────────────────────────────────────────────────
+
+// Codex keeps MCP servers in TOML. `env_vars` forwards the named variables
+// from the environment; the sibling `[...env]` table would hard-code values.
+function codex() {
+  const path = join(CODEX_HOME, "config.toml");
+  const block =
+    `[mcp_servers.ottoport]\n` +
+    `command = "${COMMAND}"\n` +
+    `args = [${ARGS.map((a) => `"${a}"`).join(", ")}]\n` +
+    `env_vars = [${ENV_NAMES.map((n) => `"${n}"`).join(", ")}]\n`;
+
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  // Replace an existing entry in place — from its header to the next
+  // top-of-line table header — so re-running is idempotent rather than additive.
+  const existing = /^\[mcp_servers\.ottoport\][^\n]*\n(?:(?!^\[)[^\n]*\n?)*/m;
+  const next = existing.test(current)
+    ? current.replace(existing, block)
+    : (current.trimEnd() + (current.trim() ? "\n\n" : "") + block);
+  write(path, next);
+  installSkill(join(CODEX_HOME, "skills"));
+  notes.push("restart Codex to pick up the server and skill");
+}
+
+// Claude Code has a real plugin (commands included), so the MCP-only path here
+// is the fallback for someone who would rather not add the marketplace.
+function claudeCode() {
+  if (!hostCli("claude", ["mcp", "add", "ottoport", "--", COMMAND, ...ARGS])) {
+    notes.push("claude CLI not found — run: claude mcp add ottoport -- npx -y ottoport mcp");
+  }
+  installSkill(join(HOME, ".claude/skills"));
+  notes.push(
+    "for the full plugin (slash commands too):\n" +
+    "  /plugin marketplace add https://ottoport.ai/plugin/marketplace.json\n" +
+    "  /plugin install ottoport@ottoport",
+  );
+}
+
+// Hermes stores MCP servers in YAML. Editing that by hand from here would risk
+// mangling a user's config, and Hermes ships a command for exactly this.
+function hermes() {
+  // `--args` takes the rest of the line, so it has to come last.
+  if (!hostCli("hermes", ["mcp", "add", "ottoport", "--command", COMMAND, "--args", ...ARGS])) {
+    notes.push(
+      "hermes CLI not found. Add to ~/.hermes/config.yaml:\n" +
+      "  mcp_servers:\n    ottoport:\n      command: npx\n      args: [-y, ottoport, mcp]",
+    );
+  }
+  notes.push("Hermes has no skill mechanism — the MCP tools carry their own descriptions");
+}
+
+// Cursor, Windsurf and Claude Desktop all read a JSON file with the same shape.
+function jsonHost(label, path) {
+  const config = existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : {};
+  config.mcpServers = {
+    ...config.mcpServers,
+    ottoport: { command: COMMAND, args: ARGS },
+  };
+  write(path, JSON.stringify(config, null, 2) + "\n");
+  notes.push(
+    `${label} launches the server from your desktop session, which may not see a key exported in a shell. ` +
+    `If the tools report 401, add an "env" block to the ottoport entry.`,
+  );
+}
+
+const HOSTS = {
+  codex,
+  claude: claudeCode,
+  "claude-code": claudeCode,
+  hermes,
+  cursor: () => jsonHost("Cursor", join(HOME, ".cursor/mcp.json")),
+  windsurf: () => jsonHost("Windsurf", join(HOME, ".codeium/windsurf/mcp_config.json")),
+  "claude-desktop": () =>
+    jsonHost(
+      "Claude Desktop",
+      platform() === "darwin"
+        ? join(HOME, "Library/Application Support/Claude/claude_desktop_config.json")
+        : join(HOME, ".config/Claude/claude_desktop_config.json"),
+    ),
+};
+
+export function installHosts() {
+  return Object.keys(HOSTS);
+}
+
+export async function cmdInstall(host, flags) {
+  DRY = flags["dry-run"] === true || flags.n === true;
+  const run = HOSTS[host];
+  if (!run) {
+    throw new Error(
+      `unknown host "${host ?? ""}". Try one of: ${installHosts().join(", ")}`,
+    );
+  }
+
+  run();
+
+  process.stdout.write(done.map((d) => `  ${d}\n`).join("") || "  nothing to do\n");
+  if (!process.env.OTTOPORT_API_KEY && !process.env.OTTOPORT_KEY_SECRET) {
+    notes.unshift(
+      "OTTOPORT_API_KEY is not set in this environment. Export it from your shell profile " +
+      "(create a key at https://ottoport.ai/api-keys) — the server reads it at launch.",
+    );
+  }
+  if (notes.length) process.stdout.write("\n" + notes.map((n) => `note: ${n}\n`).join(""));
+}

package/cli/ottoport.mjs

@@ -10,6 +10,7 @@
 //   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
+//   ottoport install <codex|claude|hermes|cursor|windsurf|claude-desktop>
 //
 // Config (flags override env):
 //   OTTOPORT_API_KEY   your op-… key (or the dev OTTOPORT_KEY_SECRET)
@@ -251,6 +252,9 @@ Usage:
   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
+  ottoport install <host>   wire the MCP server (and skill) into an agent
+                            hosts: codex, claude, hermes, cursor, windsurf, claude-desktop
+                            [--dry-run]
 
 Global flags:
   --url <base>   gateway base URL       (env OTTOPORT_BASE_URL)
@@ -265,6 +269,7 @@ Examples:
   ottoport speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
   ottoport music "lo-fi focus beat" --duration 20 --out focus.mp3
   ottoport mcp
+  ottoport install codex
 `;
 
 async function main() {
@@ -280,6 +285,10 @@ async function main() {
       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 "install": {
+        const { cmdInstall } = await import(new URL("./install.mjs", import.meta.url));
+        return await cmdInstall(rest[0], flags);
+      }
       case undefined:
       case "help":
       case "--help":

package/commands/chat.md

@@ -0,0 +1,16 @@
+---
+description: Run a prompt through any chat model on the OttoPort gateway
+argument-hint: "<prompt> [--model <id>]"
+allowed-tools: mcp__ottoport__ottoport_chat, mcp__ottoport__ottoport_list_models
+---
+
+Send this to a model through the `ottoport_chat` MCP tool:
+
+$ARGUMENTS
+
+If the request names a model, pass it as `model`; otherwise let the tool default
+to `claude-sonnet-5`. If the named model is rejected as unknown, call
+`ottoport_list_models` with `modality: "chat"`, pick the closest real id, and say
+which one you substituted.
+
+Return the model's answer itself — do not summarize it away.

package/commands/image.md

@@ -0,0 +1,14 @@
+---
+description: Generate an image through the OttoPort gateway
+argument-hint: "<prompt> [--model <id>] [--size 1024x1024]"
+allowed-tools: mcp__ottoport__ottoport_generate_image, mcp__ottoport__ottoport_list_models, Bash(curl:*)
+---
+
+Generate an image with the `ottoport_generate_image` MCP tool.
+
+Request: $ARGUMENTS
+
+- Pass `model` only if the user named one; the tool defaults to `gpt-image-2`.
+- An edit of an existing image goes through `image_url`, not the prompt.
+- The tool returns URLs, and provider URLs expire. Print the URL, and if the
+  user asked for a file, download it to the path they named with `curl -sSL`.

package/commands/models.md

@@ -0,0 +1,14 @@
+---
+description: List the OttoPort model catalog with live pricing, optionally filtered by modality
+argument-hint: "[chat|image|video|tts|music]"
+allowed-tools: mcp__ottoport__ottoport_list_models
+---
+
+List the OttoPort catalog using the `ottoport_list_models` MCP tool.
+
+Modality filter (may be empty — then list everything): `$1`
+
+Present the result as a table: model id, what it is good at, and price. Group by
+modality when no filter was given, and keep it to the models worth choosing
+between rather than every row. Never invent a model id that the tool did not
+return.

package/commands/setup.md

@@ -0,0 +1,22 @@
+---
+description: Check that the OttoPort plugin is wired up — key, gateway reachability, MCP tools
+allowed-tools: Bash(node:*), Bash(printenv:*), mcp__ottoport__ottoport_list_models
+---
+
+Verify this machine can reach OttoPort, then report what is and is not working.
+
+1. Read the environment: `printenv OTTOPORT_API_KEY OTTOPORT_BASE_URL` (print
+   only whether the key is set and what prefix it has — never echo the key).
+2. Call `ottoport_list_models`. Success means the MCP server, the base URL and
+   the key are all good; stop and report.
+3. If that fails, the fix depends on the error:
+   - no `ottoport` MCP tools at all → the plugin's MCP server did not start;
+     check `node --version` is 20+.
+   - `401`/`invalid key` → the key is missing or wrong. Keys are created at
+     https://ottoport.ai/api-keys and look like `op-…`.
+   - connection refused → `OTTOPORT_BASE_URL` points at a gateway that is not
+     running. It defaults to `https://ottoport.ai`; a local dev gateway is
+     `http://localhost:3014`.
+
+Both variables belong in the user's shell profile, since the MCP server reads
+them from the environment Claude Code was launched in.

package/commands/speech.md

@@ -0,0 +1,15 @@
+---
+description: Turn text into speech, or a prompt into music, through the OttoPort gateway
+argument-hint: "<text> [--voice alloy] [--music]"
+allowed-tools: mcp__ottoport__ottoport_generate_speech, mcp__ottoport__ottoport_generate_music, Bash(curl:*)
+---
+
+Request: $ARGUMENTS
+
+Use `ottoport_generate_music` when the request is for music, a song, or a
+backing track; otherwise use `ottoport_generate_speech` to read the text aloud.
+Pass `voice` and `format` only when named — speech defaults to `gpt-4o-mini-tts`
+with the `alloy` voice, music to `suno-v5`.
+
+Print the returned audio URL, and save it to disk with `curl -sSL` only if the
+user asked for a file.

package/commands/video.md

@@ -0,0 +1,17 @@
+---
+description: Generate a video through the OttoPort gateway
+argument-hint: "<prompt> [--model <id>] [--duration 5]"
+allowed-tools: mcp__ottoport__ottoport_generate_video, mcp__ottoport__ottoport_list_models, Bash(curl:*)
+---
+
+Generate a video with the `ottoport_generate_video` MCP tool.
+
+Request: $ARGUMENTS
+
+- Pass `model`, `duration`, `aspect_ratio` and `image_url` only when the request
+  supplies them; the tool defaults to `kling-3.0`.
+- Video generation takes a minute or more and the call blocks until the job is
+  terminal. Say so before you start, and do not retry a call that is merely slow
+  — a retry is a second billable generation.
+- Print the returned URL, and download it with `curl -sSL` only if the user asked
+  for a file on disk.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ottoport",
-  "version": "1.2.3",
-  "description": "CLI and MCP server for OttoPort — one OpenAI-compatible API for every LLM, image, video, and speech model.",
+  "version": "1.3.0",
+  "description": "Claude Code plugin, CLI and MCP server for OttoPort — one OpenAI-compatible API for every LLM, image, video, and speech model.",
   "homepage": "https://ottoport.ai",
   "license": "MIT",
   "keywords": [
@@ -14,7 +14,9 @@
     "text-to-speech",
     "mcp",
     "mcp-server",
-    "cli"
+    "cli",
+    "claude-code",
+    "claude-code-plugin"
   ],
   "engines": {
     "node": ">=20.0.0"
@@ -22,44 +24,8 @@
   "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"
-  },
-  "devDependencies": {
-    "@anthropic-ai/sdk": "^0.65.0",
-    "@supabase/ssr": "^0.10.2",
-    "@supabase/supabase-js": "^2.43.0",
-    "@tailwindcss/typography": "^0.5.13",
-    "@types/node": "^20.14.0",
-    "@types/react": "^18.3.3",
-    "@types/react-dom": "^18.3.0",
-    "autoprefixer": "^10.4.19",
-    "clsx": "^2.1.1",
-    "daisyui": "^4.12.0",
-    "eslint": "^8.57.0",
-    "eslint-config-next": "^14.2.0",
-    "lucide-react": "^0.395.0",
-    "next": "^14.2.0",
-    "openai": "^4.104.0",
-    "postcss": "^8.4.38",
-    "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",
-    "tailwindcss": "^3.4.4",
-    "typescript": "^5.4.5",
-    "zod": "^3.23.8"
   }
 }

package/skills/ottoport/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ottoport
+description: Generate text, images, and video through OttoPort — one unified, OpenAI-compatible API for every model (GPT, Claude, FLUX, Nano Banana, Kling, Veo 3). Use when the user wants to call an LLM, generate an image, or generate a video and has OttoPort configured, or asks to "use OttoPort".
+---
+
+# OttoPort
+
+OttoPort is a single OpenAI-compatible gateway that routes to first-party model
+providers. One key, one base URL, three modalities: **chat**, **image**, **video**.
+
+## Setup
+
+Two environment variables drive every access path (CLI, MCP, raw HTTP):
+
+- `OTTOPORT_API_KEY` — an `op-…` key (or the dev `OTTOPORT_KEY_SECRET`).
+- `OTTOPORT_BASE_URL` — e.g. `https://ottoport.dev` or `http://localhost:3014`.
+
+Check what's available before generating:
+
+```bash
+node cli/ottoport.mjs models              # full catalog with pricing
+node cli/ottoport.mjs models --modality image
+```
+
+## Choosing a model
+
+| Modality | Good default | Also available |
+| --- | --- | --- |
+| chat | `claude-sonnet-5` | `claude-haiku-4.5` (cheap), `gpt-5.5`, `gemini-3.5-flash` |
+| image | `gpt-image-2` | `nano-banana-pro` (high fidelity), `nano-banana-2` (edits) |
+| video | `kling-3.0` | `seedance-2.0-fast` (cheap), `veo-3.1` (with audio) |
+| tts | `gpt-4o-mini-tts` | `eleven-v3` |
+| music | `suno-v5` | `lyria-2` |
+
+Never invent model ids — run `ottoport models` if unsure.
+
+## CLI (preferred for one-off calls)
+
+```bash
+# Chat (streams by default)
+node cli/ottoport.mjs chat "explain MCP in one sentence" --model claude-haiku-4.5
+node cli/ottoport.mjs chat "summarize this" --system "You are terse." --no-stream
+
+# Image → prints URL(s); --out downloads the first
+node cli/ottoport.mjs image "isometric city at dusk" --model nano-banana-pro --out city.png
+
+# Video → blocks on the queue, prints the URL
+node cli/ottoport.mjs video "drone shot over a canyon" --duration 5 --out clip.mp4
+
+# Speech and music → print an audio URL; --out downloads it
+node cli/ottoport.mjs speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
+node cli/ottoport.mjs music "lo-fi focus beat" --duration 20 --out focus.mp3
+```
+
+## HTTP (for scripts / other languages)
+
+The gateway is OpenAI-compatible, so existing SDKs work by pointing `baseURL`
+at `${OTTOPORT_BASE_URL}/api/v1` with the OttoPort key.
+
+```bash
+curl $OTTOPORT_BASE_URL/api/v1/chat/completions \
+  -H "Authorization: Bearer $OTTOPORT_API_KEY" -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"hi"}]}'
+```
+
+Image: `POST /api/v1/images/generations` `{model, prompt, size?, n?, image_url?}` → `{data:[{url}]}`.
+Video: `POST /api/v1/videos/generations` `{model, prompt, duration?, aspect_ratio?, image_url?}` → a job with `data:[{url}]`.
+
+## MCP (for agent tool use inside another client)
+
+If OttoPort's MCP server is registered, prefer its tools over shelling out:
+`ottoport_list_models`, `ottoport_chat`, `ottoport_generate_image`,
+`ottoport_generate_video`, `ottoport_generate_speech`, `ottoport_generate_music`.
+Register it with:
+
+```bash
+claude mcp add ottoport -- node /abs/path/to/mcp/server.mjs
+```
+
+## Plugin (Claude Code)
+
+Installing the OttoPort plugin brings the MCP server, this skill, and the
+`/ottoport:*` slash commands in one step — no manual `claude mcp add`:
+
+```bash
+/plugin marketplace add https://ottoport.ai/plugin/marketplace.json
+/plugin install ottoport@ottoport
+```
+
+Commands: `/ottoport:models`, `/ottoport:chat`, `/ottoport:image`,
+`/ottoport:video`, `/ottoport:speech`, `/ottoport:setup`.
+
+## Tips
+
+- Image and video calls return **URLs**, not files — download with `--out` (CLI)
+  or fetch the URL yourself. Provider URLs may be short-lived; persist anything
+  you need to keep.
+- Video generation can take a minute; it blocks server-side and returns when done.
+- Errors come back as `{error:{message, code}}`; surface the message to the user.