Metadata-Version: 2.4
Name: runfra-mcp
Version: 0.1.0
Summary: Model Context Protocol server for Runfra — async batch image generation. Lets Claude / Cursor / any MCP client submit txt2img and img2img jobs and read results.
Project-URL: Homepage, https://runfra.com
Project-URL: Repository, https://github.com/spencer9714/Runfra
Project-URL: Documentation, https://runfra.com/docs/api
Project-URL: Issues, https://github.com/spencer9714/Runfra/issues
Author-email: Runfra <noreply@runfra.com>
License: MIT
License-File: LICENSE
Keywords: ai,flux,image-generation,img2img,mcp,model-context-protocol,product-photography,runfra,sdxl,stable-diffusion,txt2img
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastmcp<3.0,>=2.0
Requires-Dist: httpx<1.0,>=0.27
Description-Content-Type: text/markdown

# runfra-mcp

[![PyPI version](https://img.shields.io/pypi/v/runfra-mcp.svg)](https://pypi.org/project/runfra-mcp/)

Model Context Protocol (MCP) server for [Runfra](https://runfra.com) — async
batch image generation. Plug it into Claude Desktop, Cursor, or any MCP-aware
host and the assistant can submit text-to-image jobs, image-to-image
("product scene") jobs, and poll for results inside a conversation.

## Tools

The server exposes three tools. All use `RUNFRA_API_KEY` from the environment.

### `runfra_create_image_job`

Submit a text-to-image job. Returns immediately with `job_id` + `seeds`; pair
with `runfra_get_job_result` to fetch the final image URLs.

| Argument | Default | Notes |
|---|---|---|
| `prompt` | required | 1–2000 chars |
| `model` | `stable-diffusion-xl-base-1.0` | also `flux-schnell`, `flux-dev` |
| `width` / `height` | `1024` | 512–1024 |
| `batch_size` | `1` | 1–100; tier caps apply |
| `quality_mode` | `strict` | `strict` / `soft` / `off` |
| `negative_prompt` | _none_ | ignored by `flux-schnell` and `flux-dev` |

### `runfra_get_job_result`

Get the current state of any job by ID.

| Argument | Default | Notes |
|---|---|---|
| `job_id` | required | UUID returned by either creation tool |
| `wait_for_seconds` | `0` | `0` = single-shot. >0 = poll every 3 s up to that many seconds (hard-capped at 300). On timeout the tool returns the in-progress state with `timeout_exceeded: true` so the caller can retry. |

### `runfra_create_product_scene`

Image-to-image: take a public HTTPS image URL plus a scene prompt, run
SDXL img2img against it, return one final image. Combines two backend calls
(`/v1/uploads/input-image-by-url` + `/v1/jobs`) into one tool.

| Argument | Default | Notes |
|---|---|---|
| `image_url` | required | Public HTTPS URL. PNG / JPEG / WebP, ≤10 MB, longest side ≤1024 px. SSRF-guarded server-side fetch. |
| `scene_prompt` | required | 1–2000 chars |
| `width` / `height` | `512` / `512` | 384–768, multiples of 64; `width × height` ≤ 768×768 |
| `strength` | `0.6` | 0.4–0.9. Lower keeps the reference visible; higher re-imagines the frame |
| `crop_anchor` | `center` | also `top` / `bottom` / `left` / `right` / `top-left` / `top-right` / `bottom-left` / `bottom-right` |
| `wait_for_seconds` | `90` | poll for completion. 0 = fire-and-forget |

## Install

```bash
pip install runfra-mcp
```

Requires Python ≥3.10.

## Configure your MCP client

Get an API key at [runfra.com/dashboard/api-keys](https://runfra.com/dashboard/api-keys).
The key is shown **once** at creation — save it immediately.

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
`%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "runfra": {
      "command": "runfra-mcp",
      "env": {
        "RUNFRA_API_KEY": "rfa_your_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. The three tools appear under "Runfra" in the
tool picker.

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "runfra": {
      "command": "runfra-mcp",
      "env": {
        "RUNFRA_API_KEY": "rfa_your_key_here"
      }
    }
  }
}
```

Restart Cursor.

### Any other MCP host

Run the server directly:

```bash
RUNFRA_API_KEY=rfa_your_key_here runfra-mcp
```

It speaks MCP over stdio — no network port is opened.

### Optional env vars

- `RUNFRA_BASE_URL` — override the API base URL. Default is
  `https://api.runfra.com`. Useful for staging environments.

## Example session

> **You** — "Generate me a photoreal red panda on a wooden bridge, golden-hour light. Wait for the result."

> **Claude** uses `runfra_create_image_job(prompt="a photoreal red panda...", batch_size=4)`, then immediately `runfra_get_job_result(job_id=..., wait_for_seconds=120)`, and replies with the `best_result_url`.

> **You** — "Now take this photo (https://cdn.example.com/lamp.jpg) and put it in a Mediterranean kitchen at golden hour."

> **Claude** uses `runfra_create_product_scene(image_url="https://cdn.example.com/lamp.jpg", scene_prompt="on a marble countertop in a Mediterranean kitchen, golden hour light", strength=0.55)` and replies with the result URL.

## Pricing

`runfra-mcp` itself is free. Image generation consumes Runfra credits; new
accounts come with 100 credits.

| Model | ≤512 px | ≤768 px | >768 px |
|---|---|---|---|
| SDXL | 1 cr | 2 cr | 3 cr |
| FLUX Schnell | 2 cr | 3 cr | 4 cr |
| RunFra Pro (`flux-dev`) | 5 cr | 9 cr | 14 cr |

Total cost = `credits_per_image × batch_size`. Failed jobs are refunded
automatically. See [runfra.com/pricing](https://runfra.com/pricing) for credit
packs.

## Security

- Treat your `RUNFRA_API_KEY` like a password. The MCP host process spawns
  this server with the key in its environment — anyone with read access to
  the host's config file can read the key.
- Revoke keys at [runfra.com/dashboard/api-keys](https://runfra.com/dashboard/api-keys)
  if a key is exposed.
- Reference image URLs must be public HTTPS. The Runfra API refuses
  `http://`, `file://`, `data:`, and any host that resolves to a private/
  reserved IP range (RFC 1918, loopback, link-local incl. cloud metadata,
  CGNAT, IPv6 ULA / link-local).

## Develop

```bash
git clone https://github.com/spencer9714/Runfra.git
cd Runfra/mcp-server
pip install -e .
RUNFRA_API_KEY=rfa_your_key_here runfra-mcp   # runs the server on stdio
```

## License

MIT
