ottoport 1.3.0 → 1.3.1

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

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.1",
   "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.