compendio-mcp

プロジェクトのドキュメントを、可能な限り少ないトークン数であらゆるエージェントに提供します。
MCP サーバーとして公開されるローカル RAG 検索レイヤーです。エージェントは grep やファイル全体の読み込みをやめ、該当する段落に直接たどり着けます。

できること • 要件 • クイックスタート • 設定 • MCP ツール • CLI • 仕組み • 増分同期 • 多言語対応 • ドキュメント全文

---

課題

エージェントはプロジェクトのドキュメントを把握していません。そのため、できることをします。grep で検索し、ひとつの段落に答えがある質問に答えるため、400 行のファイルを cat で読み込みます。ファイルを 3 つも開けば、コンテキストウィンドウはノイズでいっぱいになり、答えは依然として推測のままです。

docs/ フォルダー全体を添付しても解決しません。無駄が早い段階に移るだけです。キーワード検索でも同様です。ドキュメントで使われている言葉とまったく同じ言葉で質問を書く人はいません。

_{同じ質問、同じモデルで、どちらの回答も正解です。違いは、そこにたどり着くまでのコストです。
ツール呼び出し 6 回 • 29 秒 • 32,301 トークン  →  ツール呼び出し 2 回 • 12 秒 • 17,684 トークン。
数値は、81 件のドキュメントからなるコーパスを対象に、OpenCode 独自の経過時間ラベルとコストのツールチップから読み取ったものです。}

## Compendio の機能

Compendio は Markdown ドキュメントをインデックス化し、AI エージェントが必要な情報だけを正確に見つけて読み取るための 3 つのツールを提供します。

• 🔍 grep ではなくハイブリッド検索 — キーワード検索で正確な用語を見つけ、セマンティック検索で言い換えを見つけます。Compendio は両方を実行し、結果を統合します。
• ✂️ トークン消費を抑える設計 — ドキュメントごとに約 10 トークンで概要を把握し、少数の断片を検索して、単一のセクションを読み取ります。コーパス全体を読み込むことはありません。
• 🔒 完全にローカル — SQLite ファイル 1 つで動作し、CPU で埋め込みを処理します。クエリ時にネットワーク通信は一切ありません。API キーも Docker もサービスも不要で、データがマシンの外に出ることはありません。
• ♻️ 常に最新 — サーバーを起動しておけば、ドキュメントの編集を自動で反映します。監視プロセスも手動での再構築も不要です。
• 🗣️ 多言語対応 — あらゆる言語のドキュメントをインデックス化できます。埋め込みモデルは多言語対応で、検索では発音区別符号を区別しません。多言語対応をご覧ください。
• 🧩 設定不要 — .md ファイルを含むあらゆるフォルダーで動作します。必須の frontmatter も設定ファイルもありません。チームですでに適用する分類体系がある場合は、任意でドキュメントの規約を利用できます。

要件

• Node.js ≥ 22.12。
• ほかに必要なものはありません。

クイックスタート

1. インストールします。

npm install -g compendio-mcp

既存のインストールを更新するには：

compendio update

2. クライアントに MCP サーバーとして登録します。

compendio install-mcp <agent>

対応エージェント：claude、claude-desktop、cursor、vscode、opencode、codex、zed。

手動でインストールする場合や、このコマンドに対応していないエージェント（Windsurf、Cline、Gemini CLI）を使う場合は、手動インストールをご覧ください。

3. プロジェクトのルートからインデックスを一度作成します。

compendio index

これで完了です。設定ファイルがなくても、Compendio は Markdown ファイルを含む最上位フォルダーを自動検出するため、docs/ を既定の隠しフォルダーとして用意する必要はありません。.compendio/ を .gitignore に追加してください。

この手順が必要な理由。 サーバーは起動時にもインデックスを作成するため、厳密にはこの手順を省略できます。ただし、初回実行時には埋め込みモデル（数十 MB）がダウンロードされ、キャッシュされるため、実行した人はその完了を待つことになります。ここで実行すれば、プログレスバーを確認しながらターミナルで処理でき、エージェントが初めてツールを呼び出すときに待たずに済みます。それ以降はすべてオフラインで動作し、インデックスは自動的に最新の状態に保たれます（後述）。

