jDocmunch MCP

jDocMunch MCP

jDocMunch は、ファイル全体をコンテキストウィンドウに読み込まずに、タスクに必要なドキュメントの正確なセクションを取得する、コーディングエージェント向けの MCP サーバーです。

ドキュメントセットを見出し階層で一度インデックス化すれば、単一のセクション、見出しのサブツリー、またはランキング付きの検索結果を取得できます。いずれも元のファイルからバイト単位で正確に抽出されます。

インストール · クイックスタート · ベンチマーク · 商用ライセンス

個人利用は無料です。 商用利用には有料ライセンスが必要です — 以下の条件をご覧ください。

---

jDocMunch が選ばれる理由

問題点。 エージェントが「認証の設定方法は？」と尋ねられると、ドキュメントファイルを開いて、必要のない何百もの段落に目を通し、別のファイルを開いて同じことを繰り返します。コンテキストウィンドウが大きくても、この問題は解決しません。無駄なコストが請求書を見るまで気にならない程度になるだけで、モデルが本当に必要としていたコンテキストを圧迫します。

仕組み。 jDocMunch は、ドキュメントセットを見出し階層に基づくセクションツリーに解析し、各セクションのバイトオフセットを元のファイルへの参照として保存して、MCP 経由の取得機能を提供します。パス、見出しテキスト、見出しレベルが変わらない限り、再インデックス化後もセクションの識別子は維持されます。

効果。 アクセス単位がファイルからセクションに変わります。エージェントはインストールのセクション、設定ブロックの一つ、特定の見出しのサブツリーだけを取得し、それ以外は取得しません。

---

他との違い

セクション優先の取得

ファイルパスやキーワードの一致だけでなく、セクション単位でドキュメントを検索・取得します。

バイト単位で正確な抽出

元のファイルの正確なバイトオフセットから、必要に応じてコンテンツ全体を取得します。

安定したセクション ID

パス、見出しテキスト、見出しレベルが変わらない限り、再インデックス化後もセクションの識別子は維持されます。

---

エビデンス

公開ドキュメントコーパスを対象とした4つのベンチマークです。コーパス、日付、クエリごとの結果をそれぞれ benchmarks/ に記録しています。

コーパス	規模	インデックス作成時間	結果
Kubernetes（kubernetes/website、2026-03-04）	1,569 個の .md ファイル、4,355 セクション、16 MB	3,352 ms	ノードアフィニティに関する単一クエリで 27,285 トークンを節約、レイテンシー 100 ms
SciPy	10,402 セクション、コーパス約 855,000 トークン	2,247 ms	スパースソルバー、FFT、最適化の検索で、クエリあたり 135～152 ms
LangChain（MDX）	5,973 セクション	5,204 ms	MDX 対応のセクション分割により、単純な処理より 754% 多くのセクションを検出
Wiki	コーパス 7,449 トークン	—	コーパス全体を読み込むと 7,449 トークンかかるのに対し、検索ではランク付けされたメタデータを約 190 トークンで返します

これらはコーパスごとの結果として捉えてください。単一の代表的な倍率ではありません。 節約量は、必要なセクションに対する元ファイルの大きさによって異なります。見出しが1つだけの小さなファイルではほとんど節約できませんが、Kubernetes コーパスでは大きな節約になります。ベンチマークファイルには、良好な結果が出たクエリだけでなく、結果が振るわなかったクエリも記録しています。

v1.121.0 の projection 作業で得られた、別途測定した結果もあります。このリポジトリのドキュメントに対し、max_results=10 で検索した場合、検索結果の1行は compact=true で 1,989 chars → 319（−84%）、または snippet_bytes=200 で 431（−78%）となり、後続の get_section 呼び出しも不要になりました。

検索品質は想定するのではなく、ゲートで検証します。 リリースごとに、固定されたゴールデンセットを使った再生フィクスチャを実行し、nDCG 0.95 を下回ると失敗します。このゲートによってビルドが失敗し、リリースがブロックされたこともあります。飾りではありません。

---

インストール

