imagine-mcp: Instructions file for Claude Code

imagine-mcp

Production-grade MCP server for image/video understanding and generation across Gemini, OpenAI, and Grok.

Architecture

• Tools (4 total, N+2 layout): understand, generate, config, help
• Providers: gemini | openai | grok
• Tiers: poor (cheap/fast) | rich (high quality)
• Media types: image | video

Tool signatures

understand(media_urls: list[str], prompt: str,
           provider: str | None = None, tier: str = "poor",
           max_tokens: int = 2048,
           model: str | None = None) -> dict

generate(media_type: Literal["image", "video"], prompt: str,
         provider: str | None = None, tier: str = "poor",
         reference_image_url: str | None = None,
         job_id: str | None = None,
         output_mode: Literal["base64", "path", "both"] = "both",
         aspect_ratio: str = "16:9",
         duration_seconds: int = 8,
         model: str | None = None) -> dict

config(action: str, key: str | None = None, value: str | None = None) -> dict

help(topic: str = "understand") -> str

model (litellm provider/model format) selects the model directly for open passthrough -- there is no hardcoded model catalog (#461). For understand it is required unless the UNDERSTAND_MODELS env chain is set (no built-in default). For generate it overrides the GENERATE_MODELS chain and the provider's own minimal built-in default.

Model selection

No hardcoded model-ID catalog: understand is caller-driven only (explicit model= or the UNDERSTAND_MODELS chain; litellm passthrough, any provider). generate stays native per provider (Gemini / OpenAI / Grok) with a minimal built-in default per tier, overridable via model= or GENERATE_MODELS. Capability gaps: OpenAI has no video understanding or generation; Grok production has no video understanding.

Transport modes

Two transports, dispatched in src/imagine_mcp/__main__.py:41-64:

• Default: stdio -- build_app().run(transport="stdio") on stdin/stdout (single-user, no daemon, no browser). Reads creds from env vars only; exits 1 if all three of GEMINI_API_KEY/OPENAI_API_KEY/XAI_API_KEY are missing. Universal MCP client compatibility.
• Opt-in: http -- enabled by --http flag, MCP_TRANSPORT=http, or TRANSPORT_MODE=http. Runs run_http() -> mcp-core run_http_server (src/imagine_mcp/server.py:314,341), always multi-user / remote-style. Set PUBLIC_URL + MCP_DCR_SERVER_SECRET to bind publicly with per-JWT-sub credential isolation; otherwise serves on 127.0.0.1:<port> for local self-host. Credentials set via the browser form at /authorize.