Windows に関する注意。 一部の MCP クライアントでは、compendio.cmd のシムを直接起動できません。ENOENT でサーバーの起動に失敗する場合は、"command": "npx" と "args": ["compendio-mcp", "serve"] を使用してください。

設定

完全に任意です。Compendio は設定ファイルがなくても動作します。上書きが必要な項目だけを設定する場合に限り、プロジェクトのルートに compendio.config.json を作成してください。

{
  "docsDir": ["docs"],
  "exclude": ["INDEX.md"],
  "db": ".compendio/compendio.db",
  "embeddings": { "provider": "local", "model": "Xenova/multilingual-e5-small" },
  "chunk": { "minTokens": 100, "maxTokens": 480 },
  "search": { "k": 5 },
  "sync": { "throttleMs": 30000 },
  "convention": {
    "mode": "loose",
    "excludedStatuses": [],
    "frontmatterFields": { "type": "type", "module": "module", "status": "status" }
  }
}

キー	用途
docsDir	明示的に指定するドキュメントのルートを1つ以上、プロジェクトルートからの相対パスで指定します。常に配列で指定し、単一の文字列形式はありません。省略するか [] を設定すると、検出モードが使用されます
exclude	インデックス作成時に除外する項目です。完全一致するパス、任意の場所で一致するファイル名、またはディレクトリのプレフィックスを指定できます（例："adr/superseded" はその配下をすべて除外します）
db	SQLite インデックスファイルの保存先です
search.k	各検索で返すフラグメントのデフォルト数です
chunk	フラグメントサイズの範囲をトークン数で指定します
sync.throttleMs	自動同期パス間の最小間隔をミリ秒単位で指定します（30000 = 30 秒）。これはタイマーではなく下限値です。serve の自動トリガーのみを制御し、手動で実行する compendio sync は制御しません。増分同期を参照してください
convention	任意のドキュメント分類です。以下を参照してください

convention ブロックの一部だけを宣言した場合、デフォルトはフィールドごとにマージされ、指定していない他の項目が消去されることはありません。frontmatterFields は type／module／status を標準以外のフロントマターキーに対応付けます（例：{ "status": "estado" } を設定すると、スペイン語のドキュメントの estado: フィールドが status として読み込まれます）。

すべての数値キー（search.k、chunk.minTokens、chunk.maxTokens、sync.throttleMs）は、0 より大きい有限数の場合にのみ有効になります。さらに、search.k は整数である必要があります。引用符で囲まれた数値（"480" など）を含め、それ以外の値は、キーを省略した場合と同様にデフォルト値にフォールバックし、その旨が報告されます。各 CLI コマンドでは標準エラー出力に、MCP クライアント向けの docs_overview ではレスポンスに表示されます。embeddings、chunk、または convention.frontmatterFields 配下の認識されないキー（maxtokens などのタイプミス）も同様に報告されます。問題のない設定では何も報告されません。

複数のドキュメントルート

複数のルートを宣言すると、adr/、rfcs/、仕様ディレクトリなど、複数のフォルダーを1つの検索可能なコーパスとしてインデックス化できます。

{ "docsDir": ["docs", "openspec"], "exclude": ["INDEX.md", "openspec/changes/archive"] }

すべてのドキュメントの path には、ルートのエイリアス（ディレクトリ自体の名前）がプレフィックスとして付加されるため、docs/x.md と openspec/specs/y.md はどちらも、実際のプロジェクト相対パスとして表示されます。これは、明示的なルートが1つだけの場合や、ルートが検出された場合も同様です。たとえば specs/y.md ではなく、openspec/specs/y.md となります。search_docs、docs_overview、read_doc、および生成される INDEX.md はすべて、このプレフィックス付きの形式を使用します。返された path をそのまま read_doc に渡せば、常に該当するドキュメントが解決されます。