要件： Python 3.10 以降、MCP 対応クライアント。

uv tool install jdocmunch-mcp
jdocmunch-mcp init

仮想環境の管理は不要で、システムの Python に何も書き込まず、何も変更せずにそのまま動作します。また、pip install が拒否される PEP 668 対応ディストリビューション（Ubuntu 24.04 以降、Debian 12 以降）でも動作します。まだ uv をお使いでない場合はこちらをご覧ください。

init は MCP クライアントを検出して設定項目を書き込み、エージェントが実際にツールを使うように、ドキュメント探索プロンプトのポリシーをインストールします。さらに、フックのインストールやドキュメントのインデックス作成も任意で行えます。

その他のインストール方法

コマンド	使用するケース
uvx jdocmunch-mcp	インストール不要。 一時的な環境から実行されるため、ディスクに恒久的なファイルは残りません。init が書き込むクライアント設定ではすでにこの方法でサーバーを起動するため、ほとんどのセットアップでは実行するのはこれだけです。⚠ フックは例外です。最小限の PATH を持つサブシェルから起動され、実行ファイルを名前で解決するため、動作させるには uv tool install（または pipx／pip）が必要です。
pipx install jdocmunch-mcp	すでに pipx を標準的に使用している場合
pip install jdocmunch-mcp	自分で管理する仮想環境内で使う場合

動作確認：

jdocmunch-mcp --version

Claude Code を手動でセットアップする場合：

claude mcp add -s user jdocmunch -- uvx jdocmunch-mcp

インストール手順は不要です。uvx が必要に応じてサーバーを取得して実行します。PATH 上で使いたい場合（また、フックには必須です）は、uv tool install jdocmunch-mcp を実行してから、claude mcp add -s user jdocmunch jdocmunch-mcp を実行してください。

サーバーをインストールするとツールを使えるようになりますが、エージェントがファイルを片っ端から読み込む習慣は変わりません。それを変えるのは、CLAUDE.md に追加する次の1行です。

Call the jdocmunch_guide tool and strictly follow its instructions.

---

クイックスタート

前提： jDocMunch がインストールされ、クライアントに登録されていること、およびドキュメントのフォルダーがあること。

ローカルのドキュメントフォルダーをインデックス化します。

jdocmunch-mcp index-local --path ./docs

コーパスの名前と検出した内容を示す JSON が出力されます。

{
  "success": true,
  "repo": "local/docs",
  "file_count": 1,
  "section_count": 4,
  "doc_types": { ".md": 1 },
  "semantic_search": false
}

section_count が file_count より大きいことが重要です。インデックスがファイルではなく見出しを対象にしているためです。

次に、エージェントで以下のように指示します。

jdocmunch を使って、「authentication configuration」に関するドキュメントを検索し、そのセクションを表示してください。

エージェントは search_sections を呼び出し、次に最上位の検索結果に対して get_section を呼び出します。ファイルではなく、1 つのセクションが返されます。get_section のレスポンスにある _meta.tokens_saved は、推定による節約量です。これは、ドキュメント全体のサイズから提供されたセクションのサイズを差し引いた値です（_meta.savings_basis: "modeled"）。search_sections 自体は節約量に加算されません。

次のステップ： コーパス全体の構造を確認するには get_toc_tree を、GitHub リポジトリからドキュメントを直接インデックス化するには index_repo を使います。

非常に大きなフォルダー

MCP クライアントは、一定時間が経過するとツール呼び出しの応答待ちを終了します。数万個のファイルがあるフォルダーのインデックス化には、それ以上の時間がかかる場合があります。ある Windows マシンでは、ファイル数 10,000（セクション数 271,585）のフォルダー全体のインデックス化に、埋め込みなしで 67 秒かかり、sentence-transformers の埋め込みを追加すると約 3 分かかりました。

フォルダーがこれほど大きい場合、または index_local の呼び出しがタイムアウトする場合は、シェルからインデックス化してください。

jdocmunch-mcp index-local --path /path/to/folder

