ipe-mcp

ipe-mcp 是一个本地优先、与主机无关（host-agnostic）的 MCP 服务器，正在开发中，用于让 AI 代理创建、编辑、验证并渲染可编辑的 Ipe 文档与演示文稿。

该项目将版本化的语义文档模型与确定性的 Ipe XML 和原生 Ipe 验证相结合。其基线为 Ipe 7.2.30 和 XML 格式 70218。初始目标环境是 WSL 上的 Ubuntu 26.04。

[!IMPORTANT] 此仓库处于 MVP 之前的阶段。里程碑 M0–M3 已完成，涵盖兼容性契约、一致性实验室、语义 IR、事务持久化、坐标和布局。stdio MCP 服务器计划在 M8 交付，因此该仓库目前还不是可安装的 MCP 集成。

目标

• 为代理提供对页面、图层、视图、对象、样式、布局、逐步揭示和导出的语义操作，而无需它们去操作原始 XML；。

• 在解析、变更、保存、原生加载和恢复过程中保留编辑能力和受支持的 Ipe 内容。

• 将图层、绘制顺序和演示视图视为相互独立的数据三种概念。

• 使每次变更都具备修订安全（revision-safe）、原子、可验证、可恢复的特性。

• 通过主机中立的契约，支持 Codex 和其他 MCP 主机。

• 输出 .ipe、PDF 与光栅预览产物，并给出明确验证与兼容性诊断。

Related MCP server: Unofficial Overleaf MCP Server

当前状态

完整的范围、门禁、风险与设计决策，请参见路线图。

架构

实现围绕几个明确的边界展开：

• src/domain：语义 IR、模式、验证与稳定标识；

• src/ipe/xml：确定性解析器、投影器、写入器；

• src/persistence：有界读取、原子写入、会话、快照与 sidecar；

• src/layout：坐标空间、矩阵、锚点、约束、布局与连接器；

• fixtures/conformance：用于与原生 Ipe 对照的文档与黄金基线数据。

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、渲染与导出。

环境要求

• Node.js 20 或更高版本；

• npm；

• Ipe 7.5.30（支持完整验证路径）；

• pdfLaTeX（用于文本编译和原生渲染工作流）。

已验证的环境使用 Ubuntu 26.04 WSL 上的 Ubuntu ipe 7.2.30-1build2 软件包。请按 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 往返、语义不动点、持久化、数值行为与布局几何形状等。M1 还支持可选的源码构建通道：

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

未设置该变量时，将使用已验证的 Ubuntu 发行版软件包，可选的源码通道则会被标记为跳过（skipped）。

兼容模式

设计上区分三种显式模式：

• 仅结构（supports-only）：允许解析、检查与生成，输出结构诊断结果，但不声称原生验证；

• 完整 7.2.30：受支持的发布路径，同时进行原生校验；

• 每夜 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 特定提示词、技能或界面级指令。