# media-gen-mcp

A personal [MCP](https://modelcontextprotocol.io) server that gives [OpenCode](https://opencode.ai) the ability to generate images and videos mid-conversation — invoked as a tool, not a separate app — using free-tier AI media providers.

Built for generating visual assets and video clips for my own websites, apps, and projects, without paying for API access.

## Providers

|Provider|Capabilities|Trust level|Status|
|---|---|---|---|
|[Agnes AI](https://apihub.agnes-ai.com)|image, video|`untrusted`|active|
|[Cloudflare Workers AI](https://developers.cloudflare.com/workers-ai/)|image|`untrusted`|active|
|[Hugging Face Inference API](https://huggingface.co/docs/api-inference)|image|`untrusted`|active|
|[Google Gemini](https://ai.google.dev)|image|`trusted`|**unavailable** — free-tier image generation quota is policy-set to 0 as of Aug 2026; requires a billed Google Cloud project. Implemented and ready — flip `status: active` in `config.yaml` once a working key exists|

`trust_level` determines how a provider's responses are handled: `untrusted` providers are unofficial/self-parsed and go through full schema validation before anything else happens; `trusted` providers use an official SDK assumed to already validate its own response shape. See `ARCHITECTURE.md` for the full reasoning.

Providers can each have multiple named accounts (e.g. multiple API keys for the same provider) — selectable explicitly per call, no auto-rotation. Some accounts need more than one secret: Cloudflare requires an account ID alongside its API token (`account_id_env` in `config.yaml`).

## Setup

This repo isn't published to a public remote yet, so `<repository-url>` is a placeholder — substitute the URL you actually clone from, don't copy it verbatim. The explicit `media-gen-mcp` target keeps the following `cd` correct: a bare `git clone` defaults to a directory named after the repository, so `cd media-gen-mcp` only holds if the repo happens to be named `media-gen-mcp`.

```bash
git clone <repository-url> media-gen-mcp
cd media-gen-mcp
python -m venv .venv
.venv/bin/pip install -e .
```

Create a `.env` file in the project root with whichever providers you plan to use:

```
AGNES_API_KEY=...
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ACCOUNT_ID=...
HUGGING_FACE_API_TOKEN=...
GEMINI_API_KEY=...   # optional — provider is currently marked unavailable
```

`config.yaml` maps each of these to a named account per provider — see the file itself, or `ARCHITECTURE.md`'s Config section, for the full schema (multiple accounts per provider, per-provider defaults, hardening limits).

### Register with OpenCode

Add to `~/.config/opencode/opencode.json` (global, so it's available from any project):

```jsonc
{
  "mcp": {
    "media-gen-mcp": {
      "type": "local",
      "command": [
        "/absolute/path/to/media-gen-mcp/.venv/bin/python",
        "/absolute/path/to/media-gen-mcp/server.py"
      ]
    }
  }
}
```

**Both paths must be absolute.** This is a global config spawned from whatever directory you happen to be working in when OpenCode starts — a relative path only happens to work if you're inside this repo, and silently breaks everywhere else.

Confirm it's connected:

```bash
opencode mcp list
```

## Tools exposed

- **`generate_image(prompt, provider?, account?, project_dir?, output_path?, ...)`** — generates an image, returns the saved file path.
- **`generate_video(prompt, provider?, account?, project_dir?, output_path?, ...)`** — starts an async video job (Agnes only), returns a `job_id` to poll.
- **`check_video_job(job_id)`** — checks/advances a video job; downloads and saves the file once complete.
- **`list_providers()`** — reports configured providers, their status, capabilities, and accounts.

Where a file is saved follows this priority: an explicit `output_path` → under `project_dir/ai-media/` if given → the configured default output directory otherwise.

## Project docs

- **`ARCHITECTURE.md`** — the full design: provider abstraction, trust-level validation, async video job handling, accounts, config schema, and the current state of the system.
- **`progress-tracker.md`** — current build status, the task list, and the incidents/lessons that shaped the decisions above.
- **`AGENTS.md`** — standing conventions for AI coding agents working on this codebase (testing discipline, hard rules, definition of done).

## License

Released to the public domain under The Unlicense — see [`UNLICENSE.md`](./UNLICENSE.md). Free to copy, modify, and distribute; provided without warranty.

## Status

Personal v1, built for a single user. Secrets live in a repo-adjacent `.env`; not currently packaged for distribution to other users or other machines (see ARCHITECTURE.md's "Future: distribution" note for what that would need). Deterministic image _editing_ (background removal, overlays, compositing) is explicitly out of scope — this project only generates media.