CLI はツールのタイムアウトなしで同じインデックス化を実行します。MCP サーバーと同じストアに書き込むため、コマンドの完了後にサーバーがそのインデックスを使用します。クライアントの MCP 設定で DOC_INDEX_PATH を設定している場合は、シェルでも設定してください。

• カスタム名。 フォルダーをカスタム名でインデックス化した場合は、同じ --name を渡してください。渡さないと、CLI はフォルダー名を使用して 2 つ目のインデックスを書き込みます。
• ファイル数の上限。 フォルダー内のファイル数は、新しい順に最大 10,000 件に制限されます。--max-files N（MCP ツールの max_files に対応する CLI オプション）で上限を引き上げられます。上限に達した場合、警告にはフォルダー内で検出されたファイル数とともにコマンドが表示されます。
• フォルダーの絞り込み。 不要なものは --extra-ignore-pattern（繰り返し指定可能。extra_ignore_patterns に対応する CLI オプション）で除外するか、--paths-from FILE（paths に対応する CLI オプション）を使って、指定したファイルのみをインデックス化してください。
• 埋め込み。 --no-embeddings を指定すると、最初に語彙インデックスを作成します。後でコマンドを再実行し、--rebuild を指定すると、埋め込みを追加できます。

スキャン PDF

スキャン PDF は、検索用のテキストレイヤーがない、テキストの画像です。オプションの [ocr] エクストラを使うと、すでにお使いのマシンにある OCR エンジンで読み取れます。jDocMunch がエンジン、言語パック、モデルをインストールまたはダウンロードすることはありません。

pip install "jdocmunch-mcp[ocr]"

エンジン。 jDocMunch は次の順にエンジンを探し、応答した最初のものを使用します。

1. 設定されている場合は JDOCMUNCH_TESSERACT_PATH。
2. PATH 上の tesseract。
3. Tesseract の既定のインストールフォルダー：C:\Program Files\Tesseract-OCR、ユーザーごとの %LOCALAPPDATA%\Programs 内のフォルダー、/opt/homebrew/bin、/usr/local/bin、/usr/bin。
4. Windows では、英語の OCR 言語がインストールされている場合（英語版 Windows にはインストールされています）、組み込みの Windows OCR。

JDOCMUNCH_OCR_ENGINE=tesseract または windows でエンジンを選択できます。JDOCMUNCH_OCR_LANG は、インストール済みの Tesseract 言語を指定します（既定値は eng）。

OCR を実行するには、2 つのキーが必要です。 両方が設定されている場合にのみ実行されます。

• MCP クライアントの env ブロック（または CLI の場合はシェル）で、ユーザーが JDOCMUNCH_OCR=1 を設定します。
• 呼び出し側が OCR を要求します：index_local(ocr=true)、または CLI の index-local --ocr。

そのため、エージェントが単独で OCR を有効にすることはできません。この選択はインデックスとともに保存され、後続の更新とウォッチャーでも引き継がれます。ocr=false または --no-ocr で無効にできます。OCR を要求して実行したすべての応答には ocr ブロックが含まれ、設定で有効になっていたか、実際に使用されたか、読み取った量、および使用したエンジンが示されます。

得られる結果。 スキャン画像はそれぞれ ## Page N セクションになります。OCR による各セクションには text_source: "ocr" のマークが付き、ocr_engine、ocr_pages、および（Tesseract のみ）ocr_confidence が含まれます。ドキュメントの冒頭には、テキストが OCR によるものであることを示す注記が表示され、応答でもその旨が警告されます。PDF 内で独自のテキストレイヤーを持つ部分は、そのまま保持されます。OCR セクションは、トークン削減の評価対象にはなりません。

精度。 印刷された文章のパブリックドメインのスキャン画像 6 点（『Encyclopaedia Britannica 1911』と『The American Printer』）でのテストでは、Tesseract 5.4 は単語の 97.4％を検出し、文字誤り率は 2.0％でした。Windows OCR は、それぞれ 97.1％と 2.0％でした。制限事項は次のとおりです。

