ipe-mcp

ipe-mcp は、AIエージェントを介して編集可能な Ipe ドキュメントとプレゼンテーションを作成、編集、検証、レンダリングするための、開発中のローカルファーストかつホスト非依存のMCPサーバーです。

このプロジェクトは、バージョン管理されたセマンティックドキュメントモデルと、決定論的なIpe XML、ネイティブなIpe検証を組み合わせています。ベースラインは Ipe 7.2.30 と XML フォーマット 70218 です。最初のターゲット環境は WSL 上の Ubuntu 26.04 です。

[!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: 制限付き読み取り、アトミック書き込み、セッション、スナップショット、サイドカー

• src/layout: 座標空間、行列、アンカー、制約、レイアウト、コネクタ

• fixtures/conformance: ネイティブIpeに対して使用するドキュメントとゴールデンデータ

要件

• Node.js 20 以上;

• npm;

• サポートされる完全検証パスには Ipe 7.2.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 パッケージが使用され、オプションのソースパッケージはスキップされたと報告されます。

互換性モード

設計では、次の3つの明確なモードを区別しています。

• 構造のみ: 構造診断を伴う解析・検査・生成を行い、ネイティブ検証を標榜しません;

• フル 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 固有のプロンプト、スキル、UI ディレクティブから独立して保つ。