ipe-mcp

ipe-mcp — локальный, не зависящий от хоста MCP-сервер в разработке для создания, редактирования, валидации и рендеринга редактируемых документов и презентаций Ipe через ИИ-агентов.

Проект объединяет версионируемую семантическую модель документа с детерминированным Ipe XML и нативной валидацией Ipe. Базовая версия — Ipe 7.2.30 и формат XML 70218. Первоначальная целевая среда — Ubuntu 26.04 в WSL.

[!IMPORTANT] Этот репозиторий находится на стадии до MVP. Вехи M0–M3 завершены и охватывают контракты совместимости, лабораторию конформности, семантический IR, транзакционное хранение, координаты и компоновку. stdio MCP-сервер запланирован на M8, поэтому репозиторий ещё не является устанавливаемой MCP-интеграцией.

Цели

• Предоставлять агентам семантические операции со страницами, слоями, видами, объектами, стилями, компоновкой, раскрытием и экспортом без необходимости работать с сырым XML.

• Сохранять редактируемость и поддерживаемое содержимое Ipe при разборе, изменении, сохранении, нативной перезагрузке и восстановлении.

• Держать слои, порядок отрисовки и виды презентации как раздельные понятия.

• Обеспечивать безопасность ревизий, атомарность, валидацию и восстановимость каждой операции изменения.

• Поддерживать Codex и другие MCP-хосты через не зависящие от хоста контракты.

• Создавать артефакты .ipe, PDF и растровых предпросмотров с явной валидацией и диагностикой совместимости.

Related MCP server: Unofficial Overleaf MCP Server

Текущее состояние

Полный объём, критерии приёмки, риски и проектные решения — в дорожной карте.

Архитектура

Реализация построена вокруг нескольких строгих границ:

Agent or MCP host
        |
        v
Semantic operations and layout
        |
        v
Versioned document IR
        |
        +--> transactional session and sidecar
        |
        v
Deterministic Ipe XML codec
        |
        v
Ipe 7.2.30 native validation, rendering, and export

Обычный API будет предоставлять типизированные операции с документами, а не произвольный XML. Нативные инструменты Ipe остаются авторитетом для поведений, которые нельзя проверить структурно, включая разрешение стилей, LaTeX, рендеринг и экспорт.

Ключевые области кода:

• src/domain: семантический IR, схемы, валидация и устойчивые идентификаторы;

• src/ipe/xml: детерминированный парсер, проектор и сериализатор;

• src/persistence: ограниченные чтения, атомарные записи, сессии, снапшоты и sidecar-файлы;

• src/layout: координатные пространства, матрицы, якоря, ограничения, компоновка и соединители;

• fixtures/conformance: документы и эталонные данные для проверки против нативного Ipe.

Требования

• Node.js версии 20 или новее;

• npm;

• Ipe 7.2.30 для полного пути валидации;

• pdfLaTeX для компиляции текста и рабочих процессов нативного рендеринга.

Проверенная среда использует пакет Ubuntu ipe 7.2.30-1build2 на Ubuntu 26.04 WSL. Инструкции по установке и проверке нативных инструментов — в SETUP-WSL.md.

Настройка разработки

git clone https://github.com/Mik1810/ipe-mcp.git
cd ipe-mcp
npm ci
npm run build
npm test

Пакет сейчас приватный: опубликованного исполняемого файла или точки входа MCP-сервера нет.

Проверка

Запустите контрольные точки вех из корня репозитория:

bash scripts/check-m0.sh
bash scripts/check-m1.sh
bash scripts/check-m2.sh
bash scripts/check-m3.sh

Контрольные точки построены на основе друг друга и охватывают структурные проверки, нативные Ipe round-trip сценарии, семантические фиксированные точки, персистентность, числовое поведение и компоновочные фикстуры. M1 также поддерживает опциональный путь сборки из исходного кода:

IPE_M1_SOURCE_BIN_DIR=/path/to/ipe/build/bin bash scripts/check-m1.sh

Без этой переменной используется проверенный пакет Ubuntu, а необязательный исходный путь помечается как пропущенный.

Режимы совместимости

В проекте выделяются три явных режима:

• structural-only: разбор, просмотр и генерация со структурной диагностикой, без заявления о нативной проверке;

• full 7.2.30: поддерживаемая релизная версия с нативной валидацией;

• nightly 7.3.x: экспериментальная совместимость; никогда не используется для перезаписи стабильного документа без явного согласия.

Точная матрица возможностей и ошибок — в docs/compatibility-modes.md.

Документация

• ROADMAP.md: архитектура, вехи, контрольные точки и будущие работы;

• docs/adr: принятые архитектурные решения;

• docs/conformance-m1.md: лаборатория нативного соответствия;

• docs/core-m2.md: IR, XML, идентичность и персистентность;

• docs/core-m3.md: координаты и компоновка;

• report-source.md: досье исходного кода и трассируемость;

• ORCHESTRATOR_PROMPT.md: протокол выполнения вех и ревью.

Принципы проекта

• Не изменяйте исходный документ до явного сохранения.

• Явно обрабатывайте каждый слой объектов верхнего уровня и каждый чувствительный к сериализации параметр по умолчанию.

• Проверяйте документ семантически и с помощью нативного Ipe; того, что файл просто открылся, недостаточно.

• Сохраняйте любое неизвестное поддерживаемое содержимое, когда это возможно, и сообщайте о любой деградации поведения.

• Держите контракты протокола независимыми от специфичных для Codex промптов, навыков или директив UI.