• 表やフォームは乱れた状態で出力される場合があります。 単語の大半は認識されるため検索できますが、列やフィールドのレイアウトは失われます。スキャンしたフォーム 2 点では、Tesseract が検出した単語は 25％から 80％でした。
• 装飾書体やブラックレター（ゴシック体）は読み取れません。 どちらのエンジンも読み取れません。
• 手書き文字は読み取れません。

速度。 この環境では、Tesseract は画像 1 枚あたり 3.4 秒（Windows OCR は 0.3 秒）かかりました。画像 20 枚のスキャンでは、Tesseract で 69 秒、Windows OCR で 6 秒でした。MCP 呼び出しで OCR に割り当てられる時間は 60 秒（ocr_budget_seconds）なので、Tesseract の場合、画像が 20 枚以上あるスキャンは 1 回の呼び出しで完了しないことがあります。 ocr_budget_exhausted としてスキップされます。すでに読み取った内容はキャッシュされ、次の呼び出しで続きから処理されます。スキャン画像のフォルダーを処理する場合は、時間制限のない CLI を実行してください。

JDOCMUNCH_OCR=1 jdocmunch-mcp index-local --path /path/to/scans --ocr

ドキュメント内のスキャン画像は最初の 50 枚まで読み取られます（ocr_max_pages、--ocr-max-pages）。残りは ocr_pages_capped として報告されます。

プライバシー。 OCR はお使いのマシン上で実行されます。Tesseract はローカルプログラムで、Windows OCR はデバイス上で動作する Windows API です。ページがマシンの外に送信されることはありません。ただし、OCR によってスキャン画像は検索可能なテキストになります。納税申告書、給与明細、身分証明書、医療記録を OCR にかけると、その内容（名前、SSN、口座番号など）は、このインデックスを検索できるすべてのエージェントが読み取れるようになり、ディスク上のインデックスのテキストキャッシュにも保存されます。jDocMunch の秘密ファイルのルールは内容ではなくファイル名に適用されるため、スキャンした W-2 は検出されません。そのようなファイルはインデックス対象のフォルダーに入れないか、extra_ignore_patterns で除外してください。

---

できること

• ドキュメント全体ではなく、セクションを取得できます。 get_section と get_sections は、元ファイルからバイト単位で正確な内容を取得します。get_section_excerpt では、さらに範囲を絞れます。
• キーワードだけでなく、意味で検索できます。 埋め込みプロバイダーを設定すると、search_sections は BM25 と意味的なコサイン類似度を組み合わせます。compact=true、fields=[...]、snippet_bytes=N を使うと、レスポンスをさらに縮小できます。
• 構造をたどれます。 get_toc、get_toc_tree、get_section_path、get_section_descendants、section_neighbors を使うと、内容を読まずに見出しツリーをたどれます。
• ドキュメントに不足している情報や古くなった情報を見つけられます。 get_doc_coverage、get_undocumented_symbols、get_stale_pages、get_orphan_sections、get_broken_links、doc_health_radar を利用できます。
• API 仕様を横断して作業できます。 find_endpoint、list_endpoints_by_tag、find_operations_using_schema、get_schema_graph は、OpenAPI ドキュメントを第一級の対象として扱います。
• ドキュメント変更を事前確認できます。 セクションを削除または再構成する前に、check_section_delete_safe と get_section_blast_radius を使えます。
• 回答が古くなっていないか確認できます。 コンテンツの読み取りでは、_meta.freshness、_meta.verdict と、どのソースレイヤーが回答したかが示されます。

ツールは合計 64 個です。全リファレンスは USER_GUIDE.md をご覧ください。

---

動作の仕組み

すべてローカルで動作します。インデックスはホームディレクトリ以下に保存され、インデックス作成や検索にホスト型サービスは必要ありません。

docs/ ──► parser (per format) ──► section tree ──► local index
                                                      │
                          MCP client ◄── retrieval ◄──┘

