HWPX Document Plugin

imagePython 3.10+ imageMCP 1.27+ imageAgent Plugins 1.0.0 imageLicense: MIT

HWPX 문서를 안전하게 분석·수정·검증하기 위한 Agent Plugin 프로젝트입니다.

“이 신청서 채워줘”라는 요청을, 승인과 검증을 거친 HWPX 수정본으로 연결합니다.

신청서·행정 서식은 내용을 채우면서도 기존 표, 고정 문구, 입력 칸을 유지해야 합니다. 이 프로젝트는 문서를 필드 단위로 분석하고, 대화로 값을 수집한 뒤 수정 계획 확인 → 사용자 승인 → 편집 → 렌더링·Vision 검토를 하나의 작업 흐름으로 제공합니다.

현재 상태: MCP 핵심 기반, 텍스트·글자 서식 편집, Codex 작업 Skill을 구현했습니다. 이미지 삽입·전자서명 배치는 개발 예정이며, Web/App 화면은 실험·검증 단계입니다. 레거시 .hwp 직접 편집은 지원하지 않습니다.

Python · FastMCP · Rust/rhwp · PyO3 · SQLite

사용 예시 · 기술적 해결 · 구현 근거 · 기여 범위 · 실행하기

사용 예시

신청서의 이름·날짜·체크박스를 채우고 일부 글자 서식을 바꾸는 요청을 예로 들면 다음과 같습니다. 아래는 사용 흐름 설명이며, 녹화된 시연이나 특정 문서의 실행 결과는 아닙니다.

이 신청서에 이름은 홍길동으로 입력해줘. 필요한 정보는 나눠서 질문하고, 제목은 굵게 표시해줘. 수정 계획을 먼저 보여주고 내 승인 후 적용해줘.

사진 삽입과 서명 이미지 배치는 아직 지원하지 않습니다. 현재의 서명 자리 입력은 텍스트 편집 기능입니다.

핵심 문제와 기술적 해결

구현을 확인하려면

• 편집과 최종화: 워크플로 회귀 테스트는 날짜·금액·글자 칸 입력, anchor 검사, 원본 복사와 Vision PASS 이후 최종화를 다룹니다.
• 중단과 복구: 생명주기 테스트와 공개 MCP 경계 테스트에서 상태 전이와 도구 경계를 확인할 수 있습니다.
• 글자 서식과 렌더링: 서식 테스트, 렌더러 테스트, 실제 문서 엔진 통합 테스트가 있습니다. 실제 문서 검증은 별도 샘플 설정이 필요합니다.

이 링크는 구현·검증 범위를 확인하기 위한 근거입니다. 모든 서식과 클라이언트의 지원을 의미하지 않으며, 문서별 시각적 품질은 실제 결과 검토가 필요합니다.

이 프로젝트는 공동 개발했습니다. 박태정의 MCP 고도화·엔진 통합·워크플로·필드·서식·Skill 작업과 안주현의 플러그인 패키징·첨부 수신·Web/App 작업은 기여 범위와 변경 이력에 연결했습니다. rhwp 엔진 자체는 외부 오픈소스이며, 이 저장소의 기여는 해당 엔진을 HWPX 작업 흐름에 통합하는 것입니다.

동작 구조

에이전트가 Skill을 읽고 작업 순서를 판단하면, MCP 도구가 입력·승인·검증 조건을 확인하며 문서 작업을 실행합니다. MCP 서버 안에 별도의 LLM을 등록해 편집을 판단하는 구조는 아닙니다.

flowchart LR
    A["사용자 요청"] --> B["Codex 에이전트 + Skill"]
    B --> C["MCP 도구 · 분석과 인터뷰"]
    C --> D["Edit Plan · 사용자 승인"]
    D --> E["Python 편집 서비스 · 격리 수정본"]
    E --> F["Rust rhwp · 렌더링과 진단"]
    F --> G["구조 비교 · PNG diff · Vision 검토"]
    G --> H["검증 통과 후 최종본"]

