kordoc

ローカル

github.com生産性2.8k今日更新

リポジトリ公式サイト

kordoc について

kordoc は韓国語文書を扱うライブラリ、CLI、MCP サーバーです。HWP、HWPX、PDF、Office 文書、画像などを Markdown と構造化データに変換し、編集、生成、検査、ローカル OCR にも対応します。

主な機能

01文書を Markdown と構造化データに解析
02HWP、HWPX、PDF、Office 形式に対応
03書式を保った文書比較と編集
04文書生成とフォーム入力
05文書検査と個人情報のマスキング
06ローカル OCR とプレビュー

活用シーン

01HWP や PDF を Markdown に変換
02文書の異なるバージョンを比較
03テンプレートから公文書フォームに入力
04RAG 用の構造化テキストチャンクを準備

MCP 対応

kordoc は、解析、比較、生成、検査、レンダリング用の 18 ツールを MCP クライアントに公開する MCP サーバーです。`npx -y kordoc setup` でインストール済みクライアントに MCP を登録できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "chrisryugj-kordoc": {
      "command": "npx",
      "args": [
        "-y",
        "kordoc"
      ]
    }
  }
}

起動コマンドnpx -y kordoc

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npmkordoc4.24.16stdio

ツール

掲載時のツール一覧 · 今日に更新

パラメーター	型	必須	説明
ocr	any	いいえ	スキャン／画像PDFのテキストをOCRします（内蔵のPP-OCRv5 korean。初回使用時に約18MBを自動ダウンロード）。true=テキストレイヤーがない、または破損しているページのみを認識し、正常なページはそのままにします。"force"=テキストレイヤーがあっても無視し、全ページを強制的に再認識します。parse結果にNEEDS_OCR警告がある場合は、このオプションで再試行してください。
plain	boolean	いいえ	プレーンテキストのMarkdown。図のプレースホルダー、リンクURL、下線／太字のマークアップを除き、テキストのみを出力します（見出し・リスト・表の構造は維持。既定ではオフ。CLI --plainに対応）。
tables	boolean	いいえ	PDFの表検出（既定はtrue。falseで無効化。CLI --no-tablesに対応）。枠線が表と誤認されて読み順が逆転する文書（2段組の試験問題など）では、自然な読み順のテキストのみを抽出します（#64）。
password	string	いいえ	パスワードで保護された文書を開くためのパスワード（#59。HWPX、HWP3、HWP5に対応。ENCRYPTEDで解析に失敗した場合は、このオプションで再試行してください。Hancom DRMで保護された文書には適用されません）。
file_path	string	はい	解析する文書ファイルの絶対パス（HWP、HWPX、PDF、XLSX、DOCX、PNG/JPG/WebP）。
formula_ocr	boolean	いいえ	PDF数式OCRを有効にします（MFD+MFR ONNX。初回使用時に約155MBのモデルを自動ダウンロード。CLI --formula-ocrに対応）。
html_tables	boolean	いいえ	すべての表をHTMLに変換します。パイプ表も対象で、各タグを個別の行にインデントして出力します（既定ではオフ。CLI --html-tablesに対応）。
script_tags	boolean	いいえ	上付き／下付き文字を<sup>·<sub>で表記し、「10⁴ m²」が「104 m2」に平坦化されるのを防ぎます。既定ではHWPX、HWP、DOCXでオン、PDFでオフ（論文や数式を含むPDFではtrueを推奨）。falseではすべてプレーンテキストになります。CLI --script-tags / --no-script-tagsに対応。
table_format	enum	いいえ	"gfm"：HTMLを使わず、すべての表をGFMのパイプ表として出力します。セル内の表は親表の後に独立した表として取り出し、<!-- <table id parent_id /> -->マーカーで関連付けを保持します（RAGのインデックス作成用。html_tablesとは併用不可。CLI --table-formatに対応）。gfm
keep_layout_tables	boolean	いいえ	罫線の見えないレイアウト表も元の表構造のまま保持します（既定ではオフ＝見た目どおりに扱い、枠はテキスト、セルを組み合わせた分数は数式として処理）。patch_documentで元に戻せる編集用バージョンを出力するには有効にします（CLI --keep-layout-tables）。
remove_header_footer	boolean	いいえ	PDFのヘッダー／フッターを自動削除します（既定はtrue。falseで無効化。CLI --no-header-footerに対応）。
keep_empty_paragraphs	boolean	いいえ	空の段落を保持 — 本文では空の paragraph ブロック、表のセルでは空行を保持します（#57、デフォルトはオフ、CLI --keep-empty-paragraphs に対応）
dedupe_running_headers	boolean	いいえ	HWP5 レイアウト表でページをまたいで繰り返されるランニングヘッダーを重複削除します（デフォルトはオフ — 添付資料ごとの再採番を誤って削除しないよう注意してください。CLI --dedupe-headers に対応）
keep_trailing_empty_cols	boolean	いいえ	表の右端にある空列（書式入力欄）を保持します（#47、デフォルトはオフ：末尾の空列をトリミング、CLI --keep-empty-cols に対応）
include_field_placeholders	boolean	いいえ	未入力のフィールドプレースホルダーの説明も出力 — 空の書式文書で各欄の用途を保持します（#92、デフォルトはオフ、CLI --include-field-placeholders に対応）