• 解析は形式ごとにモジュールを分けています。Markdown/MDX、reStructuredText、AsciiDoc、Jupyter ノートブック、HTML、プレーンテキスト、OpenAPI（YAML）、JSON/JSONC、XML/SVG/XHTML、Godot シーンに対応しています。また、オプションの [office] extra を使うと、PDF、DOCX、PPTX、EPUB にも対応します。
• ストレージはバージョン管理されたローカルインデックス（INDEX_VERSION = 3）で、初回読み込み時に自動的に移行されます。1.x リリースでは、インデックスの再作成を強制されません。
• 検索はデフォルトで語彙的な BM25 を使用し、埋め込みが利用可能な場合はハイブリッド検索になります。
• 埋め込みはオプションで、プロバイダーに依存しません。Gemini、OpenAI、OpenAI 互換エンドポイント、または FastEmbed（ONNX）か sentence-transformers（torch）を通じて利用するローカルのオフラインモデルに対応しています。設定しない場合、検索は語彙的な方式のままで、完全にオフラインで動作します。

詳しくは、ARCHITECTURE.md と SPEC.md をご覧ください。

長時間実行プロセスでのメモリ使用量

解析済みインデックスは、ファイルサイズの約 2.5～3 倍のメモリを使用します（実際の 5 つのインデックスで測定。サイズは 0.5 MB～112 MB）。次の 2 つの設定で、長時間実行プロセスのメモリ使用量を制限できます。

• JDOCMUNCH_INDEX_CACHE_MAX_BYTES は、サーバーが呼び出しの間に解析済みの状態で保持するインデックスの上限を設定します。デフォルトは 512 MiB で、各インデックスファイルのサイズの 3 倍として見積もられます。この上限を超えると、最も長く使われていないインデックスが破棄され、次に必要になったときに再読み込みされます。上限を超えるサイズのインデックスも 1 つまでは保持されます。0 以下にするとバイト数の上限は無効になりますが、8 インデックスの上限はそのまま適用されます。
• JDOCMUNCH_WATCH_INPROCESS=1 を指定すると、watcher はバッチごとに子プロセスを起動せず、自身のプロセス内でインデックスを再作成します（下記を参照）。

---

セキュリティとプライバシー

設計上、ローカルファーストです。ドキュメントはお使いのマシン上で解析・保存されます。基本パッケージのデフォルトのネットワーク動作は、匿名の節約量カウンターのみです。ランダム ID と集計されたトークン数のみを送信し、コンテンツ、パス、個人を特定できる情報（PII）は送信しません。

完全にオプトアウトするには：

JDOCMUNCH_SHARE_SAVINGS=0

埋め込みプロバイダーと要約プロバイダーは、有効にした場合に限り設定済みの API を呼び出します。デフォルトで呼び出されることはありません。watch-install は、ご自身で実行した場合に限りログインサービスを登録します。

バックグラウンド動作の詳細

ローカル埋め込みプロバイダーの初回実行時に行われるモデルのダウンロード。 どちらのオフラインプロバイダーも、初回使用時に HuggingFace からモデルを取得し、ディスクにキャッシュします。埋め込みを有効にするまでは何もダウンロードされず、語彙検索のみのインストールでは hub に接続しません。モデルがすでにキャッシュされていない場合、起動時のウォームアップはスキップされます。そのため、初回実行時はダウンロードが最初の検索時まで延期され、MCP のハンドシェイクがダウンロード待ちで停止することはありません（#110）。 パッケージのインストールとモデルのダウンロードが行われるのは、init に「はい」と答えた場合だけです。 jdocmunch-mcp init は、埋め込みプロバイダーが利用可能かどうかを確認します。利用可能なプロバイダーがない場合は、セマンティック検索を有効にするかどうかを一度だけ尋ねます。デフォルトの回答は「いいえ」です。「はい」と答えると、次の2つを実行前に表示してから実行します。

• jdocmunch が動作している Python 環境で python -m pip install "fastembed>=0.8.0" を実行します（インストール後のサイズは約160 MBで、torchではなくonnxruntimeを取得します）。
• huggingface.coから、ONNX形式のモデルファイル all-MiniLM-L6-v2 を1つダウンロードします（87 MB、1回のみ）。

