docx-mcp-server: Instructions file for Claude Code

CLAUDE.md — docx-mcp-server

ローカル MCP サーバ。DOCX ファイルの読み取り・編集・書式設定・コメント・画像一覧を提供する。

ファイル構成

src/
  index.ts            … MCP サーバ本体（ツール登録・stdio transport）
  docx-engine.ts      … バレルモジュール（engine/* を再エクスポート + 公開 API 関数）
  engine/
    xml-helpers.ts    … XNode 型定義、fast-xml-parser の parser/builder、DOM ヘルパー
    docx-io.ts        … DOCX の ZIP 読み書き (JSZip)、ErrorCode/EngineError
    text.ts           … テキスト抽出、ブロック列挙、cross-run 置換、track changes
    formatting.ts     … 文字書式 (bold/italic 等)、段落書式 (alignment/spacing 等)
    comments.ts       … コメント XML 解析、アンカーマッチング、マーカー挿入
    layout.ts         … ページサイズ / マージンのプリセットと変換
    images.ts         … 画像一覧（リレーションシップ解析、w:drawing 走査）
    anchors.ts        … 安定アンカー (w14:paraId) の生成・収集・名前空間付与・解決
    file-lock.ts      … ファイル単位の Promise チェーン書き込みロック
  __tests__/
    helpers.ts        … テストユーティリティ（tmp ファイル管理、フィクスチャ生成）
    docx-reading.test.ts
    docx-editing.test.ts
    docx-formatting.test.ts
    docx-comments.test.ts
    docx-structure-layout.test.ts
    docx-advanced-features.test.ts
    docx-bulk-operations.test.ts
    file-lock.test.ts

モジュール依存グラフ（非循環）

xml-helpers ← docx-io ← text ← formatting
                    ↑
                    ├── comments
                    ├── images
                    └── anchors
              layout (独立)
              file-lock (独立)

ビルド・テスト

npm run build     # TypeScript → dist/
npx vitest run    # 全テスト実行

ツール使用ワークフロー（推奨）

1. get_document_info でドキュメント全体を俯瞰する。総ブロック数・末尾ブロックインデックス（lastBlockIndex）・語数/文字数・見出しアウトライン（各見出しが担当する節のブロック範囲 [blockIndex, endBlock] 付き）・末尾追加ヒント（appendHint）が返る。挿入位置を決める前に必ずここで全体像を取る。「末尾に追加」は insert_paragraphs(position: -1) を使う（部分的に read_document した窓の最後のインデックスを文書末尾と取り違えない）
2. read_document で対象範囲を読む（start_paragraph / end_paragraph で範囲指定可能）
3. search_text で編集対象のブロックを特定する（テーブル内のマッチは row/col 付きで返る）
4. ピンポイント確認には軽量ツールを使う: read_table_structure / read_table_cell（全体を読まずにテーブルを調べる）、get_paragraph_format（段落書式を調べる。copy_format_from の参照元探しに有用）
5. 編集系ツール（edit_paragraphs, replace_texts 等）で変更を行う