{
  "markdown": "# Vivideo Toolchain\n\nThe developer + agent integration layer for the [Vivideo API](https://developers.vivideo.ai) — a shared client, an MCP server, a CLI, and Skills. **Agents are a primary user, not an afterthought.**\n\nEverything sits *on top of* the public API (the source of truth). No backend business logic is duplicated here — the toolchain only adds client-side ergonomics and guardrails.\n\n```\nvivideo-toolchain/            npm workspaces monorepo (TypeScript)\n├── packages/core   @vivideo/core   one typed API client + guardrails (shared)\n├── packages/mcp    @vivideo/mcp    MCP server (stdio) — 13 agent tools\n├── packages/cli    @vivideo/cli    `vivideo` CLI — humans, scripts, CI, agents\n├── skills/                          reusable agent Skills (SKILL.md)\n└── docs/                            installation, configuration, workflows\n```\n\n## Architecture\n\nOne client, one set of types, derived from [`packages/core/openapi.yaml`](packages/core/openapi.yaml). The MCP server and CLI both call `@vivideo/core` — there is exactly **one** representation of each request/response, so the tools, CLI, docs and OpenAPI stay consistent.\n\n`@vivideo/core` adds only client-side concerns, never business logic:\n\n| Guardrail | What it does |\n|---|---|\n| **Rate limiting** | Token-bucket cap on request rate (default 8/s) — the client can't *become* a request flood. |\n| **Concurrency cap** | Semaphore limits in-flight requests (default 4). |\n| **Bounded retries** | Retries only `retryable` failures, with full-jitter backoff, capped attempts. |\n| **Honors `Retry-After`** | On 429 it waits the API-specified delay before retrying. |\n| **Idempotency** | Every video-create sends an `Idempotency-Key`; retries reuse it → no duplicate charges. |\n| **Timeouts** | Per-request `AbortController` timeout (default 30s). |\n| **Safe waiting** | `waitForVideo` polls at the API's suggested interval, with a hard timeout — never a `while(true)`. |\n| **Secret redaction** | API keys / signing secrets are stripped from every log, error, and output. |\n\nThese complement — and never bypass — the API's own auth, rate limits, idempotency, credit checks, premium gates, ownership and error model.\n\n## Quick start\n\n```bash\n# from the repo (until packages are published to npm)\nnpm install\nnpm run build\n\n# authenticate (stored 0600 in ~/.vivideo/config.json), or use VIVIDEO_API_KEY\nexport VIVIDEO_API_KEY=\"vv_live_...\"   # from https://app.vivideo.ai/account/api-keys\n\n# CLI\nnode packages/cli/dist/index.js account\nnode packages/cli/dist/index.js create auto --prompt \"A 20s product teaser\" --wait\n\n# MCP server (stdio) — point an MCP client at this command\nnode packages/mcp/dist/index.js\n```\n\nOnce published: `npm i -g @vivideo/cli` (gives `vivideo`), and `npx @vivideo/mcp` for the server.\n\n## Docs\n\n- [MCP server — install, configure, connect to clients, tool reference](docs/mcp.md)\n- [CLI — install, auth, command reference, JSON & non-interactive use, exit codes](docs/cli.md)\n- [Skills — install & use](skills/README.md)\n- [Workflows — human & agent, end to end](docs/workflows.md)\n- [Security, rate limits, idempotency, credits & premium, troubleshooting](docs/guide.md)\n\n## Authentication & security\n\n- Keys are read from (in order): explicit option → `VIVIDEO_API_KEY` env → `~/.vivideo/config.json` (written owner-only `0600`).\n- The key is **never printed** — all output passes through secret redaction; `configure` stores it without echoing it.\n- Keys are account-scoped secrets. Keep them server-side; one per integration so a leak is revocable in isolation.\n\n## Not included (honest scope)\n\n- **Cancellation** — the public API has no cancel endpoint, so no cancel tool/command is offered. Failed/stuck renders are auto-refunded by the API.\n- **Agent/chat mode** — not exposed by the public API, so not in the toolchain.\n- Nothing here publishes to npm, provisions DNS, or deploys — those are external steps (see the final section of [docs/mcp.md](docs/mcp.md)).\n\n## Development\n\n```bash\nnpm run build       # build all three packages (tsc -b)\nnpm run typecheck   # type-check the whole workspace\nnpm test            # vitest\n```\n\nRequires Node ≥ 18.17.\n",
  "bytes": 4154,
  "sha": "258cfa1bfcc08c0c245dcd295b0ee7a2c23ff9b382292a806d1c6b39fefcec30",
  "repo_slug": "egocen-vivideo/vivideo-toolchain",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_egocen_vivideo_vivideo_dd11b3c9/readme"
}