その後、埋め込み処理はお使いのマシン上で実行されます。ドキュメントのテキストが外部に送信されることはありません。--yes を指定しても、この質問に自動で回答することはありません。--yes が承認するのは設定の編集であり、ダウンロードではありません。スクリプトによるインストールでは、--with-embeddings を指定してオプトインします。--dry-run はコマンドとサイズを表示するだけで、何も変更しません。pipが利用できない場合（uv tool や pipx によるインストールではpipがありません）、またはインストールに失敗した場合、init は使用しているインストール方法に応じた手動実行用コマンドを表示し、単語マッチングで処理を続けます。MCP サーバー自体が、許可なく何かをインストールまたはダウンロードすることはありません。

init が質問する理由は次のとおりです。6つのドキュメントセットに関する、ユーザーから寄せられた492件の実際の質問を対象とした公開ベンチマークでは、セマンティック検索（ハイブリッド検索）を使うと、47%の質問で直接の回答が上位5件に入りました。単語マッチングのみの場合は34%でした。手法、データ、およびそれに伴う否定的な結果については、jdoc-rerank-bench をご覧ください。CPUのみの1台のマシンで測定したところ、埋め込み処理によって初回インデックス作成に1,000セクションあたり約7秒が追加されました。doc_list_repos はインデックスごとに has_embeddings を報告するため、単語のみで処理されているものを確認できます。

オフラインプロバイダーとしてのFastEmbed。 pip install jdocmunch-mcp[fastembed] を実行すると、torchではなくonnxruntimeを使って同じ all-MiniLM-L6-v2 モデルが実行されるため、インストールサイズを大幅に小さくできます。両方のオフラインプロバイダーがインストールされている場合はFastEmbedが優先されます。もう一方を選択するには、JDOCMUNCH_EMBEDDING_PROVIDER=sentence-transformers を指定します。共有モデルでは、どちらを使っても同じベクトルストアに書き込まれるため、実行環境を切り替えてもコーパスの再埋め込みは不要です。JDOCMUNCH_FASTEMBED_MODEL でFastEmbedに別のモデルを指定すると、2つのモデルのベクトルは互換性がないため、別のベクトルが保存されます（#126）。

FastEmbedモデルの保存場所と修復方法。 FastEmbedのデフォルトフォルダーは <temp dir>/fastembed_cache で、OSのクリーンアップによって空になることがあります。モデルを読み込めない場合、index_local は embedding_provider_error と警告でその旨を伝え、問題が修復されるまで検索は単語マッチングになります。init はダウンロードせず、ローカルファイルのみを使ってモデルを確認します。モデルが見つからないか破損している場合は修復を提案します。修復にはインストール時と同じ同意が必要です。プロンプトで「はい」と答えるか、--with-embeddings を指定してください。修復ではモデルを（87 MB、1回のみ）一時ディレクトリの外にある ~/.cache/jdocmunch-mcp/fastembed にダウンロードします。モデルが保存された後、サーバーはこのフォルダーからモデルを読み込みます。一時ディレクトリにあるコピーを使用できるインストールでは、そのコピーが引き続き使われ、再ダウンロードされることはありません。JDOCMUNCH_FASTEMBED_CACHE では別のフォルダーを指定できます。FastEmbed独自の FASTEMBED_CACHE_PATH は、どちらの指定よりも優先されます。

OCRを有効にした場合に限り、ローカルのOCRプログラムを使います。 [ocr] エクストラを使い、設定で JDOCMUNCH_OCR=1、さらに呼び出し時に ocr=true（または --ocr）を指定すると、jDocMunchはスキャンされたページごとに短時間の子プロセスとしてTesseractを実行するか、Windowsのデバイス上OCRを呼び出します。いずれもネットワーク接続を開きません。テキストはドキュメントのインデックスディレクトリ（.office_cache/ocr）にキャッシュされます。バックグラウンドで処理が実行されることも、何かがインストールされることもありません。OCRで抽出されたテキストから何がわかるかについては、スキャンされたPDF をご覧ください。 ウォッチャーのバッチごとに子プロセスを起動します。 ウォッチャー（jdocmunch-mcp watch、または jdocmunch-watch ログインサービス）は、変更されたファイルの各バッチを、短時間だけ動作する子プロセス python -m jdocmunch_mcp.watch_batch で再インデックスします。再インデックスではインデックスファイル全体を書き換えますが、そのために使用したメモリは長時間動作するプロセス内ではシステムに返されないため、ウォッチャーのメモリ使用量が上限に近づいていくことがありました （#189）。子プロセスは終了時にメモリを解放します。子プロセスは次のように動作します。