• Skill은 판단 절차를 안내합니다. 최상위 라우터가 양식 채우기, 서식, 검증, 이미지 작업의 전용 Skill로 연결합니다. 이미지 Skill의 절차가 있어도 미구현 이미지 연산을 실행할 수 있는 것은 아닙니다.
• Python 서비스가 문서를 수정합니다. 지원되는 typed operation으로 ZIP/XML을 편집하고 승인 영수증, 원본 지문, 작업 상태를 검증합니다. 에이전트의 직접 XML 수정은 작업 절차에서 금지합니다.
• Rust 엔진이 렌더링과 진단을 제공합니다. PyO3로 rhwp를 같은 프로세스에서 호출하고 SVG 문자열을 메모리에서 PNG로 변환합니다. 제품 MCP 렌더링에는 외부 rhwp CLI나 필수 중간 SVG 파일이 필요하지 않습니다. Vision 판정은 MCP Sampling 또는 호스트의 이미지 검토를 사용합니다.

엔진 버전과 책임 경계는 인프로세스 통합 ADR에 기록합니다. 브라우저 WASM 실험은 기본 Python 편집 경로와 별도로 관리합니다.

현재 범위

2026-09-13 기준입니다. 구현됨은 코드와 관련 회귀 테스트가 존재한다는 뜻입니다. 모든 HWPX 양식이나 클라이언트에서 동일한 결과를 보장하는 지원 선언은 아닙니다.

안전장치와 제한사항

• 원본 보존: 원본을 덮어쓰지 않고 격리된 작업공간에 수정본을 생성합니다. 허용 문서 경로 밖의 접근을 제한합니다.
• 승인된 변경만 적용: Plan 지문에 결합한 HMAC-SHA256 승인 영수증과 사전조건을 검증합니다. Skill의 안내와 서버가 강제하는 검증은 서로 다른 역할입니다.
• 레이아웃 확인: 입력 전 맞춤 추정, 수정 후 렌더링 진단·비교와 Vision 검토를 사용합니다. 넘침 기본 정책은 거부이며 줄바꿈·축소는 지원 범위와 명시된 정책 안에서만 적용합니다.
• 제한된 복구: 동일 idempotency key의 완료 결과를 재사용하고 중단된 분석을 재시도할 수 있습니다. 계획·승인·적용·최종화의 자동 재실행은 지원하지 않으며 게시 무결성 위반은 단순 재개로 해제하지 않습니다.
• 반복 양식: 검증된 renderer 정보와 진단 근거를 포함한 v2 프로필을 재사용합니다. 프로필에는 사용자 입력값을 저장하지 않으며, 적중해도 편집 승인과 적용 후 검증은 생략하지 않습니다.

서명 키를 삭제하면 기존 승인 영수증을 검증할 수 없습니다. 키를 저장소 설정 파일이나 커밋에 넣지 마세요. MCP와 호스트 사이에는 텍스트·편집값·검토 이미지가 전달될 수 있으므로 모든 데이터가 기기 안에만 머무른다고 보장하지 않습니다.

레거시 HWP 직접 편집, 범용 문서 생성, 자유 배치 편집기, 사진·서명 이미지 삽입은 지원 범위에 포함되지 않습니다. 한컴오피스와의 완전한 렌더링 일치 및 모든 운영체제·클라이언트의 E2E 호환성도 보장하지 않습니다. 공개 SaaS 운영과 사전 빌드 배포물의 정식 제공은 아직 없습니다.

Web/App 실험 상태

브라우저 실험은 문서 열기, 제한된 필드 수정, export와 재열기를 검증합니다. Desktop WebMCP는 브라우저 DocumentSession을, Apps workspace는 서버 렌더러와 기존 승인 기반 서비스를 사용합니다.

WASM/native export에서 보고되지 않는 ZIP 항목 손실을 재현했고, 실험 경로에는 독립 보존 검사와 제한된 원본 컨테이너 재조립을 추가했습니다. 전체 제품 편집 경로의 호환성 검증 완료를 뜻하지는 않습니다.

Apps workspace 코드는 main에 있지만 실제 ChatGPT 호스트의 iframe 유지·페이지 전환·승인 흐름 검증은 남아 있습니다. 페이지 응답 지연 로드 개선은 PR #28에서 검토 중이며, 전체 문서 렌더링 시간 자체를 없애는 변경은 아닙니다. 상세 근거는 호스트 검증 보고서를 참고하세요.

로드맵

