chutes-media-mcp: Instructions file for Codex

AGENTS.md — working on chutes-media-mcp

Operating guide for AI coding agents and new contributors. It describes this repository only. Read it before changing anything; the rules below encode decisions that were made deliberately and that are easy to undo by accident.

What this project is

chutes-media-mcp is a published npm package that lets a coding agent generate image, video, music and speech through Chutes and save the asset straight into the user's project. It ships three surfaces from one codebase:

• an MCP server (chutes-media-mcp bin, stdio transport) — the primary interface,
• a thin CLI (chutes-media bin) — fallback for shells and agents without MCP,
• a bundled Agent Skill (skill/chutes-media/) documenting the describe→generate workflow.

Repository: https://github.com/TheStreamCode/chutes-media-mcp · public, MIT. Registry: https://www.npmjs.com/package/chutes-media-mcp.

Stack and runtime

• TypeScript (strict, ESM only), bundled with tsup (esbuild), target: node20.
• Runtime for the published artifact: Node.js ≥ 20.3 (engines.node). Do not raise this without a major version bump — it is a breaking change for installed users.
• Development toolchain needs Node.js ^20.19.0, ≥ 22.13.0, or ≥ 24. CI runs the matrix 20 / 22 / 24 on ubuntu-latest.
• Package manager: npm, with package-lock.json. Never introduce pnpm, yarn or bun, never add a second lockfile, and never hand-edit package-lock.json — change it only through npm commands.
• Runtime dependencies are deliberately minimal: @modelcontextprotocol/sdk, ajv, zod. Prefer native Node APIs (global fetch, node:util parseArgs, node:crypto) over new dependencies.

Architecture

src/
├── core/                  # transport-agnostic; knows nothing about MCP or the CLI
│   ├── chutes-client.ts   # HTTP: list / describe / warmup / invoke / download, auth, URL safety, error mapping
│   ├── media-engine.ts    # validate → resolve input assets → warmup → invoke (retry) → save → provenance
│   ├── schema-validate.ts # Ajv validation of params against the live cord JSON Schema
│   ├── present.ts         # shared describe/list/error formatting, reused by both frontends
│   ├── config.ts          # environment → ChutesConfig
│   └── types.ts           # shared types
├── mcp/server.ts          # MCP stdio server — registers the 3 tools, delegates to core
├── cli/index.ts           # CLI — same operations via util.parseArgs
└── index.ts               # public exports of the core