詳細

kordoc

何でもパースしてしまいます。

韓国でも屈指の文書地獄。そこで7年間耐え抜いた公務員が作りました。

HWP 3.x・5.x、HWPX、HWPML、PDF、XLS・XLSX、DOCX、PPTX、PNG・JPG・WebPをMarkdownと構造化データに変換します。ライブラリ・CLI・MCP サーバーとして利用できます。

English · 詳しい使い方 · ベンチマーク · 変更履歴

同じ法令の別表をHWP・HWPX・PDF・スキャン画像で読み込ませたkordocの実際の出力

_{同じ法令の別表1件をHWP・HWPX・PDF・スキャン画像で読み込ませた実際の出力です。4つのケースすべてで、結合セル（rowspan・colspan）を同じ構造の表として読み取ります。スキャン画像ではOCRが自動的に有効になります。}

📊 PDF公開ベンチマーク総合スコア0.964：opendataloader-benchの200文書で、公開リーダーボード上の12個のパーサーを上回るスコア（4.22.14で測定）。測定条件
🇰🇷 韓国の公文書の表構造を100%再現：元のHWPX 2,424文書にある、表示される表10,342個すべての構造が一致。検証結果

役に立ったら、GitHubで⭐を1つ押してください。他の人がこのツールを見つける助けになります。

動画：公開ベンチマークの測定過程（2026-09-27版、1分31秒） · フォーム一括入力のデモ

インストール

Node.js 20以上 · macOS / Linux / Windows

npm install kordoc

CLIはインストールせずにnpx kordocで実行できます。PDF・OCRの依存関係はデフォルトでインストールされます。--omit=optionalで除外すると、該当機能が制限されます。

AI エージェントに接続

npx -y kordoc setup

Claude Desktop・Claude Code・Cursor・Codexなど、インストール済みのクライアントにMCPを登録します。クライアントを再起動すると、パース・比較・生成・検査・レンダリングなど18個のツールを利用できます。

Claude Codeプラグイン：

/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc

手動でのMCP登録とインストールの問題解決

クイックスタート

CLI

npx kordoc 문서.hwpx -o 문서.md
npx kordoc *.pdf --jobs 4 -d ./결과
npx kordoc 문서.pdf --format json --pages 1-3
npx kordoc 스캔본.pdf --ocr -o 스캔본.md
npx kordoc generate 보고서.md --preset 보고서 -o 보고서.hwpx
npx kordoc fill --template gian -j 값.json -o 기안문.hwpx
npx kordoc lint 보고서.hwpx --gate --preset 보고서

--jobsはファイル単位の並列変換で、メモリ使用量も増加します。並列変換ガイド

JavaScript / TypeScript

import { parse, markdownToHwpx } from "kordoc"
import { writeFile } from "node:fs/promises"

const result = await parse("문서.hwpx")
if (result.success) {
  console.log(result.markdown)
  // result.blocks: 구조화 데이터, result.metadata: 문서 정보
}

const hwpx = await markdownToHwpx("# 추진계획\n\n본문", {
  gongmun: { preset: "보고서" },
})
await writeFile("보고서.hwpx", Buffer.from(hwpx))

パースオプション・API・フォーム・レンダリングの例

主な機能

作業	機能
読み取り	文書 → Markdown・IR・ページごとの本文・RAGチャンク、ローカルOCR
比較・編集	ブロック・セル単位の比較、HWPX・HWPの書式を保持したパッチ、見本の書式をそのまま使った新規コンテンツの作成
作成	Markdown → HWPX、公文書プリセット・部署の書式見本（`--template`）、表・数式・グラフ
フォーム	フィールド・入力枠への入力、標準起案書2種類、印鑑の押印
検査	表記法・公用文、構成・AI文体のゲート、予算積算根拠の検算、開いている文書をブロック単位で検査（`lint-blocks`）
表示・セキュリティ	HWPX・HWPのプレビュー・領域抽出、個人情報のマスキング

書式を保持したパッチ用のMarkdownは、--keep-layout-tablesで抽出します。適用できなかった編集は、スキップした理由とともに報告します。書式を保持した編集 · CLI全体

検証結果

4.22.14 · 2026-10-19検証。固定コーパスと参照基準で測定した結果です。

