Manga Trans Studio & MCP Server

Локальный бэкенд для сканлейта и сервер Model Context Protocol (MCP) для манги, манхвы и маньхуа.

Этот проект разделяет обязанности по локализации между AI-агентом и локальным движком:

• MCP Host (Antigravity, Cursor, Claude Desktop, Codex): Выполняет роль движка зрения и перевода, напрямую рассматривая исходные страницы через ImageContent и возвращая переводы, привязанные к неизменяемым тегам region_id.

• Local Python Backend: Отвечает за определение геометрии речевых облаков, локальный OCR (Manga-OCR / EasyOCR), контурно-зависимое удаления текста (inpainting), построение типографики с переносом слов и полной поддержкой вьетнамской диакритики, а также строгую попиксельную проверку качества.

• Studio Canvas (FastAPI Web App): Предоставляет двухпанельный интерфейс для визуальной проверки в режиме реального времени, ручной корректировки текста, обрезки речевых облаов и экспорта в PNG.

Ключевые возможности

1. Нативное для хоста видение и локализация

• Стандартная интеграция MCP: Передаёт исходные страницы манги как нативные ImageContent, чтобы модель хоста могла напрямую читать визуальные панели, эмоции персонажей и порядок чтения.

• Полностью локальная работа: На стороне сервера не требуются ключи API сторонних LLM (OpenAI, Gemini, OpenRouter).

2. Контурно-зависимый инпейнтинг (Bubble Cleaner)

• Использует анализ связных компонент и метод главных компонент (PCA) для различения символов речи от структурных линий и контуров панелей.

• Блокирует границы панелей и периметры «облаков мысли» перед инпейнтингом, предотвращая появления белых пятен или разрушение фоновой графики.

3. Автоматическая вёрстка текста в манге

• Динамический размер шрифта рассчитывается для вписывания в облака эллиптической, прямоугольной и заострённой формы.

• Интеллектуальный перенос строк с поддержкой вьетнамской диакритики и тонов без разрывов слов и отсутствующих глифов (tofu).

• Встроенные локализованные комикс-шрифты: Itim, Pangolin, Patrick Hand, Mali Bold, Bangers, Saira Condensed, Be Vietnam Pro, Chakra Petch, Comic Neue и другие.

• Обводка текста, заливка цветом, выравнивание (по центру/левому/правому краю) и стили жирный/курсив.

4. Строгая проверка целостности пикселей

Автоматическая верификация после рендера:

• box_alignment_score: Геометрическое соответствие между отрисованным текстом и целевым облаком (Целевой результат: 100).

• render_overflow_pixels и per_region_typeset_overflow_pixels: Гарантируют отсутствие выхода текста за границы допустимых областей (Целевой результат: 0).

• artwork_changes_outside_source_regions: Проверяет нулевую долю изменений пикселей за пределами речевых зон (0%).

5. Веб-студия с двойным холстом

• Сравнение исходных страниц и переведённых результатов бок о бок.

• Двусторонняя синхронизация в реальном времени с активными MCP-очередями.

• Интерактивное создание облачков: рисуйте собственные ограничительные рамки прямо на холсте, чтобы запустить локальный OCR.

• Постоянные сеансы рабочего пространства сохраняются в .manga_trans_cache/studio-workspace.json.

Related MCP server: Manga-Translation-MCP

Установка

Предварительные требования

• Python 3.10+

• ОС: Windows / Linux / macOS

• (Опционально) Видеокарта NVIDIA с поддержкой CUDA для ускорения работы локального OCR.

Установка зависимостей

pip install -r requirements.txt

Ускорение GPU (опционально)

Чтобы включить ускоренный локальный OCR, установите PyTorch с CUDA:

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

Переменные среды:

• MANGA_TRANS_DEVICE=auto (по умолчанию: использует CUDA, если доступна; иначе CPU)

• MANGA_TRANS_DEVICE=cpu (принудительное выполнение на CPU)

• MANGA_OCR_BATCH_SIZE=8 (размер батча для вывода локального OCR)

Быстрый старт

1. Запуск веб-студии

Запустите start_app.bat (Windows) или выполните:

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

Откройте браузер по адресу http://127.0.0.1:8000.

2. Настройка MCP-клиента

Добавьте описание сервера в конфигурацию вашего MCP-клиента (claude_desktop_config.json, Antigravity, Cursor и т.д.):

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

Структура каталога

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

Тестирование

Запустите набор тестов для проверки работоспособности системы:

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