Manga Trans Studio & MCP Server

A local-first scanlation backend and Model Context Protocol (MCP) server for Manga, Manhwa, and Manhua.

This project splits localization responsibilities between the AI agent and the local engine:

• MCP Host (Antigravity, Cursor, Claude Desktop, Codex): Operates as the vision and translation engine, directly inspecting raw pages via ImageContent and returning translations keyed to immutable region_id tags.
• Local Python Backend: Handles bubble geometry detection, local OCR (Manga-OCR / EasyOCR), contour-aware text erasure (inpainting), typography layout with full Vietnamese diacritics word wrapping, and strict pixel QA validation.
• Studio Canvas (FastAPI Web App): Provides a side-by-side dual-canvas interface for real-time visual inspection, manual text adjustments, custom speech-bubble cropping, and PNG export.

---

Key Capabilities

1. Host-Native Vision & Localization

• Standard MCP integration: Transmits raw manga pages as native ImageContent so the host model reads visual panels, character emotions, and reading order directly.
• Fully local execution: No third-party LLM API keys (OpenAI, Gemini, OpenRouter) required on the server side.

2. Contour-Aware Inpainting (Bubble Cleaner)

• Uses Connected-Component Analysis and Principal Component Analysis (PCA) to distinguish speech glyphs from line art and panel contours.
• Locks panel borders and thought-bubble perimeters prior to inpainting, preventing white bleed or destruction of background artwork.

3. Automated Manga Typesetter

• Dynamic font sizing calculated to fit elliptical, rectangular, and spike balloons.
• Smart word wrapping supporting Vietnamese diacritics and tones without word-breaking artifacts or missing glyphs (tofu).
• Built-in localized comic fonts: Itim, Pangolin, Patrick Hand, Mali Bold, Bangers, Saira Condensed, Be Vietnam Pro, Chakra Petch, Comic Neue, and more.
• Text stroke, color fill, alignment (center/left/right), and bold/italic styles.

4. Strict Pixel QA

Automated post-render verification:

• box_alignment_score: Geometric fit between rendered text and target balloon (Target: 100).
• render_overflow_pixels & per_region_typeset_overflow_pixels: Ensures zero text clipping outside allowable bounds (Target: 0).
• artwork_changes_outside_source_regions: Enforces 0% pixel alterations outside speech regions.

5. Dual-Canvas Web Studio

• Side-by-side comparison of original raw pages and translated outputs.
• Live two-way synchronization with ongoing MCP batches.
• Interactive bubble creation: Draw custom bounding boxes directly on the canvas to trigger localized OCR.
• Persistent workspace sessions saved in .manga_trans_cache/studio-workspace.json.

---

Installation

Prerequisites

• Python 3.10+
• OS: Windows / Linux / macOS
• (Optional) NVIDIA GPU with CUDA support for accelerated local OCR.

Install Dependencies

pip install -r requirements.txt

GPU Acceleration (Optional)

To enable GPU-accelerated local OCR, install PyTorch with CUDA:

# Example for CUDA 12.8:
pip install --upgrade --force-reinstall torch torchvision --index-url https://download.pytorch.org/whl/cu128

Environment variables:

• MANGA_TRANS_DEVICE=auto (Default: Uses CUDA if available, falls back to CPU)
• MANGA_TRANS_DEVICE=cpu (Forces CPU execution)
• MANGA_OCR_BATCH_SIZE=8 (Batch size for local OCR inference)

---

Quickstart

1. Launch Web Studio

Run start_app.bat (Windows) or execute:

python -m uvicorn backend.server:app --host 127.0.0.1 --port 8000 --reload

Open your browser at http://127.0.0.1:8000.

2. Configure MCP Client

Add the server definition to your MCP client configuration (claude_desktop_config.json, Antigravity, Cursor, etc.):

{
  "mcpServers": {
    "manga-trans": {
      "command": "python",
      "args": [
        "D:\\Code\\manga-trans\\backend\\mcp_server.py"
      ],
      "cwd": "D:\\Code\\manga-trans",
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1",
        "PYTHONUTF8": "1",
        "HF_HOME": "D:\\Code\\manga-trans\\.models\\huggingface",
        "MANGA_TRANS_DEVICE": "auto",
        "MANGA_OCR_BATCH_SIZE": "8"
      }
    }
  }
}

---

MCP Tools Reference

Tool	Description
manga_list_pages	Lists all image pages inside a raw chapter folder.
manga_analyze_page	Crops black borders, detects speech balloons, and runs local OCR for a single page.
manga_analyze_chapter	Processes and generates structured OCR manifests for an entire chapter batch.
manga_load_page	Returns the raw page as ImageContent for host vision inspection.
manga_render_page	Erases original text, typesets localized translations, and runs QA for a single page.
manga_render_chapter	Renders an entire chapter using a pre-built translations JSON manifest.
manga_clean_page	Erases source text and outputs inpainted images without typesetting.
manga_studio_status	Retrieves current workspace status and review queue from Web Studio.
manga_studio_show_page	Syncs and navigates the user's Web Studio view to a specific page number.
manga_list_fonts	Lists available fonts registered in the typesetting engine.

---

Directory Structure

manga-trans/
├── backend/
│   ├── engine/
│   │   ├── detector.py          # Offline bubble geometry & bounding box heuristics
│   │   ├── geometry.py          # Contour analysis, panel line rules, coordinate calculations
│   │   ├── inpainter.py         # Line-preserving text erasure & inpainting
│   │   ├── models.py            # Pydantic schemas for manifests & QA reports
│   │   ├── ocr.py               # Manga-OCR & EasyOCR wrappers
│   │   ├── pipeline.py          # End-to-end clean, OCR, and render pipeline
│   │   ├── preprocess.py        # Image normalization & black border cropping
│   │   ├── qa.py                # Strict Pixel QA algorithms
│   │   └── typesetter.py        # Typography layout, font sizing, word wrapping
│   ├── fonts/                   # Localized TrueType (.ttf) comic fonts
│   ├── mcp_server.py            # MCP Server entrypoint (JSON-RPC over stdio)
│   ├── server.py                # FastAPI REST & WebSocket backend for Web Studio
│   └── studio_workspace.py     # Persistent workspace session manager
├── frontend/
│   ├── index.html               # Web Studio Canvas App (HTML5/Canvas/CSS/JS)
│   └── sample/                  # Sample test assets
├── tests/
│   ├── render_mcp_qa.py         # Pipeline render & QA regression test
│   ├── test_mcp_server.py       # MCP Server test suite (38 unit tests)
│   └── test_studio_workspace.py # Web Studio workspace unit tests
├── .agent/
│   └── skills/
│       └── manga-translate/     # Manga translation skill for AI agents
│           └── SKILL.md
├── AGENTS.md                    # Universal CLI and agent operational instructions
├── GEMINI.md                    # Model-specific guidelines & rules
├── mcp_config.json              # Sample MCP client configuration
├── requirements.txt             # Python package dependencies
└── start_app.bat                # Windows launcher for Web Studio

---

Testing

Run the test suite to verify system integrity:

python -m unittest tests/test_studio_workspace.py
python -m unittest tests/test_mcp_server.py