宣言されたルートは重複できません。同じディレクトリに解決される2つのルート、一方がもう一方の配下にあるルート（宣言順は問いません）、または同じディレクトリ名（したがって同じエイリアス）を持つ2つのルートは、インデックス化が始まる前にすべて拒否されます。宣言されたルートを読み取れない場合（入力ミスや、一部のチェックアウトにしか存在しないフォルダーなど）は、そのことが報告されてスキップされ、残りのルートで処理が続行されます。宣言されたすべてのルートで失敗した場合にのみ、エラーが発生します。docsDir からルートを削除すると、ファイル自体を削除した場合と同様に、次回の同期処理でそのルートのドキュメントが削除されます。

検出モードでは、Compendio は index、sync、serve の各同期処理のたびにトップレベルのフォルダーを再スキャンし、その配下のどこかに .md ファイルがあるフォルダーを選択します。シンボリックリンクのコンテンツや、.git、.compendio、node_modules、dist、build、coverage などの生成済みまたは内部用のフォルダーはスキップし、プロジェクトのルートに INDEX.md を書き込みます。検出処理では、安全性を優先して、トップレベルの設定 JSON が不正な場合、候補ツリーを読み取れない場合、探索または読み取りで失敗した場合、あるいは以前にインデックス化された検出ルートが同期前に存在しなくなったり、シンボリックリンクまたはジャンクションになったりした場合は、インデックスを変更する前に処理を中止します。以前にインデックス化されたルートが引き続き読み取り可能なディレクトリであれば、最後の Markdown ファイルが削除された後もそのルートを探索します。そのため、正当な削除は通常どおり反映されます。シンボリックリンクのチェックでは、スキャン時と探索時に lstat／realpath を使用しますが、カーネルレベルのサンドボックスではありません。チェックと読み取りの間に発生するファイルシステム上の競合は対象外です。--dir <path>（以下を参照）は明示モードです。宣言済みまたは検出済みのルート一式をそのディレクトリ1つに置き換え、その中に INDEX.md を書き込みます。

お使いの SDD フレームワークと連携

仕様駆動開発フレームワークでは、計画成果物を Markdown で管理します。Compendio は Markdown をインデックスするため、まさに最適です。フレームワークが書き込むフォルダーを docsDir に指定してください。

フレームワーク	設定	インデックス対象
Spec Kit	{ "docsDir": ["specs", ".specify"] }	specs/NNN-feature/ 内の機能仕様、計画、タスク、および .specify/memory/constitution.md の憲章
OpenSpec	{ "docsDir": ["openspec"] }	openspec/project.md、機能仕様、進行中の変更
Kiro	{ "docsDir": [".kiro"] }	.kiro/specs/ 内の機能ごとの requirements.md／design.md／tasks.md、および .kiro/steering/
BMAD	{ "docsDir": ["docs"] }	PRD、アーキテクチャ、分割されたエピックとストーリー
フレームワークと独自ドキュメント	{ "docsDir": ["docs", "openspec"] }	両方を、検索可能な 1 つのコーパスとして

.specify/ や .kiro/ などの隠しディレクトリは、宣言したルートとしても、探索モードでも通常どおりインデックスされます。スキップされるのはルート自体ではなく、ルート内にあるドットで始まる エントリー です。そのため、設定ファイルがなくても、Spec Kit または Kiro のプロジェクトはすでにインデックスされます。

設定をコピーする前に、知っておくとよいことが 3 つあります。