• バッチごとに一度実行され、バッチの処理が終わると終了します。
• 独自のネットワーク接続は開きません。インデックス作成ですでに呼び出されているものだけを呼び出します。たとえば、設定している場合は埋め込みプロバイダーや要約プロバイダーを呼び出します。
• 埋め込みプロバイダーを毎回新たに起動します。ある Windows PC では、1 ファイルのバッチの処理時間はプロセス内で 0.3 秒、子プロセスで 0.55 秒、FastEmbed を有効にした子プロセスでは 1.7 秒でした（モデルは毎回ロードされます）。sentence-transformers は測定しておらず、ロードにはより時間がかかります。
• Windows では、コンソールウィンドウを開きません。

JDOCMUNCH_WATCH_INPROCESS=1 を設定すると、以前のプロセス内での再インデックスに戻ります。

ローカル埋め込みを使用する場合の子プロセス。 sentence-transformers プロバイダーが有効な場合、jDocMunch は埋め込みモデルをサーバー内ではなく、子プロセス（python -m jdocmunch_mcp.embeddings.worker）で実行します。子プロセスは次のように動作します。

• 埋め込みが初めて必要になった時点で起動します。モデルがローカルの HuggingFace キャッシュにすでにある場合は起動時に、そうでない場合は、そのモデルを使う最初の検索またはインデックス作成時に起動します。語彙ベースのみのインストールでは起動しません。
• ネットワーク接続は一切開かず、非公開パイプ経由で親プロセスとだけ通信します。
• サーバーの終了時に終了し、応答しなくなった場合は強制終了されます。
• ログインサービスではなく、どこにも登録されず、何も存続しません。

これは、サーバープロセス内で埋め込み関連スタックをインポートすると Windows ローダーでデッドロックが発生し （#118）、サーバーが動作している間、すべてのツール呼び出しが停止することがあるために導入されています。JDOCMUNCH_EMBED_WORKER=0 を設定すると無効になり、以前のプロセス内インポートに戻ります。

インストールした場合に限り、ログインサービスが起動します。 jdocmunch-mcp watch-install は、ログイン時にドキュメントウォッチャーが起動するよう登録します（systemd ユーザーユニット、launchd エージェント、または jdocmunch-watch という名前のタスクスケジューラタスク）。何かが自動でインストールすることはありません。インストール後は、次のように動作します。

• ディスク上のドキュメントファイルが変更されるたびに、ローカルでインデックス化されたすべてのドキュメントリポジトリを再インデックスします。
• watch-install に渡したフラグを使って、jdocmunch-mcp watch をそのまま実行します。--no-ai-summaries を指定すると要約機能を使わず、--quiet を指定すると変更ごとのログ行を抑制します。
• ドキュメントインデックスディレクトリ内の watch.log と watch.err に書き込みます。
• jdocmunch-mcp watch-uninstall で削除されます。

⚠ watch-install を再実行するとサービス定義が書き換えられるため、手動編集した内容は置き換えられます。現在は置き換えた内容を表示します。アップグレード後も設定を維持するには、フラグを watch-install 自体に渡してください （#120）。

パストラバーサルの防止、シンボリックリンクによる逸脱の保護、シークレットの除外、ファイルサイズ制限、バイナリ検出、エンコーディングの安全性については、脆弱性の報告方法とともに SECURITY.md に記載されています。

---

制限事項

