# manga_mcp

An MCP server that lets Claude generate original, English-dialogue manga in a
configurable Japanese art style — with a story-craft layer designed to stop
output from reading like generic AI "slop."

## How it avoids slop

1. **Writer's pass first.** `manga_generate_script` asks Claude (via your own
   Anthropic API key) to break your story prompt into a real script — capped
   at **10 panels total** (fewer = higher quality per panel), with genre rules
   baked in:
   - `romance_bittersweet` — the core conflict must actually resolve, but at
     least one thread stays unresolved. No saccharine endings, no pure tragedy.
   - `action_mystery` — a planted clue must pay off, stakes must escalate
     panel-over-panel, exactly one misdirection.
2. **Character consistency.** The script includes one `character_sheet`
   paragraph, reused verbatim in every panel's image prompt.
3. **Text is never left to the diffusion model.** Dialogue/captions/SFX are
   drawn on top by the compositor (`manga_compose_page`), in real English text
   — not the garbled lettering diffusion models produce.

## Project layout

```
manga_mcp/
  server.py          # MCP tool registrations (the entrypoint)
  story_engine.py     # Story prompt -> panel script (Anthropic API)
  image_backend.py    # Panel script -> panel art (Replicate API)
  compositor.py        # Panel art + dialogue -> finished page (Pillow)
  styles.py            # Art-direction presets ("our own style" lives here)
  models.py             # Shared Pydantic schemas
  config.py             # Env var loading
requirements.txt
.env.example
```

## Setup

1. **Install dependencies** (Python 3.10+):
   ```bash
   pip install -r requirements.txt
   ```

2. **Get your API keys:**
   - Anthropic: https://console.anthropic.com/ → API Keys
   - Replicate: https://replicate.com/account/api-tokens

3. **Copy `.env.example` to `.env`** and fill in both keys.

4. **Pick an art model.** Browse
   https://replicate.com/collections/generate-anime, open a model you like
   (e.g. an Animagine XL / Pony-style / NoobAI-XL checkpoint), copy its
   `owner/name:version` string from the API tab, and paste it into
   `replicate_model_version` for each profile in `styles.py`. This is the
   main knob for "our own style" — tweak `art_direction` / `negative_prompt`
   per profile to push the look further.

5. **Run it standalone to sanity-check:**
   ```bash
   python -m manga_mcp.server
   ```

6. **Connect it to Claude — two ways:**

   **A) Local, via Claude Desktop.** Add to `claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "manga_mcp": {
         "command": "python",
         "args": ["-m", "manga_mcp.server"],
         "cwd": "/absolute/path/to/manga_mcp",
         "env": {
           "ANTHROPIC_API_KEY": "sk-ant-...",
           "REPLICATE_API_TOKEN": "r8_..."
         }
       }
     }
   }
   ```
   Restart Claude Desktop and the five `manga_*` tools show up as available
   tools in chat. Requires the Desktop app to be running.

   **B) Remote, no Desktop needed — works from Claude mobile too.** Custom
   connectors connect to a server reachable over the public internet, from
   any Claude client (web, mobile, Desktop). Fastest path using the included
   `render.yaml` blueprint:
   1. Push this folder to a GitHub repo (`git init && git add . && git commit
      -m init`, create an empty repo on GitHub, `git push`).
   2. On [render.com](https://render.com) (free account): **New +** →
      **Blueprint** → connect that repo. Render reads `render.yaml` and
      configures the service automatically.
   3. It'll prompt you for the two secret values it can't guess:
      `ANTHROPIC_API_KEY` and `REPLICATE_API_TOKEN`. Paste those in.
   4. Deploy. You get a URL like `https://manga-mcp-xxxx.onrender.com`.
      Free tier cold-starts after idling — fine for testing, a $7/mo tier
      removes that.
   5. In Claude: Settings → Connectors → Add custom connector → paste
      `https://manga-mcp-xxxx.onrender.com/mcp`. Now usable from any chat,
      phone included.

## Tools

| Tool | Purpose |
|---|---|
| `manga_generate_script` | Story prompt → panel-by-panel script (≤10 panels) |
| `manga_generate_panel_image` | One panel's art via Replicate |
| `manga_compose_page` | Panel art + dialogue → finished page PNG |
| `manga_generate_full_story` | Runs all three end-to-end for a whole story |
| `manga_list_style_profiles` | Lists configured art styles |

## Known gaps / next steps

- **Character consistency is prompt-only right now.** It's driven entirely by
  reusing the `character_sheet` text — good enough for a prototype, but true
  cross-panel consistency needs image-to-image referencing (e.g. an
  IP-Adapter / ControlNet reference pass, or generating a character turnaround
  once and feeding it back into every panel call).
- **Layouts are template-based** (`compositor.py: LAYOUT_TEMPLATES`), not yet
  driven by `panel_size_weight` — a splash panel currently doesn't visually
  dominate the page yet.
- **No caching** — re-running `manga_generate_full_story` re-generates every
  image from scratch (costs add up on Replicate).