Manga Trans Studio & MCP Server

Ein lokal ausgeführtes Scanlation-Backend und Model Context Protocol (MCP)-Server für Manga, Manhwa und Manhua.

Dieses Projekt teilt die Lokalisierungsaufgaben zwischen dem KI-Agenten und der lokalen Engine auf:

• MCP Host (Antigravity, Cursor, Claude Desktop, Codex): Fungiert als Vision- und Übersetzungs-Engine, untersucht Rohseiten direkt über ImageContent und liefert Übersetzungen, die an unveränderliche region_id-Tags gebunden sind.

• Lokales Python-Backend: Übernimmt Blasengeometrie-Erkennung, lokale OCR (Manga-OCR / EasyOCR), konturbewusste Textentfernung (Inpainting), typografisches Layout mit vollständiger Zeilenumbruchunterstützung für vietnamesische Diakritika sowie eine strenge Pixel-QA-Prüfung.

• Studio Canvas (FastAPI-Web-App): Bietet eine Doppel-Canvas-Oberfläche für den visuellen Seitenvergleich in Echtzeit, manuelle Textanpassungen, individuelles Zuschneiden von Sprechblasen und PNG-Export.

Hauptfunktionen

1. Host-Native Vision & Lokalisierung

• Standard-MCP-Integration: Überträgt rohe Manga-Seiten als native ImageContent, sodass das Host-Modell visuelle Panels, Emotionen der Charaktere und Lesereihenfolge direkt erfasst.

• Vollständig lokale Ausführung: Auf der Serverseite sind keine API-Schlüssel für Drittanbieter-LLMs (OpenAI, Gemini, OpenRouter) erforderlich.

2. Konturbewusstes Inpainting (Bubble Cleaner)

• Verwendet Connected-Component-Analyse und Hauptkomponentenanalyse (PCA), um Sprachglyphen von Liniengrafik und Panel-Konturen zu unterscheiden.

• Sperrt Panel-Kanten und Gedankenblasen-Konturen vor dem Inpainting, um weiße Ausläufer oder eine Zerstörung der Hintergrundgrafik zu verhindern.

3. Automatisierter Manga-Typesetter

• Dynamische Schriftgrößenberechnung für elliptische, rechteckige und spitz zulaufende Sprechblasen.

• Intelligenter Zeilenumbruch mit Unterstützung für vietnamesische Diakritika und Tonzeichen – ohne Trennungsartefakte oder fehlende Glyphen (Tofu).

• Integrierte lokalisierte Comic-Schriften: Itim, Pangolin, Patrick Hand, Mali Bold, Bangers, Saira Condensed, Be Vietnam Pro, Chakra Petch, Comic Neue und weitere.

• Textkontur, Farbfüllung, Ausrichtung (zentriert/links/rechts/rechts) sowie fett/kursive Stile.

4. Strenge Pixel-QA

Automatische Überprüfung nach dem Rendern:

• box_alignment_score: Geometrische Übereinstimmung zwischen gerendertem Text und Ziel-Sprechblase (Ziel: 100).

• render_overflow_pixels & per_region_typeset_overflow_pixels: Stellt sicher, dass kein Text außerhalb der zulässigen Grenzen abgeschnitten wird (Ziel: 0).

• artwork_changes_outside_source regions: Erzwingt 0 % Pixelveränderungen außerhalb der Sprachregionen.

5. Dual-Canvas Web-Studio

• Einseitiger Vergleich von Original-Rohseiten und übersetzten Ergebnissen.

• Live-bidirektionale Synchronisierung mit laufenden MCP-Batches.

• Interaktive Sprechblasen-Erstellung: Benutzerdefinierte Begrenzungsrahmen direkt auf die Canvas zeichnen, um lokale OCR auszulösen.

• Persistente Arbeitsbereichssitzungen, gespeichert in .manga_trans_cache/studio-workspace.json.

Related MCP server: devscope

Installation

Voraussetzungen

• Python 3.10+

• OS: Windows / Linux / macOS

• (Optional) NVIDIA-GPU mit CUDA-Unterstützung für eine beschleunigte lokale OCR.

Abhängigkeiten installieren

pip install -r requirements.txt

GPU-Beschleunigung (Optional)

Um die GPU-beschleunigte lokale OCR zu aktivieren, installieren Sie PyTorch mit CUDA:

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

Umgebungsvariablen:

• MANGA_TRANS_DEVICE=auto (Standard: Verwendet CUDA, falls verfügbar, fällt andernfalls auf CPU zurück)

• MANGA_TRANS_DEVICE=cpu (Erzwingt CPU-Ausführung)

• MANGA_OCR_BATCH_SIZE=8 (Batchgröße für die bishe lokale OCR-Inferenz)

Schnellstart

1. Web-Studio starten

Führen Sie start_app.bat (Windows) aus oder führen Sie folgenden Befehl aus:

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

Anschließend öffnen Sie http://127.0.0.1:8000 in Ihrem Browser.

2. MCP-Client konfigurieren

Fügen Sie die Serverdefinition zur MCP-Client-Konfiguration hinzu (claude_desktop_config.json, Antigravity, Cursor usw.):

{
  "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-Referenz

| manga_studio_status | Ruft Status und Überprüfungswarteschlange des jeweiligen Web-Studios ab. | | manga_studio_show_page | Synchronisiert die Web-Studio-Ansicht des Benutzers und springt zu einer bestimmten Seite. | | manga_list_fonts | Listet die in der Typesetting-Engine registrierten Schriftarten auf. |

Verzeichnisstruktur

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

Testen

Führen Sie die Testsuite aus, um die Systemintegrität zu prüfen:

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