Hwpx MCP

🚀 HWPX MCP Server - 拡張版

🚀 元プロジェクトをフォークし、安定性と機能を大幅に改善したバージョンです。

AIツール（Claudeなど）と連携して、韓国語（HWPX）文書を自動的に編集できるMCP（Model Context Protocol）サーバーです。

🚀 クイックスタート

AIツール（Claudeなど）と連携して、韓国語（HWPX）文書を自動的に編集できるMCP（Model Context Protocol）サーバーです。

✨ 主な機能

🌍 クロスプラットフォーム対応

すべてのオペレーティングシステムで動作します！

なぜ可能なのですか？ HWPXファイルは ZIP + XML構造 です。ハングルソフトウェアがなくても、Node.jsだけで完全に読み書きできます。

*LibreOfficeはHWPXを制限的にサポートしています。完全な互換性のために、ハングルオフィスの使用をお勧めします。

✨ 拡張機能

元のプロジェクトと比較して、次のような 重要な問題を解決 しました。

🔧 重大なバグ修正

🛠 技術的な改善

1. 原子的なファイル書き込み

   • 一時ファイル → ZIP検証 → 原子的な移動
   • 保存中にエラーが発生しても元のファイルが保護されます

2. スマートな行レイアウトのリセット

   • テキストを編集すると lineseg が自動的にリセットされます
   • ハングルソフトウェアを開くと自動的に改行が再計算されます
   • テキストの重なり現象が完全に解消されます

3. 深さベースのXMLパーシング

   • 既存の遅延正規表現の入れ子構造の誤認識問題を解決します
   • 複雑なテーブル（入れ子テーブル、サブリストなど）を完全にサポートします

4. 完全なスタイル保存

   • charPr、spacing などの元のスタイルを100％維持します
   • 不完全なシリアル化ロジックを削除してデータの整合性を保証します

5. 安全な複数セルの更新

   • 同じ行（row）の複数のセルを同時に編集しても安全です
   • 行ごとのグループ化 + 逆順処理によりインデックスの損傷を防止します

📦 インストール

1. MCPサーバーのインストール

git clone https://github.com/Dayoooun/hwpx-mcp.git
cd hwpx-mcp/mcp-server
npm install
npm run build

2. MCPクライアントの設定

以下から使用するクライアントを選択してください。

🖥️ Claude Desktop

設定ファイルの場所:

設定内容:

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["C:/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

⚠️ Windowsではパスに \\ または / を使用してください（例: C:/Users/username/hwpx-mcp/...）

💻 Claude Code (CLI)

方法1: プロジェクトごとの設定 (.mcp.json ファイルをプロジェクトのルートに作成)

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

方法2: グローバル設定 (~/.claude/settings.json)

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

方法3: CLIコマンドで追加

claude mcp add hwpx-mcp node /path/to/hwpx-mcp/mcp-server/dist/index.js

🔷 Cursor

設定ファイル: ~/.cursor/mcp.json (ない場合は作成)

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

または Cursor Settings > MCP から直接追加することもできます。

🆚 VS Code (MCP拡張を使用する場合)

設定ファイル: .vscode/mcp.json (プロジェクトフォルダ内)

{
  "servers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["${workspaceFolder}/../hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

${workspaceFolder} 変数を使用すると相対パスを指定できます

🛠️ その他のMCPクライアント

一般的なMCP設定形式:

{
  "mcpServers": {
    "hwpx-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/hwpx-mcp/mcp-server/dist/index.js"]
    }
  }
}

パスの例:

3. インストールの確認

クライアントを再起動した後、MCPツールのリストに hwpx-mcp サーバーと77個のツールが表示されれば成功です！

💻 使用例

基本的な使用法

// 文書を開く
await mcp.open_document({ file_path: "report.hwpx" })

// テーブルセルを編集する
await mcp.update_table_cell({
  doc_id: "...",
  section_index: 0,
  table_index: 0,
  row: 0,
  col: 1,
  text: "修正された内容"
})

// 入れ子テーブルを挿入する（表の中に表）
await mcp.insert_nested_table({
  doc_id: "...",
  section_index: 0,
  parent_table_index: 0,
  row: 1,
  col: 2,
  nested_rows: 2,
  nested_cols: 2,
  data: [["A1", "A2"], ["B1", "B2"]]
})

// Mermaidダイアグラムを挿入する
await mcp.render_mermaid({
  doc_id: "...",
  mermaid_code: "graph TD; A-->B; B-->C;",
  after_index: 0,
  theme: "default"
})

