Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

MCP 서버 레퍼런스

hwpforge-mcp는 HwpForge의 MCP 서버입니다. Claude Code 같은 MCP 지원 AI 도구가 한글 문서를 직접 만들고 읽고 편집할 수 있도록 도구 19개, 리소스 4개, 프롬프트 3개를 노출합니다. 이 장의 이름과 매개변수는 crates/hwpforge-bindings-mcp/src의 정의에서 옮겼습니다.

모든 도구는 { data, summary, next } 3층 출력 형식을 씁니다. 파일은 대부분 경로로 주고받으며(예외: hwpforge_convert는 is_file: false로 Markdown을 인라인으로 받고, hwpforge_to_json은 output_path 없이 JSON을 인라인으로 돌려주고, hwpforge_diff는 output_path 없이 보고서를 인라인으로 돌려주며, hwpforge_from_json은 JSON을 structure 문자열로 받습니다), 실패는 오류 응답(CallToolResult::error)으로 돌아옵니다.

등록

npm (권장, Rust 툴체인 불필요)

npx -y가 플랫폼에 맞는 바이너리를 내려받습니다.

# 현재 프로젝트에서만
claude mcp add hwpforge -- npx -y @hwpforge/mcp

# 모든 프로젝트에서 (user 범위)
claude mcp add --scope user hwpforge -- npx -y @hwpforge/mcp

프로젝트 루트의 .mcp.json에 직접 적어도 됩니다.

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

Claude Code의 MCP 서버는 claude mcp add 또는 .mcp.json으로 등록합니다. .claude/settings.json에 적어도 MCP 서버로 읽히지 않습니다.

Cargo

cargo install hwpforge-bindings-mcp
claude mcp add hwpforge hwpforge-mcp

crates.io 패키지 이름은 hwpforge-bindings-mcp이고 설치되는 바이너리 이름은 hwpforge-mcp입니다([[bin]] name = "hwpforge-mcp").

npm 패키지 구성

@hwpforge/mcp는 플랫폼별 패키지를 optionalDependencies로 가진 기본 패키지입니다. 플랫폼 패키지는 .github/workflows/npm-publish.yml의 빌드 매트릭스와 같은 다섯 개입니다.

플랫폼 패키지 접미사Rust 타깃
darwin-arm64aarch64-apple-darwin
darwin-x64x86_64-apple-darwin
linux-x64x86_64-unknown-linux-gnu
linux-arm64aarch64-unknown-linux-gnu
win32-x64x86_64-pc-windows-msvc

패키지 이름은 @hwpforge/mcp-<접미사> 형태입니다. 게시는 npm Trusted Publishing(OIDC)만 씁니다.

도구

표의 (.hwpx)는 그 output_path가 .hwpx로 끝나야 한다는 표시입니다. 이 확장자 검사는 hwpforge_convert·hwpforge_from_json·hwpforge_restyle·hwpforge_fill·hwpforge_set_cell·hwpforge_patch·hwpforge_stamp에 있고, hwpforge_insert_para·hwpforge_delete_para에는 없습니다. hwpforge_to_json의 output_path는 .json으로 끝나야 합니다.

만들기 · 변환

도구용도매개변수
hwpforge_convertMarkdown을 HWPX로 변환합니다markdown(파일 경로 또는 인라인 내용), is_file(기본 true), output_path(.hwpx), preset(기본 default)
hwpforge_to_jsonHWPX를 편집용 JSON으로 내보냅니다file_path, section(선택, 0부터), output_path(선택, .json으로 끝나야 함, 없으면 JSON을 응답에 인라인으로 돌려줌)
hwpforge_from_jsonJSON(ExportedDocument 스키마)으로 HWPX를 직접 만듭니다structure(JSON 문자열), output_path(.hwpx)
hwpforge_to_mdHWPX를 Markdown으로 변환합니다file_path, output_dir(선택, 기본값은 입력과 같은 디렉터리)
hwpforge_restyle기존 HWPX에 다른 스타일 프리셋을 적용합니다file_path, preset, output_path(.hwpx)
hwpforge_templates스타일 프리셋 목록을 돌려줍니다name(선택, 프리셋 이름 필터)