• セクション検索の効果は、小さなファイルでは最も小さくなります。 見出しが1つ、40行のドキュメントでは、セクションを検索するコストとファイルを読むコストはほぼ同じです。
• セマンティック検索には埋め込みプロバイダーが必要です。 プロバイダーがない場合、検索は語彙ベースのみです。識別子や完全一致する表現には適していますが、言い換えられた質問への対応は劣ります。
• Office形式の利用にはオプションの [office] エクストラが必要で、ローカルでのインデックス作成のみサポートされます。スキャン画像のみのPDFにはテキストレイヤーがないため、OCRなしではインデックスに登録されません。レスポンスでは skipped_paths.no_extractable_text に該当ファイル名が記載され、警告が追加され、coverage_complete: false が報告されます。
• OCRはオプションで、デフォルトでは無効になっており、機能も限定的です。 [ocr] エクストラを導入し、マシンにすでにあるエンジンを使用して、両方のキーを設定すると、スキャンされたページを読み取れます（スキャンPDFを参照）。印刷された文章は良好に読み取れます。表やフォームは乱れた結果になる場合があり、装飾文字、ブラックレター、手書き文字は読み取れません。
• 鮮度は明示されますが、保証はされません。 ソースを確認できないセクションは、最新とみなすのではなく unknown として報告されます。
• jDocMunchはコードを解析しません。 シンボル、シグネチャ、コールグラフには jcodemunch-mcp を、表形式のデータには jdatamunch-mcp をご利用ください。

---

ドキュメント

ドキュメント	内容
USER_GUIDE.md	ツールの詳細なリファレンス、ワークフロー、ベストプラクティス
ARCHITECTURE.md	ストレージモデル、解析パイプライン、拡張ポイント
SPEC.md	レスポンスの契約と理由コードの用語
SECURITY.md	セキュリティ制御と脆弱性の報告
TOKEN_SAVINGS.md	節約量の計算方法と報告方法
CONTRIBUTING.md	開発環境のセットアップとCLAの要件
CHANGELOG.md · ROADMAP.md	リリース履歴と今後の予定

---

ライセンスと商用利用

jDocMunch-MCP Dual-Use License（ライセンス全文）のもとで公開されています。非商用利用は無料です。商用利用には有料ライセンスが必要で、jMunch LLCが買い切りで販売しています。

jDocMunchのみ： Builder、$29（開発者1名） · Studio、$99（最大5名） · Platform、$499（組織全体での社内導入）

jMunchスイート全体（コード＋ドキュメント＋データ）： Trio Builder、$99 · Trio Studio、$449 · Trio Platform、$2,499

個人開発者と非商用プロジェクトにはライセンスは不要です。社内チーム全体にjDocMunchを導入する組織にはライセンスが必要です。

1.xの互換性に関する取り組み

1.xのライセンスでは、今後リリースされるすべての1.xバージョンをご利用いただけます。次のような1.xバージョンをリリースすることはありません。

• MCPツールを削除または改名する（非推奨となったツール名には引き続きエイリアスが保持されます）。
• レスポンス形式から Section フィールドを削除する。
• 初回読み込み時に既存のインデックスを自動移行せず、再インデックスを強制する。
• 既存の利用側を壊すような形で、いずれかのツールレスポンスのJSONワイヤ形式を変更する。
• または、これまでデフォルトだった動作で例外を発生させる。

これらの約束に反する変更は、将来のメジャーバージョン（2.x）に限って実施されます。機械的に検証される契約の全文は、tests/test_server.py（ツール名と必須フィールドの不変条件）および、すべてのリリースで実行されるリプレイフィクスチャのゲートによって適用されます。

サポートとプロジェクトの状況

積極的にメンテナンスされています。問題やバグの報告：GitHub Issues。セキュリティに関する報告：SECURITY.mdをご覧ください。商用ライセンスに関するお問い合わせは、jcodemunch.comからご連絡ください。

jcodemunch-mcp（コードシンボル）およびjdatamunch-mcp（表形式データ）とともに、jMunch スイートの一部を構成しています。3つすべてが、オープンな検索インターフェース仕様であるjMRIを実装しています。