Manga Trans Studio & MCP Server

Un backend de scanlation local-primero y un servidor Model Context Protocol (MCP) para Manga, Manhwa y Manhua.

Este proyecto divide las responsabilidades de localización entre el agente de IA y el motor local:

• MCP Host (Antigravity, Cursor, Claude Desktop, Codex): Actúa como el motor de visión y traducción, inspecciona directamente las páginas originales mediante ImageContent y devuelve las traducciones asociadas a las etiquetas inmutables region_id.

• Backend local de Python: Gestiona la detección de la geometría de los bocadillos, el OCR local (Manga-OCR / EasyOCR), el borrado de texto mediante inpainting sensible a los contornos, la maquetación tipográfica con saltos de línea correctos para todos los diacríticos vietnamitas y una validación estricta de QA de píxeles.

• Studio Canvas (aplicación web FastAPI): Proporciona una interfaz de doble lienzo lado a lado para la inspección visual en tiempo real, el ajuste manual de los textos, el recorte personalizado de bocadillos de diálogo y la exportación a PNG.

Funcionalidades principales

1. Visión y localización nativas del host

• Integración MCP estándar: Transmite las páginas de manga sin procesar como ImageContent nativo, de modo que el modelo anfitrión lea directamente las viñetas, las expresiones de los personajes y el orden de lectura.

• Ejecución totalmente local: No se requieren claves API de LLM de terceros (OpenAI, Gemini, OpenRouter) en el lado del servidor.

2. Inpainting sensible a los contornos (Bubble Cleaner)

• Utiliza el análisis de componentes conexos y el análisis de componentes principales (PCA) para distinguir los glifos de diálogo del dibujo de línea y los contornos de las viñetas.

• Bloquea los bordes de las viñetas y el perímetro de los bocadillos de pensamiento antes del inpainting, con lo que se evita el sangrado de blancos o la destrucción del arte de fondo.

3. Rotulador de manga automático

• Tamaño de fuente dinámico calculado para ajustarse a bocadillos elípticos, rectangulares y puntiagudos.

• Saltos de línea inteligentes con soporte para los diacríticos y tonos vietnamitas, sin cortes no deseados de palabras ni glifos ausentes (tofu).

• Fuentes de cómic integradas pensadas para la localización: Itim, Pangolin, Patrick Hand, Mali Bold, Bangers, Saira Condensed, Be Vietnam Pro, Chakra Petch, Comic Neue, entre otras.

• Trazo del texto, relleno de color, alineación (centro/izquierda/derecha) y estilos de negrita/cursiva.

4. QA de píxeles estricto

Verificación automática posterior al renderizado:

• box_alignment_score: Ajuste geométrico entre el texto renderizado y el bocadillo objetivo (Objetivo: 100).

• render_overflow_pixels y per_region_typeset_overflow_pixels: Garantizan que no haya recortes de texto fuera de los límites permitidos (Objetivo: 0).

• artwork_changes_outside_source_regions: Exige que no se produzcan alteraciones de píxeles en las zonas fuera de las regiones de diálogo.

5. Estudio de doble lienzo

• Comparación lado a lado de las páginas originales y las salidas traducidas.

• Sincronización bidireccional en tiempo real con los lotes MCP en curso.

• Creación interactiva de bocadillos: Dibuja cuadros delimitadores personalizados directamente en el lienzo para activar el OCR local.

• Sesiones de trabajo persistentes guardadas en .manga_trans_cache/studio-workspace.json.

Related MCP server: Manga-Translation-MCP

Instalación

Requisitos previos

• Python 3.10 o posterior.

• Sistemas operativos: Windows / Linux / macOS

• (Opcional) GPU NVIDIA con soporte para CUDA para acelerar el OCR local.

Instalar las dependencias

pip install -r requirements.txt

Aceleración por GPU (opcional)

Para habilitar el OCR local acelerado por tarjeta gráfica, instala PyTorch con CUDA:

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

Variables de entorno:

• MANGA_TRANS_DEVICE=auto (Por defecto: Utiliza CUDA si está disponible; si no, usa la CPU)

• MANGA_TRANS_DEVICE=cpu (Fuerza la ejecución con la CPU)

• MANGA_OCR_BATCH_SIZE=8 (Tamaño del lote para la inferencia de OCR local)

Inicio rápido

1. Crear el Estudio

Ejecuta start_app.bat (Windows) o el siguiente comando:

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

Abre tu navegador en http://127.0.0.1:8000.

2. Configurar el cliente MCP

Añade la definición del servidor a la configuración de tu cliente MCP (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"
      }
    }
  }
}

Referencia de herramientas MCP

Estructura de directorios

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

Pruebas

Ejecuta el conjunto de pruebas para comprobar la integridad del sistema:

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