hwpforge_to_json의 인라인 응답은 직렬화된 응답이 1 MB 미만일 때만 가능하며, 더 큰 내보내기는 OUTPUT_TOO_LARGE로 거부되므로 output_path를 주세요. 전체 문서 내보내기는 hwpforge_from_json이, section을 준 내보내기는 hwpforge_patch가 읽습니다.

MCP hwpforge_from_json이나 Markdown으로 HWPX를 재생성할 때 원본 패키지의 서명·암호화 상태는 승계되지 않습니다.

읽기 · 검사

도구용도매개변수
hwpforge_inspect섹션·문단·표·이미지·차트·머리글/바닥글·쪽번호 개수와 디코드 경고를 돌려줍니다file_path, styles(예약 필드, 현재 무시됨)
hwpforge_outline제목, 표, 이름 있는 누름틀, 책갈피의 내비게이션 맵file_path
hwpforge_fields누름틀의 이름, 힌트, 현재 값, 채울 수 있는지 여부file_path
hwpforge_read문단 범위, 표 격자, 필드 중 하나만 텍스트로 읽습니다file_path, section, paras("A..B" 또는 "N"), table, field — section/table/field 중 정확히 하나
hwpforge_diff두 HWPX를 semantic·package 두 채널로 비교합니다base_path, revised_path, output_path(선택, 보고서가 인라인 1 MB를 넘으면 필수)
hwpforge_validateHWPX 구조와 무결성을 검사합니다file_path

hwpforge_validate는 디코드할 수 없는 HWPX를 “유효하지 않은 문서” 판정이 아니라 DECODE_FAILED 오류로 알립니다. HWP5(.hwp)는 HWP5_INPUT입니다. MCP는 자동 변환하지 않으므로 CLI hwpforge convert-hwp5 <in.hwp> -o <out.hwpx> 또는 Python convert_hwp5로 먼저 변환하세요.

편집

도구용도매개변수
hwpforge_fill이름 있는 누름틀을 이름→값 맵으로 채웁니다(전부 성공하거나 전부 취소)file_path, values(이름→값 맵), output_path(.hwpx)
hwpforge_set_cell표 셀을 논리 격자 주소로 편집합니다file_path, specs(셀 명세 배열: 표 순번 + at {row,col} / right_of / below + text), output_path(.hwpx)
hwpforge_patch섹션 하나를 편집한 JSON으로 교체합니다(텍스트 전용)base_path, section, section_json_path, output_path(.hwpx)
hwpforge_insert_para기준 문단 앞뒤에 새 최상위 문단을 삽입합니다file_path, section, anchor, before(기본 false), text 또는 texts 중 정확히 하나, output_path
hwpforge_delete_para최상위 본문 문단을 인덱스로 삭제합니다file_path, section, indices, output_path
hwpforge_stamp_plan자리표시자 후보를 찾습니다file_path
hwpforge_stamp승인된 명세로 자리표시자를 누름틀로 승격합니다file_path, specs(텍스트 명세), cells(셀 명세), source_sha256(cells를 쓰면 필수), output_path(.hwpx), manifest_path(기본 <output>.manifest.json)

전자서명·암호화 표지가 있는 문서는 편집할 수 없으며, 이 거부 오류는 decode 단계의 DECODE_FAILED로 보고됩니다.

