{"_id":"hwp-mcp","_rev":"3-5ae8a98f9101f9c8a678fc43581e0fd2","name":"hwp-mcp","dist-tags":{"latest":"0.3.0"},"versions":{"0.2.0":{"name":"hwp-mcp","version":"0.2.0","keywords":["hwp","hwpx","hangul","한글","mcp","model-context-protocol","claude","cursor","korean","hancom","llm"],"author":{"name":"Treesoop","email":"official@treesoop.com"},"license":"MIT","_id":"hwp-mcp@0.2.0","maintainers":[{"name":"ndh8392","email":"ndh8392@gmail.com"}],"homepage":"https://github.com/treesoop/hwp-mcp","bugs":{"url":"https://github.com/treesoop/hwp-mcp/issues"},"bin":{"hwp-mcp":"dist/server.js"},"dist":{"shasum":"8e07480c40f9fcebc4dc57d4bee014b64f97f636","tarball":"https://registry.npmjs.org/hwp-mcp/-/hwp-mcp-0.2.0.tgz","fileCount":27,"integrity":"sha512-IRKEo9kOdL2WhsydmmyRFgApISPuwWzutorHBOkse85bzJ0cZ7Q/X5kGVk5zaWXqK0QjWXrK5gf3fNVV0m+pvw==","signatures":[{"sig":"MEUCIHxCurKOUbUyYl+XfrVJwdQNH0eEkt+0MK2nRpy9KT+NAiEAyI/ogqBpPkHJz7zzckaHUq9ZAPB5ndzDdpiyslM2LGw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":224444},"main":"dist/server.js","type":"module","engines":{"node":">=20"},"gitHead":"474904726d14052558a9016bf9bd2c52da6a043a","scripts":{"dev":"tsx src/server.ts","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/server.js","test:watch":"vitest","build:fixtures":"tsx test/fixtures/build-fixtures.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"ndh8392","email":"ndh8392@gmail.com"},"repository":{"url":"git+https://github.com/treesoop/hwp-mcp.git","type":"git"},"_npmVersion":"11.8.0","description":"MCP server for reading and writing HWP/HWPX (Korean Hangul) documents — built on rhwp.","directories":{},"_nodeVersion":"25.6.0","dependencies":{"jszip":"^3.10.1","@rhwp/core":"0.7.x","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^2.0.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/hwp-mcp_0.2.0_1777455704124_0.808523635817108","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"hwp-mcp","version":"0.2.1","keywords":["hwp","hwpx","hangul","한글","mcp","model-context-protocol","claude","cursor","korean","hancom","llm"],"author":{"name":"Treesoop","email":"official@treesoop.com"},"license":"MIT","_id":"hwp-mcp@0.2.1","maintainers":[{"name":"ndh8392","email":"ndh8392@gmail.com"}],"homepage":"https://github.com/treesoop/hwp-mcp","bugs":{"url":"https://github.com/treesoop/hwp-mcp/issues"},"bin":{"hwp-mcp":"dist/server.js"},"dist":{"shasum":"05710866418939767f05d26ff9bea606e816cd74","tarball":"https://registry.npmjs.org/hwp-mcp/-/hwp-mcp-0.2.1.tgz","fileCount":27,"integrity":"sha512-ke7zpXtVO2A1Mjwmn3TrNJeYjLRE6Yj2dmhUkNbWWXVOLdrSUEcSU/kPYEpqglAY1mw6A+pTrR2P7O6OEE/Qiw==","signatures":[{"sig":"MEYCIQChNysYib+gwkrs+hADBQPj4GzpYsp2nqCymrz2k2SNGAIhAKbHhBAmAkz9dYYNBjXN0eld1mSMoCbmfVrqTJP8wKaN","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":226225},"main":"dist/server.js","type":"module","engines":{"node":">=20"},"gitHead":"831e209ab958970fe5374a0b8f0be29b81bf3114","scripts":{"dev":"tsx src/server.ts","test":"vitest run","build":"tsc -p tsconfig.json","start":"node dist/server.js","test:watch":"vitest","build:fixtures":"tsx test/fixtures/build-fixtures.ts","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"ndh8392","email":"ndh8392@gmail.com"},"repository":{"url":"git+https://github.com/treesoop/hwp-mcp.git","type":"git"},"_npmVersion":"11.8.0","description":"MCP server for reading and writing HWP/HWPX (Korean Hangul) documents — built on rhwp.","directories":{},"_nodeVersion":"25.6.0","dependencies":{"jszip":"^3.10.1","@rhwp/core":"0.7.x","@modelcontextprotocol/sdk":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.0.0","vitest":"^2.0.0","typescript":"^5.4.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/hwp-mcp_0.2.1_1779806322690_0.9692673653212363","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"hwp-mcp","version":"0.3.0","description":"MCP server for reading and writing HWP/HWPX (Korean Hangul) documents — built on rhwp.","type":"module","license":"MIT","author":{"name":"Treesoop","email":"official@treesoop.com"},"homepage":"https://github.com/treesoop/hwp-mcp","repository":{"type":"git","url":"git+https://github.com/treesoop/hwp-mcp.git"},"keywords":["hwp","hwpx","hangul","한글","mcp","model-context-protocol","claude","cursor","korean","hancom","llm"],"bin":{"hwp-mcp":"dist/server.js"},"main":"dist/server.js","engines":{"node":">=20"},"scripts":{"build":"tsc -p tsconfig.json","start":"node dist/server.js","dev":"tsx src/server.ts","test":"vitest run","test:watch":"vitest","build:fixtures":"tsx test/fixtures/build-fixtures.ts","prepublishOnly":"npm run build && npm test"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","@rhwp/core":"0.7.x","jszip":"^3.10.1"},"devDependencies":{"@types/node":"^20.0.0","tsx":"^4.0.0","typescript":"^5.4.0","vitest":"^2.0.0"},"gitHead":"3edd0c3d00e43a1ca2800bf14a5244e3e519f84c","_id":"hwp-mcp@0.3.0","bugs":{"url":"https://github.com/treesoop/hwp-mcp/issues"},"_nodeVersion":"25.6.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-+CYrAT5cKOpf6GCHyXRvw4SY/Z5GqBxO+Za92PyHCwseU8C6T3A3AR2bVv6hNQbG4SL6GJsgyfeaKjmpMut/Fw==","shasum":"2b5f43d3a3e727b5112aaf715e009ea588f003db","tarball":"https://registry.npmjs.org/hwp-mcp/-/hwp-mcp-0.3.0.tgz","fileCount":29,"unpackedSize":245928,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFaqoW9YNqp1sOdhgZztqSOSd8lCXqTTCjjuukZGnXpPAiBM2mJJhZml+09TwGdnNrDMAJ4VNJcHW9mrO2YCzumlXg=="}]},"_npmUser":{"name":"ndh8392","email":"ndh8392@gmail.com"},"directories":{},"maintainers":[{"name":"ndh8392","email":"ndh8392@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/hwp-mcp_0.3.0_1783502293518_0.08550061787647789"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-29T09:41:44.123Z","modified":"2026-07-08T09:18:13.755Z","0.2.0":"2026-04-29T09:41:44.272Z","0.2.1":"2026-05-26T14:38:42.844Z","0.3.0":"2026-07-08T09:18:13.638Z"},"bugs":{"url":"https://github.com/treesoop/hwp-mcp/issues"},"author":{"name":"Treesoop","email":"official@treesoop.com"},"license":"MIT","homepage":"https://github.com/treesoop/hwp-mcp","keywords":["hwp","hwpx","hangul","한글","mcp","model-context-protocol","claude","cursor","korean","hancom","llm"],"repository":{"type":"git","url":"git+https://github.com/treesoop/hwp-mcp.git"},"description":"MCP server for reading and writing HWP/HWPX (Korean Hangul) documents — built on rhwp.","maintainers":[{"name":"ndh8392","email":"ndh8392@gmail.com"}],"readme":"# hwp-mcp\n\n> Claude · Cursor · ChatGPT 등 MCP 호환 AI에서 **한글 문서(.hwp / .hwpx)** 를 읽고 수정하고 새로 만들 수 있게 해주는 서버입니다.\n\n[![npm version](https://img.shields.io/npm/v/hwp-mcp.svg)](https://www.npmjs.com/package/hwp-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/hwp-mcp.svg)](https://www.npmjs.com/package/hwp-mcp)\n[![Built on rhwp](https://img.shields.io/badge/built%20on-rhwp-blue)](https://github.com/edwardkim/rhwp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub release](https://img.shields.io/github/v/release/treesoop/hwp-mcp)](https://github.com/treesoop/hwp-mcp/releases/latest)\n\n`hwp-mcp`은 한컴오피스 문서를 AI 에이전트가 직접 다루도록 해주는 MCP(Model Context Protocol) 서버입니다. **읽기뿐 아니라 텍스트 수정, 템플릿 채우기, 새 문서 생성까지 가능합니다.**\n\n## 어떤 프로젝트인가요?\n\n이 프로젝트는 두 부분으로 나뉩니다.\n\n- 🔧 **핵심 엔진: rhwp** — [Edward Kim](https://github.com/edwardkim) 님의 [**rhwp**](https://github.com/edwardkim/rhwp)는 한글 포맷(HWP 5.0 binary, HWPX/OWPML)을 Rust + WebAssembly로 구현한 오픈소스 엔진입니다. 파싱, 표·이미지·수식·머리말 추출, SVG 렌더링, 한컴 호환 Field API 등 포맷 처리 능력을 제공합니다.\n\n- 🤝 **`hwp-mcp` 가 한 일 (에이전트 어댑터)** — `@rhwp/core` 위에 얹은 MCP 서버 layer. 우리가 추가한 것은:\n  - `read_hwp`, `fill_hwp_template`, `replace_hwp_text` 같은 **에이전트 친화적 도구 시그니처** — Claude/Cursor 같은 LLM이 자연어로 호출할 수 있게\n  - 본문·표·이미지·머리말·꼬리말·각주·수식을 한 번에 dump 하는 **시나리오 중심 traversal walker**\n  - 표 셀 병합 자동 처리, footnote/equation 자동 합본 같은 **사용 편의 layer**\n  - rhwp 0.7.7 의 `exportHwpx` 라운드트립 한계를 우회하기 위한 **`.hwpx` ZIP-level mutation layer** (실제 쓰기를 가능하게 하는 핵심)\n  - npm `hwp-mcp` 패키지 (한 줄 설치) + Node.js WASM 부트스트랩\n\n요약: **AI 에이전트가 한글 문서를 읽고 쓸 수 있게 해주는 어댑터**입니다. 포맷 처리는 rhwp, 에이전트 연동은 hwp-mcp 가 담당합니다.\n\n---\n\n## 설치\n\n### Claude Code\n\n```bash\nclaude mcp add hwp-mcp -- npx -y hwp-mcp\n```\n\n### Claude Desktop / Cursor / VS Code (settings JSON)\n\n```json\n{\n  \"mcpServers\": {\n    \"hwp-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"hwp-mcp\"]\n    }\n  }\n}\n```\n\nNode.js 20 이상 필요. **macOS · Windows · Linux 모두 지원** — 엔진이 WebAssembly 기반이라 한컴오피스 설치 없이 OS 무관하게 동작합니다.\n\n### 설치 확인\n\n```bash\nclaude mcp list | grep hwp-mcp\n# hwp-mcp: npx -y hwp-mcp  - ✓ Connected\n```\n\n`✓ Connected` 가 뜨면 끝.\n\n### 처음 써보기 (60초)\n\n설치 직후 동작 확인용 가장 짧은 검증:\n\n```\n나: 새 hwpx 문서 만들어줘. 파일 이름은 hello.hwpx 이고 \"안녕 한글\" 한 줄만 들어가게.\nAI: HWPX 문서 생성 완료 (created): hello.hwpx\n\n나: hello.hwpx 읽어줘.\nAI: # hello.hwpx\n    안녕 한글\n```\n\n위 두 단계가 되면 읽기·쓰기 양쪽 다 동작합니다. 이제 실제 문서로:\n\n- `~/Downloads/공고문.hwp 읽어줘`\n- `report.hwpx 의 {{이름}}을 남대현으로, {{날짜}}를 2026-05-26으로 채워줘`\n- `document.hwpx 의 첫 페이지를 SVG로 보여줘`\n\n### 안 되면?\n\n| 증상 | 원인 / 해결 |\n|---|---|\n| `✗ Failed to connect` | `v0.2.0` bin symlink 버그 — [v0.2.1](https://github.com/treesoop/hwp-mcp/releases/tag/v0.2.1) 이상으로 업그레이드 (아래) |\n| 설치는 됐는데 `mcp__hwp-mcp__*` 도구가 안 보임 | Claude Code / Cursor 세션 **재시작** 필요 (MCP 도구는 세션 시작 시점에 로드됨) |\n| `npx: command not found` 또는 ESM 에러 | Node 20+ 인지 확인: `node --version`. Node 18 은 EOL — `nvm install 20` 또는 [공식 설치](https://nodejs.org) |\n| `npx` 가 옛 버전을 캐시 | `claude mcp add hwp-mcp -- npx -y hwp-mcp@latest` (`@latest` 명시) 또는 `npm cache clean --force` |\n| Claude Desktop / Cursor 에서 안 보임 | 설정 JSON 저장 후 앱 **완전 종료 + 재실행** (백그라운드 트레이도 종료) |\n\n**v0.2.0 → v0.2.1 업그레이드:**\n\n```bash\nclaude mcp remove hwp-mcp\nclaude mcp add hwp-mcp -- npx -y hwp-mcp@latest\nclaude mcp list | grep hwp-mcp   # ✓ Connected\n```\n\n설정 파일 방식(Claude Desktop/Cursor)이면 `args` 를 `[\"-y\", \"hwp-mcp@latest\"]` 로:\n\n```json\n{\n  \"mcpServers\": {\n    \"hwp-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"hwp-mcp@latest\"]\n    }\n  }\n}\n```\n\n여전히 안 되면: [Issues](https://github.com/treesoop/hwp-mcp/issues) 에 `node --version`, `claude mcp list` 출력, 실행 OS 적어서 알려주세요.\n\n---\n\n## 도구 목록\n\n`hwp-mcp` v0.3이 노출하는 **35개 MCP 도구**입니다. 읽기·렌더는 `.hwp`/`.hwpx` 모두 지원, 쓰기는 `.hwpx` 전용입니다.\n\n### 읽기 / 변환 (6)\n\n| 도구 | `.hwp` | `.hwpx` | 설명 |\n|------|:---:|:---:|------|\n| `read_hwp` | ✅ | ✅ | 본문 + 표(마크다운) + 이미지 목록 한 번에 |\n| `read_hwp_text` | ✅ | ✅ | 본문 + 머리말 + 꼬리말 + 각주 + 수식 통합 텍스트 |\n| `read_hwp_tables` | ✅ | ✅ | 표를 GitHub 마크다운으로 (셀 병합 처리) |\n| `convert_hwp_markdown` | ✅ | ✅ | 문서 → Markdown 변환 (문서 순서 유지, 표 GFM 제자리, 이미지 추출+상대링크, 수식 `$…$`, 각주 문서 끝) |\n| `list_hwp_images` | ✅ | ✅ | 임베디드 이미지 목록 (mime, 바이트) |\n| `extract_hwp_images` | ✅ | ✅ | 이미지를 디스크로 추출 |\n\n### 메타 / 조회 (5)\n\n| 도구 | `.hwp` | `.hwpx` | 설명 |\n|------|:---:|:---:|------|\n| `get_hwp_info` | ✅ | ✅ | 버전·페이지·글꼴·표/이미지/각주/수식 통계 |\n| `get_hwp_page_def` | ✅ | ✅ | 섹션별 용지 크기·여백·단·헤더/푸터 마진 |\n| `list_hwp_fields` | ✅ | ✅ | 한컴 필드 목록 |\n| `get_hwp_field_value` | ✅ | ✅ | 필드 값 조회 |\n| `list_hwp_bindata` | – | ✅ | `.hwpx` BinData/ 엔트리 목록 |\n\n### 시각 렌더 (4)\n\n| 도구 | `.hwp` | `.hwpx` | 설명 |\n|------|:---:|:---:|------|\n| `render_hwp_page` | ✅ | ✅ | 특정 페이지 → SVG (인라인/파일) |\n| `render_hwp_all_pages` | ✅ | ✅ | 전체 페이지 SVG 일괄 |\n| `render_hwp_html` | ✅ | ✅ | 페이지 → HTML |\n| `render_hwp_equation_svg` | – | – | OWPML 수식 script → SVG |\n\n### 쓰기 — 텍스트 (5)\n\n| 도구 | `.hwpx` | 설명 |\n|------|:---:|------|\n| `replace_hwp_text` | ✅ | 특정 문자열 찾아 바꾸기 |\n| `fill_hwp_template` | ✅ | `{{이름}}` 등 다중 자리표시자 |\n| `set_hwp_paragraph_text` | ✅ | N번째 문단 텍스트 통째 교체 |\n| `set_hwp_cell_text` | ✅ | 표 셀 (행, 열) 텍스트 직접 설정 |\n| `set_hwp_field_value` | ✅ | 필드 값 설정 |\n\n### 쓰기 — 구조 (9)\n\n| 도구 | `.hwpx` | 설명 |\n|------|:---:|------|\n| `append_hwp_paragraph` | ✅ | 본문 끝에 새 문단 |\n| `delete_hwp_paragraph` | ✅ | N번째 문단 삭제 |\n| `append_hwp_table_row` | ✅ | 표 마지막에 새 행 |\n| `delete_hwp_table_row` | ✅ | 표 행 삭제 |\n| `append_hwp_table_column` | ✅ | 표 끝에 새 열 (모든 행에) |\n| `delete_hwp_table_column` | ✅ | 표 열 삭제 |\n| `merge_hwp_cells_horizontal` | ✅ | 가로 셀 병합 (colSpan) |\n| `merge_hwp_cells_vertical` | ✅ | 세로 셀 병합 (rowSpan) |\n| `replace_hwp_image` | ✅ | 임베디드 이미지 교체 |\n\n### 쓰기 — 서식 (2)\n\n| 도구 | `.hwpx` | 설명 |\n|------|:---:|------|\n| `apply_hwp_text_style` | ✅ | 글자 색·볼드·이탤릭·밑줄·크기 (charPr 추가) |\n| `apply_hwp_paragraph_style` | ✅ | 문단 정렬·들여쓰기·줄간격 (paraPr 추가) |\n\n### 쓰기 — 이미지 / 표 / 신규 (4)\n\n| 도구 | `.hwpx` | 설명 |\n|------|:---:|------|\n| `insert_hwp_image` | ✅ | 새 이미지 추가 (BinData + manifest + `<hp:pic>`) |\n| `delete_hwp_image` | ✅ | BinData/ 엔트리 삭제 |\n| `insert_hwp_table` | ⚠️ | 새 OWPML 표 삽입 (실험적 — 파일 valid, rhwp 인식 비완전) |\n| `create_hwpx_document` | ✅ | 텍스트로 새 `.hwpx` 만들기 |\n\n## 컨텐츠 추출 매트릭스\n\n| 컨텐츠 | 추출 | 비고 |\n|---|:---:|---|\n| 본문 문단 텍스트 | ✅ | `read_hwp_text`, `read_hwp` |\n| 표 (셀 병합 포함) | ✅ | `read_hwp_tables` 가 markdown 으로 |\n| 임베디드 이미지 | ✅ | PNG/JPG/BMP 등 추출 |\n| **머리말 / 꼬리말** | ✅ | `read_hwp_text` 결과에 `--- headers ---` / `--- footers ---` 블록 |\n| **각주(footnote)** | ✅ | 결과 끝에 `--- footnotes ---` 블록, `[1] 본문…` 형태 |\n| **수식(equation)** | ✅ | OWPML script 형태 (예: `TIMES LEFT ( {a} over {b} RIGHT )`), `--- equations ---` 블록 |\n| 페이지 SVG 렌더 | ✅ | `render_hwp_page` |\n| 텍스트박스 본문 | ❌ | rhwp의 `createShapeControl`은 만들지만 `getTextBoxControlIndex` 반환 패턴이 비명시적 — v0.3에서 trace |\n| 미주(endnote) | – | rhwp 자체 미지원 (footnote만) |\n| 차트(chart) | ❌ | v0.3 이후 |\n\n## 작성 매트릭스\n\n| 작업 | `.hwp` | `.hwpx` | 비고 |\n|---|:---:|:---:|---|\n| 텍스트 단일 치환 | ❌ | ✅ | `replace_hwp_text` |\n| 다중 자리표시자 채우기 | ❌ | ✅ | `fill_hwp_template` |\n| 문단 텍스트 통째 교체 | ❌ | ✅ | `set_hwp_paragraph_text` |\n| 표 셀 직접 수정 | ❌ | ✅ | `set_hwp_cell_text` (행·열 지정) |\n| 필드 값 설정 | ❌ | ✅ | `set_hwp_field_value` |\n| 새 문단 추가 / 삭제 | ❌ | ✅ | `append_hwp_paragraph` / `delete_hwp_paragraph` |\n| 표 행 추가 / 삭제 | ❌ | ✅ | `append_hwp_table_row` / `delete_hwp_table_row` |\n| 이미지 교체 / 삭제 | ❌ | ✅ | `replace_hwp_image` / `delete_hwp_image` |\n| 새 문서 생성 (텍스트) | – | ✅ | `create_hwpx_document` |\n| 새 문서 생성 (표) | – | ⚠️ | 텍스트 행으로 평탄화 (v0.3에서 진짜 OWPML 표) |\n| 새 이미지 삽입 | ❌ | ✅ | `insert_hwp_image` |\n| 표 열 추가 / 삭제 | ❌ | ✅ | `append_hwp_table_column` / `delete_hwp_table_column` |\n| 셀 병합 (가로·세로) | ❌ | ✅ | `merge_hwp_cells_horizontal` / `merge_hwp_cells_vertical` |\n| 글자 서식 (색·볼드·이탤릭·밑줄·크기) | ❌ | ✅ | `apply_hwp_text_style` |\n| 문단 서식 (정렬·들여쓰기·줄간격) | ❌ | ✅ | `apply_hwp_paragraph_style` |\n| 새 표 삽입 (진짜 OWPML) | ❌ | ⚠️ | `insert_hwp_table` (실험적) |\n| 머리말/꼬리말 신규 삽입 | ❌ | ❌ | v0.3 |\n| 차트·북마크·스타일 정의 | ❌ | ❌ | v0.3 |\n\n> `.hwp` 바이너리 쓰기는 rhwp 0.7.7 의 `exportHwp` 라운드트립 한계로 v0.2에서 미지원. 한컴오피스에서 `.hwpx`로 다른 이름 저장 후 쓰기 도구를 사용하시거나, v0.3 릴리스를 기다려주세요.\n\n---\n\n## 사용 예시\n\n### 정부 한글 문서 읽기\n\n```\n나: /Users/me/2026년_시행계획.hwpx 읽어줘\n\nAI: # 2026년_시행계획.hwpx\n    형식: .HWPX | 문단: 153개 | 표: 15개 | 이미지: 2개\n\n    Ⅰ. 추진 배경\n    □ (글로벌 현황) 전세계 AI 솔루션 시장 규모는 ...\n\n    ### 표 9 (7행 x 4열)\n    | 도메인 | 입력 데이터 | 학습 내용 | 산업AI 솔루션 적용 기능 예시 |\n    | --- | --- | --- | --- |\n    | 기계 | · 센서 데이터 로그 ... | ... | ... |\n```\n\n### 템플릿 채우기\n\n```\n나: /path/to/form.hwpx 에서 {{이름}}=남대현, {{회사}}=포텐랩 으로 채워줘\n\nAI: 저장 완료 (saved): form_filled.hwpx\n    총 2건 치환 (2 replacements)\n      '{{이름}}' → 1건\n      '{{회사}}' → 1건\n```\n\n### 텍스트 치환\n\n```\n나: /path/to/doc.hwpx 의 \"산업AI\" 를 \"산업-AI\" 로 바꿔줘\n\nAI: '산업AI' → '산업-AI': 18건 교체 (replaced 18)\n    저장 (saved): doc_modified.hwpx\n```\n\n### 새 .hwpx 만들기\n\n```\n나: employees.hwpx 에 \"사원 명부\" 와 \"두 번째 줄\" 두 줄을 가진 문서 만들어줘\n\nAI: HWPX 문서 생성 완료 (created): employees.hwpx\n```\n\n### 이미지 추출\n\n```\n나: /path/to/document.hwpx 에서 이미지 빼줘\n\nAI: 이미지 2개를 추출했습니다 (extracted 2 images):\n    저장 위치: /path/to/document_images\n      - image_001.bmp\n      - image_002.bmp\n```\n\n### 페이지를 SVG로 렌더 (시각 분석용)\n\n```\n나: /path/to/document.hwpx 의 첫 페이지를 SVG로 보여줘\n\nAI: <svg xmlns=\"...\" width=\"793\" height=\"1122\" viewBox=\"...\">\n    <defs>...</defs>\n    ...\n    </svg>\n```\n\n또는 디스크로 저장:\n```\n나: /path/to/document.hwpx 모든 페이지 SVG로 저장해줘\n\nAI: 9/9 페이지 SVG 저장 (rendered 9/9 pages):\n    저장 위치: /path/to/document_pages\n      - page_001.svg\n      - page_002.svg ...\n```\n\n---\n\n## 한계\n\n`hwp-mcp` v0.2의 알려진 제약 사항입니다.\n\n- **`.hwp` 쓰기 미지원** — 읽기는 `.hwp`/`.hwpx` 모두 됩니다. 쓰기는 `.hwpx`만. `.hwp` 입력에 대해 쓰기 도구를 호출하면 명확한 에러 메시지를 돌려줍니다. 한컴오피스에서 `.hwpx`로 다른 이름 저장 후 사용하시거나, v0.3 릴리스를 기다려주세요.\n- **크로스 포맷 저장 거부** — `.hwpx` 입력은 `.hwpx`로만 저장됩니다.\n- **머리말/꼬리말/각주 추출 가능, 텍스트박스/미주/수식은 v0.3** — `read_hwp_text` 결과에 머리말은 `--- headers ---`, 꼬리말은 `--- footers ---`, 각주는 `--- footnotes ---` 블록으로 표시됩니다. 텍스트박스 본문, 미주, 수식 추출은 v0.3 예정.\n- **검색어가 두 텍스트 노드에 걸치면 매칭 안 됨** — 예: 한 `<hp:t>`가 \"산업\"으로 끝나고 다음이 \"AI\"로 시작하면 \"산업AI\"는 매칭 X. 한컴 hwpctl과 동일한 한계입니다.\n- **`create_hwpx_document`의 표는 v0.2에서 텍스트 행으로 평탄화** — 진짜 OWPML 표는 v0.3에서.\n\n---\n\n## 어떻게 동작하나요?\n\n- **읽기**: [`@rhwp/core`](https://www.npmjs.com/package/@rhwp/core) (rhwp의 Rust+WASM 파서) 가 섹션·문단·표(병합 셀 포함)·이미지를 traverse 합니다.\n- **쓰기 (.hwpx)**: ZIP 아카이브 안의 `Contents/section*.xml` 을 직접 파싱해서 `<hp:t>` 텍스트 노드를 search/replace 한 뒤 다시 패키징합니다 (mimetype은 spec대로 stored). rhwp의 `exportHwpx()` 라운드트립 이슈를 우회하기 위한 layer입니다.\n- **새 문서**: rhwp의 `createBlankDocument` + `insertText` 로 작성한 뒤 `exportHwpx` 로 저장합니다 (텍스트 라운드트립이 안정).\n\n## 크레딧\n\n**rhwp** ([@edwardkim](https://github.com/edwardkim), MIT) — 한글 포맷 파서·렌더러·Field API. 이 프로젝트의 포맷 처리는 rhwp 에 기반합니다: <https://github.com/edwardkim/rhwp>\n\n**hwp-mcp** — rhwp 위에 AI 에이전트가 자연어로 호출할 수 있게 도구화한 MCP 어댑터.\n\n## 커버리지\n\n| 영역 | 커버 |\n|---|---|\n| 읽기/추출 | ~90% |\n| 렌더링 | ~85% (SVG · HTML · 수식 SVG · Canvas는 브라우저용이라 제외) |\n| 쓰기 — 텍스트 | ~95% |\n| 쓰기 — 구조 | ~90% (행·열·병합·이미지 4종) |\n| 쓰기 — 서식 | ~70% (글자 + 문단) |\n| 메타 / 필드 | ~85% |\n| **전체 가중** | **~85%** |\n\n남은 v0.3 큰 항목: `.hwp` 바이너리 쓰기, 차트, 스타일 정의·적용, 텍스트박스 본문 추출, hwpctl 30 Actions(의도적 제외).\n\n## 릴리스 / 이슈\n\n- 변경 이력: <https://github.com/treesoop/hwp-mcp/releases>\n- 버그 신고 · 기능 제안: <https://github.com/treesoop/hwp-mcp/issues>\n- npm 패키지: <https://www.npmjs.com/package/hwp-mcp>\n\n이슈 올릴 때는 `node --version`, OS, MCP 클라이언트(Claude Code / Desktop / Cursor / …), 그리고 가능하면 재현되는 `.hwpx` 샘플을 첨부해주세요.\n\n## English\n\n`hwp-mcp` is an MCP server for reading and writing Korean Hangul (.hwp / .hwpx) documents from Claude / Cursor / ChatGPT and any MCP-compatible client. **Read works for both formats; write currently supports .hwpx (find/replace, template fill, create new doc) — .hwp write is planned for v0.3.** Runs on macOS, Windows, and Linux (WebAssembly-based — no Hancom Office install required). Built on top of [rhwp](https://github.com/edwardkim/rhwp) (Rust + WebAssembly HWP engine by Edward Kim, MIT).\n\n```bash\nclaude mcp add hwp-mcp -- npx -y hwp-mcp\nclaude mcp list | grep hwp-mcp   # ✓ Connected\n```\n\n**Not seeing `✓ Connected`?** Upgrade to v0.2.1+ (`npx -y hwp-mcp@latest`) — v0.2.0 had a bin-symlink bug that made the server exit silently. Tools not appearing in your AI client? Restart the session; MCP tools load at startup.\n\n## License\n\nMIT.\n","readmeFilename":"README.md"}