• ルートのエイリアスは、指定したパスではなくディレクトリ名です。 .kiro/specs のエイリアスは specs なので、そのドキュメントは specs/auth/design.md として返されます。つまり、トップレベルの specs/ ルートと衝突するため、Spec Kit の設定と組み合わせることはできません。表のように、代わりに .kiro を指定してください。
• BMAD の出力フォルダーは設定可能です。 デフォルトは docs です。BMAD v6 は独自の設定から output_folder を読み取るため、ご自身の設定値を指定してください。
• テンプレートはノイズになります。 .specify/templates/ にはプロジェクトの知識ではなく、プレースホルダーのひな形が含まれます。検索結果に含めたくない場合は、"exclude": [".specify/templates", ".specify/scripts"] を追加してください。

ドキュメント規約（任意）

convention.mode で選択する 2 つのモードがあります。

• loose（デフォルト、設定不要） — メタデータがないことを理由にファイルを拒否することはありません。タイトルは最初の H1 から取得し（なければ人が読みやすいファイル名を使用）、モジュールはフォルダーから推定します。type／status はフロントマターにあれば読み取り、なければ未設定のままにします。
• strict（オプトイン） — リンターとして動作します。すべてのドキュメントに H1 と、空ではない type／module／status が必要で、プロジェクトが宣言したリストに照らして検証されます。条件を満たさないファイルはスキップされて報告されますが、実行が中断されることはありません。

{
  "convention": {
    "mode": "strict",
    "types": ["functional", "adr", "api", "qa", "guide"],
    "statuses": ["draft", "current", "deprecated"],
    "excludedStatuses": ["draft", "deprecated"]
  }
}

excludedStatuses はライフサイクル状態に基づいてドキュメントを検索対象から除外します。下書きや非推奨のページが検索結果に紛れ込まなくなります。このリポジトリのドキュメントが従う規約の詳細については、docs/documentation-convention.md を参照してください。

MCP ツール

段階的な情報開示を前提に設計されています。まず概要を手軽に把握し、次に手軽に検索し、必要なものだけを読み取ります。

1. docs_overview() — コーパスのマップです。種類とモジュールごとの件数に加え、ドキュメントごとに 1 行で表示します。ドキュメント 1 件あたりおよそ 10 トークンです。

2. search_docs({ query, type?, module?, tags?, k?, include_excluded? }) — 上位 k 件の断片を返します（デフォルトは 5 件、1 ドキュメントあたり最大 2 件）。各断片にはパス、セクション、抜粋、スコアが含まれます。type は固定リストではなく、プロジェクトが定義する任意の文字列です。

3. read_doc({ path, section? }) — 1 つのセクション、またはドキュメント全体を読み取ります。セクションを含む大きなドキュメント（推定トークン数が約 6,000 を超える場合）では、本文の代わりに H2／H3 見出しの簡潔なアウトラインを返すため、エージェントは必要なセクションだけを読み取れます。存在しないパスを指定すると、エラーではなく類似度の高いパスを 3 件返すため、エージェントは手探りで再試行せずに自ら修正できます。

CLI

コマンド	説明
compendio serve	stdio 経由で MCP サーバーを起動します
compendio install-mcp <agent>	指定したエージェントの設定に compendio-mcp を登録します
compendio update	npm から compendio-mcp を最新バージョンに更新します
compendio index	インデックスを全面的に再構築します
compendio sync	ターミナルから増分同期を 1 回実行します。内容が変更されたドキュメントのみを同期し、進行状況をリアルタイムで表示します。増分同期を参照してください
compendio search "..."	フィルター（--type、--module、--tags、-k、--all）を使ったハイブリッド検索
compendio overview	インデックス化されたコーパスのマップ
compendio index-md	統合された INDEX.md を生成または更新します。検出モードではプロジェクトルートの INDEX.md、明示的に指定した最初のルートまたは --dir で指定したルートではその中の INDEX.md を生成し、ドキュメントごとに 1 行を記載します
compendio eval	ゴールデンセットを基に検索品質を測定します

グローバルオプション -C, --root <dir>：プロジェクトルートです。index、sync、search に --lexical を追加すると、埋め込みを完全にスキップします。index／index-md の --dir <path> は、設定済みの docsDir をそのディレクトリ 1 つで置き換えます。追加するものではなく、生成されるインデックスのパス形式は引き続きプレフィックス付き（<dirname>/x.md）です。sync には --dir がありません。増分同期中にこの方法でルートを除外すると、単にスキップするのではなく、そのドキュメントが削除されてしまいます（compendio sync --help を参照してください）。

