ipe-mcp

ipe-mcp는 AI 에이전트를 통해 편집 가능한 Ipe 문서와 프레젠테이션을 생성, 편집, 검증, 렌더링하기 위해 개발 중인 로컬 우선(local-first) 호스트 무관(host-agnostic) MCP 서버입니다.

이 프로젝트는 버전이 지정된 시맨틱 문서 모델과 결정적 Ipe XML 및 네이티브 Ipe 검증을 결합합니다. 기준은 Ipe 7.2.30 및 XML 형식 70218입니다. 초기 대상 환경은 WSL의 Ubuntu 26.04입니다.

[!IMPORTANT] 이 저장소는 MVP 이전 단계입니다. M0–M3 마일스톤은 완료되어 호환성 계약, 적합성 검증소, 시맨틱 IR, 트랜잭션 영속화, 좌표 및 레이아웃을 다룹니다. stdio MCP 서버는 M8에 계획되어 있으므로 이 저장소는 아직 설치 가능한 MCP 통합이 아닙니다.

목표

• 에이전트가 원시 XML을 직접 다루지 않아도 되도록 페이지, 레이어, 뷰, 객체, 스타일, 레이아웃, 리빌(reveal) 및 내보내기에 대한 시맨틱 연산을 사용한다.

• 파싱, 변경, 저장, 네이티브 재로드, 복구 과정에서도 편집 가능성과 지원되는 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 대신 타이핑된 문서 연산을 노출합니다. 스타일 해석, LaTeX, 렌더링, 내보내기 등 구조적으로 검증할 수 없는 동작에 대해서는 네이티브 Ipe 도구가 권위를 가집니다. 키 소스 영역:

• src/domain: 시맨틱 IR, 스키마, 검증 및 안정적 식별자\

• src/ipe/xml: 결정적 파서, 프로젝터 및 직렬화\

• src/persistence: 제한된 읽기, 원자적 쓰기, 시스템, 스냅샷 및 사이드카\

• src/layout: 좌표 공간, 행렬, 앵커, 제약, 레이아웃 및 커넥터\

• fixtures/conformance: 네이티브 Ipe 대상으로 사용되는 문서 및 골든 데이터.

개발 설정

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 지시와 독립성을 유지한다.