awkoy/replicate-flux-mcp

Migrates from @modelcontextprotocol/sdk 1.7 → 1.29.0 and replicate 1.1 → 1.4.0, then layers on features that take advantage of the newer MCP spec (protocol revision 2025-11-25).

SDK migration

• Every tool moves to registerTool with a proper config object (title, description, annotations, inputSchema, outputSchema).
• Resources move to registerResource with ResourceTemplate + list callback + { title, description, mimeType } config.
• handleError returns { isError: true } CallToolResult instead of throwing McpError, matching the current MCP spec.
• Server advertises prompts: {} and logging: {} capabilities.

New capabilities

• Structured output — every generate_* tool returns machine-readable structuredContent matching a per-tool outputSchema (URL, prompt, format, aspect_ratio, seed where applicable).
• Progress notifications — generate_multiple_images and generate_image_variants emit notifications/progress when the client supplies a progressToken.
• run_replicate_model — generic escape hatch accepting any owner/name[:version] reference, gated by the optional REPLICATE_MODEL_ALLOWLIST env var. Fail-closed when the env var is set but empty.
• get_model_schema — fetches a model's OpenAPI input schema for introspection before calling run_replicate_model.
• 5 prompt templates — logo, portrait, svg-icon, product-shot, isometric-diagram exposed via registerPrompt (slash palette in Claude Desktop, @-menu in Cursor).
• Structured logging — resource errors travel over notifications/message via server.sendLoggingMessage instead of console.error.

Housekeeping

• Shared helpers: src/utils/image.ts (mimeFor, fetchWithAuth, base64/svg fetch), src/resources/fetchPredictions.ts (paginate + error-log used by all three list resources).
• sharedImageParams in src/types/index.ts — the three image-generation schemas no longer duplicate the same 8 fields.
• run_replicate_model only emits an image content block when the guessed MIME is actually an image type (prevents clients from choking on non-image image blocks).
• Dropped a redundant predictions.get call in createPrediction whose return value was never used.
• README fully refreshed for the 0.4.0 surface (prompts, structured output, env-var semantics, testing note).

Environment variables

| Variable | Required | Purpose |
| --- | --- | --- |
| REPLICATE_API_TOKEN | yes | Replicate API token. |
| REPLICATE_MODEL_ALLOWLIST | no | Comma-separated owner/name entries gating run_replicate_model. Unset = any model allowed. Set-but-empty = deny all. |

Install

npx -y replicate-flux-mcp

Or configure via MCP client — see the README.