対象	規模	結果
HWPX	2,424文書 · 10,342表	表構造の一致 10,342/10,342 · 100%
HWP 5.x ↔ HWPX	1,130組 · 4,315表	対応する文書の表構造の一致 100%
PDFの文章	744組	文字再現率 99.879% · 精度 99.670% · 読み取り順序 99.247% · 語節F1 99.049%
PDFの表	708組 · 2,331表	表の検出 99.87% · 構造の一致 98.16% · セルF1 0.9918
HWPXの再組版	複数行の25,187段落（12フォルダー）	すべての行頭の一致 24,941/25,187 · 99.02%
PDFの入れ子表（テキスト層）	29文書 · 101表	構造・セル内容 101/101 · 100%
法令の別表	272件 · 346表	HWP 346/346、PDF 342/346 · 98.84%
PDF全体	1,911文書中1,729件を採点	文章のカバレッジ 99.80%
OCR	53文書 · 102ページ	CER 0.0409 · 文字再現率 99.02%
opendataloader-bench	PDF 200文書	デフォルトの総合スコア 0.964 · OCR無効 0.939

表構造のスコアと、セル内容・画面上の再現性は別の指標です。入れ子表の100%は上記の101表に限られ、PDF全体や組版全体が完全に一致することを意味しません。採点範囲・除外基準・オプションごとの数値・再現方法はベンチマークの詳細をご覧ください。

자주 묻는 질문

Q. HWP·HWPX 파일을 Markdown으로 바꾸려면? npx kordoc 문서.hwp -o 문서.md 한 줄입니다. 한컴오피스 없이 파일을 직접 읽으며, 여러 파일은 npx kordoc *.hwpx -d ./output으로 한 번에 바꿉니다.

Q. Claude·Cursor 같은 AI가 한글 문서를 읽게 하려면? npx -y kordoc setup으로 MCP를 등록하면 AI가 파일 경로만 받아 HWP·PDF·엑셀을 읽고, 비교하고, 양식을 채웁니다.

Q. 인터넷이 막힌 폐쇄망에서도 되나요? 됩니다. KORDOC_OFFLINE=1이 외부 통신을 모두 막고, OCR도 API 키 없이 로컬 CPU에서 돕니다. 폐쇄망 설치

Q. RAG 색인용으로 쓸 수 있나요? --format chunks가 제목 경로를 붙인 구조 청크와 독립 표 청크를 냅니다. 표를 HTML 없이 받으려면 --table-format gfm(API는 tableFormat: "gfm")을 씁니다. Python·Java에서는 Python SDK·Java SDK로 부릅니다.

Q. OCR 줄 좌표나 다른 모델이 필요하면? --ocr --ocr-lines --format json이 줄별 상자·신뢰도를 내고, --ocr-det·--ocr-det-long-side로 검출 모델과 해상도를 고릅니다. OCR 줄·모델 선택

문서·보안

상세 사용법: 전체 CLI·MCP 도구·API·지원 포맷
Java SDK · Python SDK: 상주 엔진 워커로 Java·Python 시스템에서 파싱 (워커 프로토콜)
공문서 생성 가이드 · 아키텍처
폐쇄망 설치: KORDOC_OFFLINE=1, MCP 접근 범위 KORDOC_ROOT
보안 정책 · 라이선스 MIT · 오픈소스 고지

만든 사람

대한민국 지방공무원. 광진구청에서 7년간 HWP 파일과 싸우다가 이걸 만들었습니다. 5개 공공 프로젝트에서 수천 건의 실제 관공서 문서를 파싱하며 검증했습니다.

Markdown 対応

ログインしてコメント

基本情報

作者: chrisryugj
言語: node
バージョン: 4.24.16
トランスポート: stdio
掲載日: 2026年10月28日
最終更新: 今日
公式 Registry: io.github.chrisryugj/kordoc

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

バージョン	主な変更
4.24.1	検査の修正：ブロック検査での疎な表によるメモリの急増、千ウォン規則の二次時間、予算検算（リスト行・小計（A）・比率行）、`generate --template`での見本の上書き防止
4.24.0	ブロック単位の検査`lintBlocks`：開いている文書の段落・表のセルをブロックとして渡すと、指摘をブロックID・ブロック内の位置とともに返します（CLI `lint-blocks`、MCP `lint_document`、ワーカー、Python SDK）
4.23.1	見本からの生成で、タイトル表の決裁欄を役職別に作成。積算根拠の行・表セルにおける千ウォン単位の誤検出を削除
4.23.0	部署の書式見本を使った新規文書の作成（`generate --template`）、予算文書の検査（`lint --budget`）、MCP `lint_document`
4.22.18	kordoc生成レポートのタイトル枠・章帯・要約ボックスのパッチ、変更履歴を含むHWPパッチの結果がハングルで表示されなかった問題

kordoc

kordoc について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

kordoc

インストール

クイックスタート

CLI

JavaScript / TypeScript

主な機能

検証結果

最近の更新

자주 묻는 질문

문서·보안

만든 사람

コメント

MCP は初めてですか？

MCP（Model Context Protocol）とは？

MCP サーバーとクライアントの違いは？

ローカルとリモート、どちらを選ぶべき？

Claude や Cursor にサーバーを導入するには？

掲載プロジェクトは審査されていますか？「認証済み」とは？

自分のプロジェクトが掲載されています。どう申請できますか？