ottoport 1.3.0 → 1.3.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "1.3.2",
   "author": {
     "name": "LITBOX LLC",
     "email": "support@ottoport.ai"

package/README.md

@@ -1,28 +1,52 @@
-# OttoPort for Claude Code
+# OttoPort
 
-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.
+One API for every model. This package is three things over the same gateway:
+a **CLI**, an **MCP server**, and a **Claude Code plugin** — chat, image,
+video, speech, and music, on one key and one prepaid balance.
 
-## Install
+Get a key at <https://ottoport.ai/api-keys> (they look like `op-…`), then pick
+whichever surface fits.
 
-```
-/plugin marketplace add https://ottoport.ai/plugin/marketplace.json
-/plugin install ottoport@ottoport
-```
+## CLI
 
-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:
+```bash
+npm install -g ottoport     # or run any command below through `npx ottoport …`
+export OTTOPORT_API_KEY=op-...
+```
 
 ```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
+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] [--out speech.mp3]
+ottoport music "<prompt>" [--model suno-v5] [--duration 15] [--out song.mp3]
+
+ottoport install <host>   # wire the MCP server into an agent
+ottoport mcp              # run the MCP server on stdio
 ```
 
-Run `/ottoport:setup` to confirm the key, the gateway, and the MCP tools are all
-live.
+Chat streams by default. Image, video and audio commands print the result URL;
+`--out` downloads it. `--url` and `--key` override the environment for a single
+call.
+
+Every command is a thin client over the public REST API, so anything the CLI
+does is available to your own code — the gateway is OpenAI-compatible, and any
+OpenAI SDK works by pointing `baseURL` at `https://ottoport.ai/api/v1`.
+
+## Claude Code plugin
 
-## Slash commands
+Brings the MCP server, the `ottoport` skill, and six slash commands in one
+install:
+
+```
+/plugin marketplace add https://ottoport.ai/plugin/marketplace.json
+/plugin install ottoport@ottoport
+```
 
 | Command | What it does |
 | --- | --- |
@@ -33,23 +57,33 @@ live.
 | `/ottoport:speech` | Read text aloud, or generate music. |
 | `/ottoport:setup` | Diagnose key / gateway / MCP wiring. |
 
-## 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.
-
-## CLI
+## Other agents
 
-The same package ships the `ottoport` CLI for terminal and CI use:
+Claude Code is the only host with a plugin format. Everywhere else, one command
+registers the MCP server by writing that agent's own config:
 
 ```bash
-npm install -g ottoport
-ottoport models --modality video
-ottoport image "isometric city at dusk" --out city.png
+npx ottoport install codex     # or hermes, cursor, windsurf, claude-desktop, claude
 ```
 
+Codex also gets the OttoPort skill copied into `~/.codex/skills/`. Your key is
+forwarded from the environment rather than written into any config file.
+
+## MCP tools
+
+`ottoport_list_models`, `ottoport_chat`, `ottoport_generate_image`,
+`ottoport_generate_video`, `ottoport_generate_speech`, `ottoport_generate_music`.
+The server speaks stdio JSON-RPC and is launched by the host as a subprocess, so
+it needs Node 20+ on the PATH of whatever starts that host.
+
+## Configuration
+
+- `OTTOPORT_API_KEY` — your `op-…` key. Export it from your shell profile: the
+  MCP server reads the environment its host was launched in, so a key exported
+  inside a running session arrives too late.
+- `OTTOPORT_BASE_URL` — defaults to `https://ottoport.ai`; set it only to point
+  at another deployment.
+
 ## Notes
 
 - Image, video, and audio calls return **URLs**, and provider URLs expire.

package/commands/setup.md

@@ -1,6 +1,6 @@
 ---
 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
+allowed-tools: Bash(node:*), Bash(which:*), Bash(printenv:*), mcp__ottoport__ottoport_list_models
 ---
 
 Verify this machine can reach OttoPort, then report what is and is not working.
@@ -10,8 +10,13 @@ Verify this machine can reach OttoPort, then report what is and is not working.
 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+.
+   - no `ottoport` MCP tools at all → the plugin's MCP server did not start.
+     Check `which node` before `node --version`: the usual cause is not a wrong
+     version but no `node` at all in the environment that launched the host.
+     A Node managed by nvm, volta, asdf or mise lives in a directory those tools
+     add to an interactive shell's PATH, and a client started from the Dock or a
+     desktop launcher never runs that shell. Launching the host from a terminal,
+     or installing a system-wide Node, fixes it.
    - `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ottoport",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "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",

package/skills/ottoport/SKILL.md

@@ -1,99 +1,84 @@
 ---
 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".
+description: Generate text, images, video, speech, and music through OttoPort — one gateway for every model (GPT, Claude, Gemini, GPT Image, Nano Banana, Veo, Kling, Seedance, Suno). Use when the user wants to call an LLM or generate an image, video, or audio 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**.
+One gateway, five modalities: **chat**, **image**, **video**, **speech**, **music**.
 
-## Setup
+## Use the tools
 
-Two environment variables drive every access path (CLI, MCP, raw HTTP):
+This skill ships with an MCP server. Call its tools directly — do not shell out,
+and do not call the HTTP API, when a tool covers the job:
 
-- `OTTOPORT_API_KEY` — an `op-…` key (or the dev `OTTOPORT_KEY_SECRET`).
-- `OTTOPORT_BASE_URL` — e.g. `https://ottoport.dev` or `http://localhost:3014`.
+| Tool | For |
+| --- | --- |
+| `ottoport_list_models` | The catalog, with modality, provider, and price. Filter with `modality`. |
+| `ottoport_chat` | `prompt`, plus optional `model`, `system`, `temperature`, `max_tokens`. |
+| `ottoport_generate_image` | `prompt`, plus optional `model`, `size`, `n`, `image_url` (edits / image-to-image). |
+| `ottoport_generate_video` | `prompt`, plus optional `model`, `duration`, `aspect_ratio`, `image_url`. |
+| `ottoport_generate_speech` | `prompt` (the text), plus optional `model`, `voice`, `format`. |
+| `ottoport_generate_music` | `prompt`, plus optional `model`, `duration`, `format`. |
 
-Check what's available before generating:
-
-```bash
-node cli/ottoport.mjs models              # full catalog with pricing
-node cli/ottoport.mjs models --modality image
-```
+If those tools are not present, the server is not registered in this client —
+say so rather than reaching for a shell. `ottoport install <host>` registers it
+(codex, claude, hermes, cursor, windsurf, claude-desktop).
 
 ## Choosing a model
 
-| Modality | Good default | Also available |
+Pass `model` only when the request calls for a specific one; every tool has a
+sensible default.
+
+| Modality | 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` |
+| speech | `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
+Never invent a model id. Call `ottoport_list_models` when unsure — the catalog
+changes, and a wrong id is a failed billable call.
 
-# 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.
+## What comes back
 
-```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, video and audio tools return **URLs**, not files. Provider URLs expire;
+  download anything worth keeping.
+- Video blocks until the job is terminal, often a minute or more. Say so before
+  starting, and never retry a slow call — a retry is a second generation, billed
+  again.
+- Errors arrive as `{error: {message, code}}`. Surface the message; it usually
+  names the fix (`401` = key, `402` = balance or spend limit).
 
-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}]`.
+## Terminal and CI
 
-## 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:
+Outside a tool-calling client, the same account works from the CLI:
 
 ```bash
-claude mcp add ottoport -- node /abs/path/to/mcp/server.mjs
+npm install -g ottoport        # or: npx ottoport <command>
+export OTTOPORT_API_KEY=op-... # keys: https://ottoport.ai/api-keys
+
+ottoport models --modality image
+ottoport chat "explain MCP in one sentence" --model claude-haiku-4.5
+ottoport image "isometric city at dusk" --out city.png
+ottoport video "drone shot over a canyon" --duration 5 --out clip.mp4
+ottoport speech "Welcome to OttoPort" --voice alloy --out welcome.mp3
 ```
 
-## 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`:
+`--out` downloads the result; chat streams unless `--no-stream`.
 
-```bash
-/plugin marketplace add https://ottoport.ai/plugin/marketplace.json
-/plugin install ottoport@ottoport
-```
+## Calling from code
 
-Commands: `/ottoport:models`, `/ottoport:chat`, `/ottoport:image`,
-`/ottoport:video`, `/ottoport:speech`, `/ottoport:setup`.
+Only when writing a program that will run without this agent: the gateway is
+OpenAI-compatible, so any OpenAI SDK works by pointing `baseURL` at
+`https://ottoport.ai/api/v1` with an OttoPort key. Image, video, speech and
+music live under `/api/v1/images/generations`, `/videos/generations`,
+`/audio/speech` and `/audio/music`. Full reference: <https://ottoport.ai/docs>.
 
-## Tips
+## Configuration
 
-- 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.
+- `OTTOPORT_API_KEY` — an `op-…` key, read from the environment the client was
+  launched in. A key exported inside a running session arrives too late.
+- `OTTOPORT_BASE_URL` — defaults to `https://ottoport.ai`; set it only to point
+  at another deployment.