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.

Related MCP server: devscope

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

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