ImageGen.McpHost 0.1.1

ImageGen MCP Server

A provider-agnostic Model Context Protocol server for AI image generation.
Switch between Stability AI and Google Gemini Imagen using runtime tool arguments — your MCP client never notices the change.

Features

• Three MCP tools: image_gen_generate, image_gen_get_credits, image_gen_info
• Two providers out of the box: Stability AI (sd3-large, core) and Google Gemini Imagen 3
• Fail-fast startup — validates config before the server accepts any connections
• Polly resilience — automatic retries with jitter on transient 5xx / 429 errors
• FluentValidation — prompt length, aspect ratio, and step range are checked before any HTTP call
• Hexagonal Architecture — add a new provider by implementing one interface, touching zero existing files
• All logs → stderr — stdout is reserved exclusively for MCP JSON-RPC traffic

Quick Start

1. Prerequisites

• .NET 10 SDK
• A Stability AI or Google Gemini API key

2. Build

git clone https://github.com/your-org/Mcp.Server.ImageGen
cd Mcp.Server.ImageGen
dotnet build ImageGen.slnx

3. Install CLI Tool

Build and pack the tool:

dotnet pack ImageGen.McpHost/ImageGen.McpHost.csproj -c Release

Install globally from local package output:

dotnet tool install --global ImageGen.McpHost --add-source "C:\Projects\Mcp.Server.ImageGen\ImageGen.McpHost\nupkg" --version 0.1.0

If already installed, update instead:

dotnet tool update --global ImageGen.McpHost --add-source "C:\Projects\Mcp.Server.ImageGen\ImageGen.McpHost\nupkg" --version 0.1.0

4. Configure & Run

Stability AI:

$env:STABILITY_API_KEY = "sk-..."
imagegen-mcp

Google Gemini:

$env:GEMINI_API_KEY = "AIza..."
imagegen-mcp

5. Connect to Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "image-gen": {
      "command": "imagegen-mcp",
      "args": [],
      "env": {
        "STABILITY_API_KEY": "sk-..."
      }
    }
  }
}

6. Test with MCP Inspector

$env:STABILITY_API_KEY = "sk-..."
$env:GEMINI_API_KEY = "AIza..."
npx @modelcontextprotocol/inspector imagegen-mcp

Environment Variables (API Keys Only)

Tool Reference

image_gen_generate

prompt        (required) Text description of the image
aspect_ratio  1:1 | 16:9 | 9:16 | 4:3 | 3:4 | 2:3 | 3:2 | 21:9 | 9:21 | 4:5 | 5:4
steps         1–150, default 30
seed          optional integer for reproducibility
model         provider-specific model name override

Returns the absolute path of the saved image file.

image_gen_get_credits

Returns remaining credits for the active provider (Stability AI only; Gemini returns N/A).

image_gen_info

Returns the active provider name, supported models, and output directory.

Solution Structure

ImageGen.slnx
├── ImageGen.Domain/          Pure interfaces, value objects, exceptions
├── ImageGen.Application/     Use cases, ProviderFactory, FluentValidation, MCP tools
├── ImageGen.Infrastructure/  StabilityAdapter, GeminiAdapter, Polly, ImageFileHelper
├── ImageGen.McpHost/         Console host — thin bootstrap, fail-fast config check
├── ImageGen.Tests/           xUnit tests: validators, use cases, adapters (mocked HTTP)
└── Documentation/            DocFX documentation site

Running Tests

dotnet test ImageGen.slnx

All tests run without network access — HTTP responses are intercepted by FakeHttpMessageHandler.

Building the Docs

dotnet tool restore
dotnet build Documentation/Documentation.csproj
# Output: _site/

Adding a New Provider

See Adding a New Provider — four steps, only the Infrastructure layer is touched.

License

MIT