// 保存する
await mcp.save_document({ doc_id: "..." })

高度な使用法

テーブルセルの検索/置換ワークフロー

同じテキストが複数の場所にある場合、特定の位置 のみを編集する方法:

// 1. テーブルを含む検索で位置を特定する
const results = await mcp.search_text({
  doc_id: "...",
  query: "修正対象",
  include_tables: true  // テーブルセルを含む
})
// 結果: [{ text: "修正対象", location: { type: "table", tableIndex: 2, row: 3, col: 1 } }, ...]

// 2. 目的の位置のセルのみを精密に置換する
await mcp.replace_text_in_cell({
  doc_id: "...",
  section_index: 0,
  table_index: 2,  // 検索結果で確認した位置
  row: 3,
  col: 1,
  old_text: "修正対象",
  new_text: "新しい内容"
})

📚 ドキュメント

🔌 MCPツール (77個)

📁 文書管理 (Document Management) - 5個

📄 文書情報 (Document Info) - 5個

📝 段落 (Paragraphs) - 8個

🎨 テキストスタイル (Text Styling) - 4個

🔍 検索/置換 (Search & Replace) - 4個

📊 テーブル (Tables) - 12個

📐 ページ設定 (Page Settings) - 2個

🖼️ 画像 (Images) - 5個

✏️ 図形 (Shapes) - 3個

📑 ヘッダー/フッター (Header/Footer) - 4個

📌 脚注/章末注 (Footnotes/Endnotes) - 4個

🔗 ブックマーク/ハイパーリンク (Bookmarks/Hyperlinks) - 4個

➗ 数式 (Equations) - 2個

💬 メモ (Memos/Comments) - 3個

📚 セクション (Sections) - 5個

🎭 スタイル定義 (Style Definitions) - 4個

📰 段設定 (Column Layout) - 2個

📤 エクスポート (Export) - 2個

↩️ 元に戻す/やり直す (Undo/Redo) - 2個

📋 サポートされる形式

注意: HWP（バイナリ）ファイルはサポートされていません。ハングルオフィスでHWPXに変換してから使用してください。

📝 リリースノート

v0.4.0 (拡張検索とダイアグラムサポート)

• 🆕 新機能: search_text に include_tables オプションを追加 - テーブルセル内のテキストも検索できます
• 🆕 新機能: replace_text_in_cell - 特定のテーブルセル内のテキストのみを精密に置換できます
• 🆕 新機能: render_mermaid - Mermaidダイアグラムを画像として文書に挿入できます
  • フローチャート、シーケンス、クラス図など、すべてのMermaid文法をサポートします
  • テーマを選択できます（default, dark, forest, neutral）
• 🆕 新機能: get_section_xml / set_section_xml - セクションのRaw XMLを直接操作できます
  • AIベースの高度な文書編集シナリオをサポートします
• 🔧 改善: insert_image を完全に改善しました
  • BinDataフォルダに画像を自動保存します
  • content.hpfマニフェストを自動登録します
  • ファイル損傷なしで画像を挿入できます

v0.3.0 (入れ子テーブルのサポート)

• 🆕 新機能: insert_nested_table - テーブルセル内に入れ子テーブルを挿入する機能
  • 親テーブルの特定のセルに新しいテーブルを挿入できます
  • 初期データを指定できます（2D配列）
  • HWPX標準構造（treatAsChar, hp:subList）を完全に遵守します
• 🔧 改善: charSpacingのパーシングを改善しました（属性の順序に関係なく処理します）

v0.2.1 (重大な修正)

• 🔥 重大な修正: 同じ行に複数のセルを同時に編集する際のファイル損傷問題を完全に解決しました
  • 行（row）ごとの更新をグループ化してインデックスの不一致を防止します
  • 逆順（descending）処理により安全なXML編集を保証します

v0.2.0 (拡張版)

• 🔥 主要な修正: テキストを編集する際にlinesegを自動的にリセットして、重なり現象を完全に解消しました
• 🔧 バグ修正: 入れ子テーブル構造でのXML要素の境界の誤認識問題を修正しました
• 🛡️ 安定性: 原子的なファイル書き込みによりファイル損傷を防止します
• 📦 保存: 元のcharPr/spacingスタイルを完全に保存します

v0.1.0 (元のバージョン)

• 最初のリリース（mjyoo2/hwp-extension）

🙏 クレジット

• 元のプロジェクト: mjyoo2/hwp-extension
• 拡張: Dayoooun

📄 ライセンス

MIT

🤝 コントリビューション

バグレポートや機能リクエストは、GitHub Issues で行ってください。