仕組み

docs/**/*.md
     │
     ├─▶ split into fragments at heading boundaries, then bounded to maxTokens
     │
     ├─▶ index each fragment twice ─┬─ full-text (keywords)
     │                              └─ embeddings (meaning)
     │
     └─▶ one file: .compendio/compendio.db

クエリ時には両方のインデックスを個別に検索し、**相互ランク融合（Reciprocal Rank Fusion）**によって順位を統合します。これは重みを手探りで調整する必要のない、順位ベースの統合方式です。エージェントには、関連性の高い最小限のフラグメントが返されます。

Compendio は RAG における検索を担います。LLM を呼び出すことも、何かを生成することもありません。適切な段落を見つけたら、その役目を終えます。

埋め込みモデルが利用できない場合でも、Compendio はクラッシュしません。キーワードのみの検索に切り替え、そのことを応答で伝えます。

インクリメンタル同期

作業中にドキュメントが変更されても、Compendio は自動で、または要求に応じて最新の状態を保ちます。インデックスが更新されるきっかけは4つあります。

トリガー	動作
サーバー起動時（compendio serve）	トランスポートの接続前に、インクリメンタル同期を1回実行します。最初のツール呼び出しは同期が終わるまで待機するため、初期化されていないインデックスを使って応答することはありません
MCP ツール呼び出し時（search_docs、docs_overview、read_doc）	前回の同期から 30 s（sync.throttleMs。デフォルトは 30000）が経過している場合に限り、インクリメンタル同期を1回実行します。経過していない場合、呼び出しは現在のインデックスを使って処理されます
compendio sync	ターミナルから手動で実行し、進捗をリアルタイムに表示しながらインクリメンタル同期を1回実行します。sync.throttleMs の制限は適用されません。実行間隔にかかわらず、呼び出すたびに新しい同期処理が実行されます。ドキュメントを一度に大量に追加した場合は、このコマンドの実行を推奨します。
compendio index	ゼロから全面的に再構築します。インデックスを削除して再作成します

タイマーではありません。 バックグラウンドの定期実行も、ファイルウォッチャーもありません。同期はエージェントによるツール呼び出し、または compendio sync の実行によって行われます。また、スロットルは2つの自動トリガー間の最小間隔であり、スケジュールではありません。誰からも問い合わせられていないサーバーは同期せず、1秒間に10回呼び出されても同期処理は最大1回しか実行されません。並行する呼び出しは2回目の同期処理を開始せず、すでに実行中の処理に合流します。

インクリメンタル同期では、各回の処理でコンテンツハッシュをインデックス済みの内容と比較するため、新規・変更・削除されたドキュメントだけが処理され、変更のないコーパスにはコストがかかりません。serve で同期処理が失敗した場合は標準エラー出力に記録されますが、ツールは現在のインデックスを使って応答します。このようなフォールバックは compendio sync にはないため、同じ失敗が発生すると、プロセスはゼロ以外の終了コードで終了します。

全面的な再構築が必要な場合。 インデックスを再作成するコマンドは compendio index だけです。データベース全体を削除して再作成するため、これが唯一の正式な方法です。大規模な再構成の後、インデックスが実際の状態とずれている疑いがある場合、あるいは意外と見落とされがちなケースとして、chunk.minTokens／chunk.maxTokens を変更した後に実行してください。自動実行でも compendio sync による手動実行でも、インクリメンタル同期ではドキュメントのフィンガープリントにコンテンツハッシュだけを使います。そのため、編集していないドキュメントは、設定が変更されても古い分割境界のままです。変更されていないファイルに新しいチャンク設定を適用できるのは全面的な再インデックス（compendio index）だけです。必要になる可能性が高い場面で確認できるよう、同じ注意事項が compendio sync --help にも記載されています。

