orcadub-mcp-server: Instructions file for Codex

AGENTS.md — orcadub-mcp-server

Guidance for AI coding agents (Codex, Claude Code, Cursor, …) working in this repository. Read this before changing code.

What this repo is

The public distribution repo for the OrcaDub MCP server: a standalone Go stdio MCP server that exposes the OrcaDub video-dubbing service (OrcaRouter model orca/dub) as five tools — dub_health / dub_upload / dub_create / dub_get / dub_download.

It is a mirror for release purposes. The development home is the private Continuum-AI-Corp/orca-rt-dubbing repo (cmd/dub-mcp), which shares wire types with the dub-server itself. Feature work generally lands there first and is synced here manually. Keep the two in behavioural lockstep.

Layout

cmd/                   # entrypoint; serverVersion stamped via goreleaser ldflags
internal/              # HTTP client, Skill installer/TUI/i18n, MCP tool layer, vendored wire types, tests
npm/                   # npx launcher: postinstall downloads the platform binary
.goreleaser.yaml       # 6-platform release (bare binaries + tar.gz/zip + ghcr.io docker images)
Dockerfile             # standalone build; Dockerfile.goreleaser is used at release time
.github/workflows/     # ci.yml (fmt/vet/build/test/goreleaser check), release.yml (tag → release + npm publish)
server.json            # MCP Registry manifest

Architecture invariants — do not break these

1. All submit/query traffic goes through the OrcaRouter gateway (https://api.orcarouter.ai, hardcoded as gatewayBaseURL). Every entry-point request carries the model=orca/dub routing field: videos create body, /v1/files multipart form field, /v1/uploads create body.
2. Delivery uses the origin content route — https://orcadub.orcarouter.ai/v1/videos/{job_id}/content with the same Bearer key (job_id comes from the gateway's task retrieve). The gateway's own /content proxy is SSRF-blocked and its stored presigned URL expires; the origin re-signs per request. Never expose presigned COS URLs (output_url) to users — they are bearer-token-free and unrevocable.
3. The only dubbing runtime configuration is ORCADUB_API_KEY. No other env vars, no config files. Skill installation does not use the key. A missing key must NOT fail startup: tools register and every dubbing call returns the sign-up redirect to https://www.orcarouter.ai/console so the agent can walk the user through registration.
4. Tool surface = the gateway's documented dub lifecycle, nothing more. Do not add list / cancel / delete / native /api/v1/dub/* tools — the gateway does not expose those routes.
5. dub_create is billed (per minute of source video). Required fields (source_lang, target_lang, file_id XOR url, video_name with file_id) carry "REQUIRED — ask the user" in their jsonschema descriptions — keep those annotations so agents ask instead of guessing. Boolean knobs are *string "true"/"false" on the wire (server convention); convert via boolStr.
6. Folder names must not carry the orcadub brand — directories are plain cmd/, internal/. The brand lives on the repo, the released binary, and the npm package (@orcadub/cli) only.
7. Wire types in internal/types.go are vendored from orca-rt-dubbing/internal/quality/openaicompat (the source of truth, shared with the server). Do not invent or rename JSON fields here — sync from the source when the server changes.
8. Two error envelopes exist on the wire and both must keep parsing: OpenAI-style {"error":{"message":...}} (gateway routing errors) and the OrcaRouter task envelope {"code":..,"message":..,"data":..} (dub task errors). See apiError.
9. Skill installer machine output stays presentation-free. Interactive fields are implemented by the Huh adapter in internal/skill_prompt_huh.go; installer-owned Simplified Chinese and English text lives in internal/skill_i18n.go. skill install --json, --yes, and fully explicit installs must not emit the banner, ANSI escapes, prompts, or localized status values into JSON.