편집 도구의 동작 규칙은 CLI 레퍼런스의 대응하는 명령(예: hwpforge_insert_para는 insert-para)과 같습니다. 주의할 점은 다음과 같습니다.

  • hwpforge_patch는 문단 구조를 바꾸지 못합니다. 의미 텍스트 슬롯의 개수나 경로가 다르면 거부되며, 문단 추가·삭제는 hwpforge_insert_para·hwpforge_delete_para, 표 셀은 hwpforge_set_cell, 구조가 바뀐 문서 재구성은 hwpforge_from_json을 씁니다.
  • hwpforge_delete_para: 한컴 저장 HWPX에서도 검증 가능한 최상위 본문 평문·빈 문단을 삭제할 수 있습니다. 문단 번호는 입력 문서의 위치 기준입니다. 원문 보존 경로는 한 요청에 한 문단을 받아 대상 문단만 제거하며, 생존 문단의 줄 조판 캐시·표 높이·ID와 관련 없는 부속 데이터를 유지합니다. 위치에 따라 줄 폭이 바뀔 수 있는 문서는 원래 admission 오류로 거부합니다. 기존 Preview와 관련 연결은 제거하고 PREVIEW_REMOVED를 알립니다. 한컴에서 다시 저장하면 미리보기가 만들어집니다. 검증할 수 없는 입력은 기존 오류로 거부하며 출력하지 않습니다.
  • hwpforge_insert_para·hwpforge_stamp와 보존 범위 밖 hwpforge_set_cell은 왕복 안전한 입력만 편집합니다. 인코더가 ZIP 엔트리를 모두 실어 보낼 수 없는 문서, 곧 한컴이 저장하며 Preview/*와 META-INF/container.rdf를 더한 문서는 거부됩니다. 이런 문서에도 hwpforge_to_json + hwpforge_patch(텍스트)와 hwpforge_fill(누름틀)은 쓸 수 있습니다.
  • hwpforge_stamp는 hwpforge_stamp_plan이 준 후보 객체를 그대로 복사해 action({"field":{"name":"…"}} 또는 "ignore")만 더합니다. 지침 문맥의 후보는 자동 적용되지 않습니다.

요청한 모든 칸이 본문 직속 표의 한 문단·한 텍스트 run(빈 run 포함)이고 원문 위치와 header 보존을 확인할 수 있으면 텍스트 슬롯만 바꿉니다. 문단·표 속성과 슬롯 밖 미해석 원문은 유지합니다. 실제 값이 바뀌면 기존 Preview와 연결을 제거하고 PREVIEW_REMOVED를 알리며, 같은 값은 원본 바이트를 반환합니다. 입력 경고는 한 번 남으며 header 수선을 뜻하지 않습니다. 한 칸이라도 이 범위 밖이거나 텍스트 치환을 지원하지 않으면 파일 전체에 기존 왕복 안전성·패키지 보존 검사와 재인코드를 적용합니다. 주소 오류와 검증 실패는 오류로 끝납니다.

리소스

스타일 템플릿을 YAML(application/x-yaml)로 읽는 리소스 4개입니다. 프리셋 이름과 일치합니다(crates/hwpforge-bindings-mcp/src/resources/mod.rs).

URI이름
hwpforge://templates/defaultDefault Template
hwpforge://templates/modernModern Template
hwpforge://templates/classicClassic Template
hwpforge://templates/latestLatest Template

프롬프트

워크플로 안내 프롬프트 3개입니다(crates/hwpforge-bindings-mcp/src/prompts/mod.rs).

이름제목인자
generate_proposal정부 제안서 생성topic(필수), organization(선택), deadline(선택, YYYY-MM-DD)
generate_report보고서 생성topic(필수), author(선택), report_type(선택: research / progress / analysis, 기본 research)
convert_and_review문서 편집 워크플로우file_path(필수), edit_instructions(선택)

참고

  • MCP 서버는 베타이며 HWP5 경로는 MCP가 아니라 CLI(convert-hwp5, audit-hwp5, to-pdf)를 우선합니다. 이 서버의 19개 도구에는 HWP5와 PDF 관련 도구가 없습니다.
  • CLI 명령은 CLI 레퍼런스, Python 사용법은 Python 가이드를 보세요.

by Ai-Scream