media-gen-mcp: Instructions file for Codex

AGENTS.md

Project

media-gen-mcp is a personal MCP server that exposes image and video generation tools to OpenCode. It wraps multiple AI media providers (Agnes AI, Google Gemini, more later) behind one interface, so choosing a provider is a config/runtime decision, not a code change per provider.

Read ARCHITECTURE.md before making any structural change, and check progress-tracker.md for current status and past incidents before starting work. ARCHITECTURE.md governs what the system looks like, right now — provider interface, trust-level wrapping, job persistence, module layout, tool schemas. progress-tracker.md governs what's been done, what's open, and what's already gone wrong once — read it so you don't re-discover a lesson the hard way. This file (AGENTS.md) governs how you work, independent of both.

Stack

• Python, mcp SDK for the protocol layer
• httpx for outbound HTTP calls (Agnes)
• official google-genai SDK for Gemini
• pydantic for response schema validation
• python-dotenv for local secrets
• pytest for tests

Hard rules

• Never log, print, or write API keys anywhere — including error messages and test fixtures. Secrets live only in .env (gitignored), read via environment variables.
• Machine-specific identifiers leak too — absolute paths under a user's home directory, usernames, local tool-install locations. These aren't secrets in the credential-unlocks-access sense, but they're a real leak class on their own, and they've been found twice in this project in files that don't look like "config" at a glance: a tool's cache directory (graphify-out/.graphify_python) and an agent hook-command file (.claude/settings.json). Don't assume machine paths only hide in obvious places.
• When a leak-shaped problem is found once, don't just fix that instance — check whether the same pattern exists elsewhere before considering it closed. In this project the second machine-path leak was found by accident, unrelated to what was being worked on, and it prompted a full history sweep (git filter-repo) rather than a single-file fix. That full-sweep response is the default for this shape of discovery, not the exception.
• Any provider marked untrusted in config.yaml goes through the full ResponseValidator path, no exceptions and no "temporarily skip it to get something working" — wire it through the validator from the start.
• Every provider, trusted or not, still gets the generic hardening: timeout, size cap, content-type check, safe filename generation. This isn't optional just because a provider is marked trusted.
• Don't add a new dependency without flagging it first — this is a personal, free-tier project; keep the footprint small.
• Don't guess at a provider's response shape. If Agnes's actual response format for a given endpoint isn't confirmed by a real call, say so and ask, rather than inventing a plausible-looking schema.
• Never assume the MCP server's own process cwd is the user's project directory (see ARCHITECTURE.md for why) — always go through the explicit project_dir argument.
• For untrusted providers, _extract_image_bytes reads a raw dict, not the validated Pydantic model — validation and extraction are two separate passes over the same data, not one enforcing the other structurally. Every field extraction touches must be explicitly required and type-checked in that provider's schema (confirmed by audit for Agnes/Cloudflare/HuggingFace as of Milestone 5). If you add a new provider, add a field to extraction, or change a schema, re-verify this by hand — nothing enforces it automatically.