2026-09-13 기준 구현·이슈 상태입니다. 마일스톤 종료나 정식 릴리스와는 구분합니다.

현재 개발 초점은 HWPX 편집 기능과 실제 사용 환경 검증입니다.

전체 이슈 · 마일스톤

빠른 시작

현재 기본 경로는 저장소 소스를 빌드해 로컬 stdio MCP로 연결하는 방식입니다. 저장소가 비공개이므로 접근 권한이 필요합니다.

1. 소스 설치

Python 3.10 이상, uv, Rust 1.93.1과 운영체제의 네이티브 빌드 도구가 필요합니다. Maturin은 빌드 설정에 포함되어 있으며 별도 rhwp CLI 설치는 필요하지 않습니다.

git clone https://github.com/taejung3852/hwpx-document-plugin.git
cd hwpx-document-plugin
uv sync

2. 실행 진입점 확인

uv run hwp-editor-plugin

최초 실행 시 허용 문서 폴더와 로컬 서명 키를 자동 준비하고 stdio MCP 요청을 기다립니다. 웹 화면을 여는 명령이 아니므로 웹 주소가 출력되지 않아도 정상입니다. 직접 실행 확인을 마쳤으면 Ctrl+C로 종료합니다.

데이터 경로는 PLUGIN_DATA를 우선 사용합니다. 설정하지 않으면 Windows의 %LOCALAPPDATA%/hwpx-document-plugin, Unix의 $XDG_DATA_HOME/hwpx-document-plugin 또는 ~/.local/share/hwpx-document-plugin을 사용합니다. 그 아래 documents가 기본 문서 폴더이며 secrets/signing-key.json에 서명 키를 저장합니다.

3. MCP 연결 후 첫 분석

클라이언트의 stdio MCP 설정에 다음 실행 정보를 등록합니다. 경로는 실제 저장소와 문서 폴더의 절대 경로로 바꿉니다. 이는 MCP 서버 연결 설정이며, Skill까지 설치하는 플러그인 패키지 등록과는 별개입니다.

{
  "mcpServers": {
    "hwpx-document": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/hwpx-document-plugin", "hwp-editor-plugin"],
      "env": {
        "HWP_MCP_ROOT": "/absolute/path/to/documents"
      }
    }
  }
}

실제 설정 파일 형식은 클라이언트에 따라 다릅니다. 저장소에는 휴대형 plugin.json·mcp.json, Codex용 .codex-plugin/plugin.json·.mcp.json, 작업 Skill이 포함되어 있습니다.

허용 문서 폴더에 유효한 HWPX 파일을 넣고 연결된 에이전트에 파일의 실제 절대 경로와 함께 요청합니다.

이 HWPX 문서를 수정하지 말고 구조와 입력 가능한 항목을 분석해줘. 항목이 많으면 나눠서 보여줘.

연결이 정상이라면 문서 검사·분석 도구가 실행되고 본문·표·필드 정보 또는 추가 확인이 필요한 상태가 반환됩니다. 필드 매핑이 불확실한 NEEDS_HUMAN은 사람이 확인해야 하는 결과이며 편집 성공을 뜻하지 않습니다.

그다음 필요한 값을 제공하고 진행합니다.

이름은 홍길동으로 입력하고, 나머지 필요한 정보는 질문해줘. 수정 계획을 먼저 보여주고 내 승인 후 적용해줘. 수정 전후 이미지도 검토해줘.

완료 기준은 검증된 최종본 경로와 최종 상태입니다. 승인 또는 Vision 검토 기능을 제공하지 못하는 호스트에서는 해당 단계가 완료되지 않을 수 있습니다. 클라이언트별 전체 호환성 검증은 #4에서 추적합니다.

개발과 상세 문서

uv run pytest -q

테스트는 네이티브 빌드 환경이 필요하며 실제 문서·wheel·외부 실행 환경에 의존하는 검증은 별도 조건을 요구할 수 있습니다.

• 개발 환경과 기술 구조
• Rust 엔진 통합 ADR
• MCP 도구 정의, HTTP Control Plane
• 최상위 라우터, 양식, 서식, 검증
• WASM 검증·제약 보고서

라이선스

MIT. 포함된 Rust 의존성의 라이선스와 고지는 THIRD_PARTY_NOTICES.md에 기록합니다.