{
  "markdown": "# claude-hwp-plugin\n\n> **Claude Code** 로 한컴 한글 문서(.hwp / .hwpx)를 자연어로 완전히 제어하는 AI 에이전트 플러그인\n\n[![npm version](https://img.shields.io/npm/v/claude-hwp-plugin-mcp)](https://www.npmjs.com/package/claude-hwp-plugin-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/claude-hwp-plugin-mcp)](https://www.npmjs.com/package/claude-hwp-plugin-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-brightgreen)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue)](https://www.typescriptlang.org)\n[![MCP](https://img.shields.io/badge/MCP-1.28-purple)](https://modelcontextprotocol.io)\n\n---\n\n## 개요\n\n한국 공공기관·기업 표준 문서 포맷인 **HWP / HWPX** 를 AI 에이전트로 자동화합니다.\n\n- **자연어 명령** 만으로 문서 읽기·양식 채우기·새 문서 생성·비교를 수행\n- [kordoc](https://github.com/chrisryugj/kordoc) 라이브러리를 **MCP Server** 로 래핑, Claude Code **Skill** 과 연결\n- `.hwp` / `.hwpx` / `.pdf` 읽기 지원, 쓰기는 `.hwpx` 포맷으로 출력\n- npm 패키지 [`claude-hwp-plugin-mcp`](https://www.npmjs.com/package/claude-hwp-plugin-mcp) 로 배포 — `npx` 한 줄로 즉시 사용 가능\n\n```\n사용자 자연어 명령\n      ↓\nClaude Code + Skill (SKILL.md)\n      ↓\nMCP Server (npx claude-hwp-plugin-mcp — 8개 도구)\n      ↓\nkordoc 라이브러리 (HWP/HWPX 파싱·생성)\n      ↓\n출력 파일 (.hwpx) 또는 구조화 데이터\n```\n\n---\n\n## 주요 기능\n\n| 기능 | 자연어 명령 예시 |\n|------|----------------|\n| 📄 **문서 읽기** | \"보고서.hwpx 내용 요약해줘\" |\n| ✏️ **양식 자동 채우기** | \"신청서.hwp 양식에 이름 홍길동, 날짜 오늘로 채워줘\" |\n| 📋 **일괄 양식 생성** | \"직원 명단 CSV로 신청서 100개 한 번에 만들어줘\" |\n| ✨ **새 문서 생성** | \"월간 업무 보고서를 HWPX로 만들어줘\" |\n| 🔍 **문서 비교** | \"v1.hwpx와 v2.hwpx 변경된 부분 알려줘\" |\n| 🏷️ **메타데이터 확인** | \"이 문서 작성자랑 수정일 알려줘\" |\n| 🔎 **포맷 감지** | \"이 파일이 진짜 HWP인지 확인해줘\" |\n\n---\n\n## 제공 MCP 도구 (8개)\n\n| 도구 | 설명 |\n|------|------|\n| `hwp_parse` | HWP / HWPX / PDF → 마크다운 + 구조화 블록(IRBlock[]) 변환 |\n| `hwp_detect_format` | 파일 매직 바이트 분석으로 실제 포맷 감지 |\n| `hwp_extract_form` | 양식(서식) 필드 추출 — 라벨, 현재값, 신뢰도 반환 |\n| `hwp_fill_form` | 양식 템플릿에 데이터를 채워 HWPX 파일 생성 |\n| `hwp_batch_fill` | 하나의 템플릿으로 여러 레코드를 일괄 처리 (최대 500건) |\n| `hwp_create` | 마크다운 텍스트로 새 HWPX 문서 생성 |\n| `hwp_compare` | 두 문서를 비교하여 추가 / 삭제 / 수정 블록 표시 |\n| `hwp_metadata` | 제목·작성자·날짜·페이지 수 등 메타데이터 빠른 추출 |\n\n---\n\n## 설치\n\n### 방법 1: npx로 즉시 사용 (권장)\n\n별도 설치 없이 `npx` 로 바로 실행합니다.\n\n**Claude Code CLI 로 등록:**\n\n```bash\nclaude mcp add claude-hwp -- npx -y claude-hwp-plugin-mcp\n```\n\n또는 프로젝트 루트의 `.mcp.json` 에 직접 추가:\n\n```json\n{\n  \"mcpServers\": {\n    \"claude-hwp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"claude-hwp-plugin-mcp\"],\n      \"description\": \"HWP/HWPX 문서 제어 MCP 서버\"\n    }\n  }\n}\n```\n\n### 방법 2: 전역 설치 후 사용\n\n```bash\nnpm install -g claude-hwp-plugin-mcp\nclaude mcp add claude-hwp -- claude-hwp-mcp\n```\n\n### 방법 3: 소스에서 직접 빌드\n\n```bash\ngit clone https://github.com/hyunmin625/claude-hwp-plugin.git\ncd claude-hwp-plugin/mcp-server\nnpm install\nnpm run build\nclaude mcp add claude-hwp node ./dist/index.js\n```\n\n### 요구사항\n\n- Node.js **18** 이상\n- Claude Code (MCP 사용 가능 버전)\n\n---\n\n## 사용 예시\n\n### 양식 자동 채우기\n\n```\n나: \"입사지원서.hwpx 양식에 이름 홍길동, 지원직무 개발자, 날짜 2026-03-31로 채워서 저장해줘\"\n\nClaude: hwp_extract_form 도구로 양식 필드를 확인합니다...\n        - [이름] 현재값: (빈칸)\n        - [지원직무] 현재값: (빈칸)\n        - [날짜] 현재값: (빈칸)\n\n        hwp_fill_form 도구로 채웁니다...\n        ✅ 완료: ./output/입사지원서_filled.hwpx (24.1 KB)\n        ✔ 채워진 필드: 이름, 지원직무, 날짜\n```\n\n### 일괄 양식 생성 (배치)\n\n```\n나: \"직원명단.json 데이터로 재직증명서.hwpx 양식을 한 번에 생성해줘. 파일명은 이름으로 해줘\"\n\nClaude: hwp_batch_fill 도구로 50명분 재직증명서를 생성합니다...\n        ✅ 50개 파일 생성 완료 → ./output/ 디렉토리\n        ✔ 홍길동.hwpx, 김영희.hwpx, 이철수.hwpx ...\n```\n\n### 문서 비교\n\n```\n나: \"계약서_v1.hwpx와 계약서_v2.hwpx 달라진 내용 알려줘\"\n\nClaude: hwp_compare 결과:\n        📊 추가: 3개 블록 / 삭제: 1개 블록 / 수정: 5개 블록\n        ➕ [추가] 제5조 손해배상 조항 신설\n        ✏️  [수정] 계약 기간 1년 → 2년\n        ...\n```\n\n---\n\n## 프로젝트 구조\n\n```\nclaude-hwp-plugin/\n├── .claude-plugin/\n│   └── plugin.json              # 플러그인 매니페스트\n├── .mcp.json                    # MCP 서버 로컬 설정\n│\n├── mcp-server/                  # npm 패키지 (claude-hwp-plugin-mcp)\n│   ├── src/\n│   │   ├── index.ts             # 8개 MCP 도구 구현 (메인)\n│   │   └── __tests__/           # 단위 테스트 (vitest)\n│   │       ├── utils.test.ts    # formatBytes, escapeRegex, 파일 검증 (41개)\n│   │       ├── patterns.test.ts # 필드 치환 정규식 패턴 테스트 (29개)\n│   │       └── batch.test.ts    # 배치 처리, Zod 스키마 검증 (40개)\n│   ├── dist/                    # 빌드 결과물 (tsc 컴파일)\n│   ├── package.json             # npm: claude-hwp-plugin-mcp@0.1.0\n│   ├── tsconfig.json\n│   └── vitest.config.ts\n│\n├── skills/\n│   └── hwp-agent/\n│       └── SKILL.md             # Claude Code Skill 프롬프트\n│\n├── scripts/\n│   └── package-plugin.mjs       # .plugin 아카이브 패키징 스크립트\n│\n└── README.md\n```\n\n---\n\n## 개발\n\n### 테스트 실행\n\n```bash\ncd mcp-server\n\n# 전체 테스트 실행 (110개)\nnpm test\n\n# 파일 변경 감지 모드\nnpm run test:watch\n\n# 커버리지 리포트\nnpm run test:coverage\n```\n\n### .plugin 파일 패키징\n\n```bash\n# 루트 디렉토리에서\nnpm run package          # 빌드 + 패키징\nnpm run package:only     # 패키징만 (이미 빌드된 경우)\n\n# 출력: claude-hwp-plugin-v0.1.0.plugin\n```\n\n### 기술 스택\n\n| 분류 | 기술 |\n|------|------|\n| 런타임 | Node.js ≥ 18 |\n| 언어 | TypeScript 5.5 |\n| MCP 프로토콜 | @modelcontextprotocol/sdk 1.28 |\n| 문서 엔진 | kordoc 1.6 |\n| 스키마 검증 | Zod 3.23 |\n| 테스트 | Vitest 2.x |\n| 패키징 | archiver 7.x |\n\n---\n\n## 제한 사항\n\n| 항목 | 제한 |\n|------|------|\n| 파일 크기 | 최대 500 MB |\n| 배치 처리 | 최대 500건 |\n| 쓰기 포맷 | HWPX 전용 (HWP 바이너리 쓰기 미지원) |\n| 읽기 포맷 | HWP / HWPX / PDF |\n| 필드 감지 | 비표준 양식은 신뢰도 저하 가능 |\n\n---\n\n## 개발 로드맵\n\n- [x] **Phase 1** — kordoc 분석 + MCP Server 기반 구축 (8개 도구)\n- [x] **Phase 2** — 양식 채우기 고도화 + 배치 처리 (`hwp_batch_fill`, 최대 500건)\n- [x] **Phase 2** — 단위 테스트 110개 작성 (vitest)\n- [x] **Phase 3** — `.plugin` 패키징 스크립트 완성\n- [x] **Phase 3** — npm 패키지 배포 (`claude-hwp-plugin-mcp@0.1.0`)\n- [x] **Phase 3** — Claude Code 플러그인 디렉토리 제출\n\n---\n\n## 참조\n\n- [npm: claude-hwp-plugin-mcp](https://www.npmjs.com/package/claude-hwp-plugin-mcp) — npm 패키지\n- [kordoc](https://github.com/chrisryugj/kordoc) — HWP / HWPX / PDF 파싱·생성 엔진\n- [Model Context Protocol](https://modelcontextprotocol.io) — MCP 사양\n- [Claude Code Docs](https://docs.claude.com) — Claude Code 문서\n\n---\n\n## 라이선스\n\n[MIT](LICENSE) © 2026 hyunmin625\n",
  "bytes": 5978,
  "sha": "960826817f9330dd7fd8ddc4cac2a7acac2bd59824e9618b577afd0cc686cdb9",
  "repo_slug": "hyunmin625/claude-hwp-plugin",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hyunmin625_claude_hwp_plugin_claude_hwp__89e079df/readme"
}