ipe-mcp

ipe-mcp es un servidor MCP local-first, independiente del host, en desarrollo para crear, editar, validar y renderizar documentos y presentaciones editables de Ipe a través de agentes de IA.

El proyecto combina un modelo de documento semántico versionado con XML determinista de Ipe y validación nativa de Ipe. Su línea base es Ipe 7.2.30 y el formato XML 70218. El entorno inicial previsto es Ubuntu 26.04 en WSL.

[!IMPORTANT] Este repositorio es pre-MVP. Los hitos M0–M3 están completos y cubren los contratos de compatibilidad, el laboratorio de conformidad, el IR semántico, la persistencia transaccional, las coordenadas y la maquetación. El servidor stdio MCP está previsto para M8, por lo que el repositorio no es todavía una integración MCP instalable.

Objetivos

• Ofrecer a los agentes operaciones semánticas para páginas, capas, vistas, objetos, estilos, maquetación, revelados y exportación sin que deban manipular XML arbitrario.

• Preservar la editabilidad y el contenido de Ipe admitido durante el análisis, la mutación, el guardado, la recarga nativa y la recuperación.

• Mantener capas, orden de dibujo y vistas de presentación como conceptos separados.

• Hacer que cada mutación sea segura frente a revisiones, atómica, validada y recuperable.

• Soportar Codex y otros hosts MCP mediante contratos neutrales respecto al host.

• Producir artefactos .ipe, PDF y vistas previas rasterizadas con validación explícita y diagnósticos de compatibilidad.

Related MCP server: docx-mcp-server

Estado actual

Consulta la hoja de ruta para conocer el alcance completo, los controles, los riesgos y las decisiones de diseño.

Arquitectura

La implementación se organiza alrededor de unos límites estrictos:

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

La API normal expondrá operaciones de documento tipadas en lugar de XML arbitrario. Las herramientas nativas de Ipe siguen siendo la autoridad para los comportamientos que no pueden validarse estructuralmente, incluyendo la resolución de estilos, LaTeX, el renderizado y la exportación.

Principales áreas de código:

• src/domain: IR semántico, esquemas, validación e identidades estables;

• src/ipe/xml: analizador determinista, proyector y serializador;

• src/persistence: lecturas acotadas, escrituras atómicas, sesiones, instantáneas y sidecars;

• src/layout: espacios de coordenadas, matrices, anclas, restricciones, maquetación y conectores;

• fixtures/conformance: documentos y datos golden usados contra Ipe nativo.

Requisitos

• Node.js 20 o posterior;

• npm;

• Ipe 7.2.30 para la ruta de validación completa;

• pdfLaTeX para compilación de texto y flujos de renderizado nativo.

El entorno verificado usa el paquete ipe 7.2.30-1build2 de Ubuntu en Ubuntu 26.04 WSL. Siga SETUP-WSL.md./SETUP-WSL.md para instalar y comprobar las herramientas nativas.

Configuración de desarrollo

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

El paquete es actualmente privado y no tiene ejecutable publicado ni punto de entrada de servidor MCP.

Verificación

Ejecuta los controles de hito desde la raíz del repositorio:

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

Los controles se apoyan unos sobre otros y cubren comprobaciones estructurales, ciclos de ida y vuelta con Ipe nativo, puntos fijos semánticos, persistencia, comportamiento numérico y fixtures de maquetación. M1 proporciona también una vía opcional de compilación desde el código fuente:

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

Sin esa variable, se usa el paquete Ubuntu verificado y la vía opcional se registra como omitida.

Modos de compatibilidad

El diseño distingue tres modos explícitos:

• solo estructural: analizar, inspeccionar y generar con diagnostics estructurales, sin reclamar verificación nativa;

• completo 7.2.30: la ruta de lanzamiento soportada con validación nativa;

• nocturno 7.3.x: compatibilidad experimental, nunca se usa para reescribir un documento estable sin consentimiento.

Consulte docs/compatibility-modes.md para ver la matriz exacta de capacidades y fallos.

Documentación

• ROADMAP.md: arquitectura, hitos, controles y trabajo futuro;

• docs/adr: decisiones de arquitectura aceptadas;

• docs/conformance-m1.md: laboratorio de conformidad nativo;

• docs/core-m2.md: IR semántico, XML, identidad y persistencia;

• docs/core-m3.md: coordenadas y maquetación;

• report-source.md: expediente de código y trazabilidad;

• ORCHESTRATOR_PROMPT.md: protocolo de ejecución y revisión de hitos.

Principios del proyecto

• No mutar nunca el documento original antes de un guardado explícito.

• Tratar explícitamente cada capa de objetos de nivel superior y cada configuración por defecto sensible a la serialización.

• Content semántico y con Ipe nativo; que un fichero se abra no es un control suficiente.

• Preserve el contenido desconocido no admitido cuando sea posible; e informar de cualquier comportamiento degradado.

• Mantener los contratos de protocolo independientes de los prompts, habilidades o directivas de interfaz específicos de Codex.