多言語対応

チームで使っている言語でドキュメントを書いてください。Compendio は言語を問いません。

• ツールの契約は英語ですが、コーパスは英語である必要はありません。 ツールのパラメーター（path、type、module、tags、section）、レスポンスのフィールド、ツールの説明は英語なので、どのエージェントでも問題なく読み取れます。ドキュメントの記述言語とは無関係です。インデックス作成前にフロントマターのキーは取り除かれ、FTS5 トークナイザーには言語固有のステマーがありません。
• 英語以外のフロントマターキーも対応付けられます。 ドキュメントで status: の代わりに estado: を使う場合は、convention.frontmatterFields で対応付けられます。
• アクセントは適切に処理されます。 検索は発音区別符号を区別しないため、validación と validacion は一致します。アクセントを区別する検索では、結果が気付かないうちに失われます。
• 埋め込みモデルは多言語対応（Xenova/multilingual-e5-small）なので、単一言語のコーパスと複数言語が混在するコーパスのどちらも、同じようにインデックスを作成して検索できます。

ejemplos/ に同梱されている参照コーパスと評価セットは、意図的にスペイン語で作成されています。英語のコードベースとツールの契約でも、英語以外のドキュメントを損失なく検索できることを示すためです。

grep と比べて、セマンティクスによってどれだけ向上しますか？

サンプルコーパス（ejemplos/：11 個のドキュメント、29 個のチャンク、設定ファイルなし。ゼロ設定の経路そのもの）と、実際の質問 22 件を集めたゴールドセットを使い、compendio eval で測定しました。

モード	recall@5	MRR	失敗数
ハイブリッド	1.00	0.943	0
キーワードのみ	0.95	0.856	1

• 質問にコーパス内の用語が使われていれば、キーワード検索だけでも高い性能を発揮します。
• 言い換えや同義語を使う質問では差が開きます。«¿Qué endpoint hay que llamar para crear un lead?» は、埋め込みがないと上位 5 件から漏れますが、セマンティック検索を組み合わせると見つかります。一致するドキュメントとの単語の重複がゼロの質問は、セマンティクスだけで解決できます。
• 速度：モデルがウォームアップ済みなら、ハイブリッド検索の応答時間は 5～20 ms です。

compendio eval を実行すれば、いつでもこの表を再現できます。また、推測に頼らずにチャンク分割や k を調整するためのツールでもあります。

アーキテクチャ

ヘキサゴナルアーキテクチャです。コアは SQLite、transformers.js、ファイルシステムについて何も知りません。

src/
├── domain/            # pure, no dependencies: model, chunking, ranking, convention policy
├── application/       # use cases
├── infrastructure/    # adapters: SQLite, markdown parsing, filesystem, embeddings
├── composition.ts     # composition root — start here to see the whole app
├── cli.ts             # input adapter: commander
└── server.ts          # input adapter: MCP server (stdio)

すべての外部依存関係は、src/domain/ports.ts のポートの背後にあります。ベクトルストアや埋め込みプロバイダーの切り替えは、アダプター 1 つのローカルな変更で済み、書き直す必要はありません。

開発

npm install
npm run build       # compiles to dist/
npm test            # vitest: domain, adapters and integration
npm run typecheck   # tsc --noEmit
npm run dev -- ...  # CLI without compiling (tsx)

統合テストでは、実際の ejemplos/ コーパスに対して、決定論的な埋め込みプロバイダーを使用します（ダウンロードは不要です）。

パッケージをインストールせずに、同梱のサンプルコーパスを使って CLI を試せます。

node dist/cli.js --root ejemplos index
node dist/cli.js --root ejemplos search "¿cuándo se considera duplicado un lead?"

このリポジトリには ejemplos/ コーパスを提供する .mcp.json が含まれているため、設定不要で Claude Code からツールを試せます。

ライセンス

MIT © Raúl García Barciela