ExpertPack MCP

ep-mcp

Model Context Protocol を介したエキスパティーズ・アズ・ア・サービス。

あらゆる ExpertPack を、リアルタイムにクエリ可能なナレッジサービスに変換する MCP サーバーです。MCP 対応のエージェント（Claude Desktop、Cursor、Windsurf、Claude.ai、カスタムホスト）は、標準化されたツールを通じて、出典情報が充実した高品質なドメイン知識を取得できます。

🌐 expertpack.ai · 📦 ExpertPack Framework · 📖 アーキテクチャ

本番環境の v4.1 原子的概念パック（658 チャンク）を対象とした 22 問のベンチマークで、検索ヒット率 97.6%／完全な失敗 0 件を達成。同じパックと評価セットにおける以前の v4.0 ベースラインは 65.1% でした。

特徴

• スキーマ対応ハイブリッド検索：BM25＋ベクトル検索（sqlite-vec）、メタデータによるブースト、MMR による再ランキング、適応型しきい値フィルタリング、長さペナルティ
• requires: の展開（schema v4.1 atomic-conceptual）：上位 K 件のアトムのフロントマターに requires: [B, C] が宣言されている場合、参照先のアトムが requires_expanded=True のフラグ付きで追加の SearchResult として結果に自動追加されます。方向性があり（A→B は B→A を意味しません）、最大 2 ホップまで推移的に展開されます。上限は 3 アトム、累計 3,500 トークンで、max_results のスライス後に追加されるため、上位 K 件が押し出されることはありません。
• インテント対応ルーティング：クエリを自動分類（ENTITY/HOW/WHY/WHEN/GENERAL）し、クエリごとにベクトル検索と BM25 の融合重みを調整します。LLM は不要です。
• クエリ埋め込みキャッシュ：(model, dimension, sha256(query)) をキーとする SQLite ベースのキャッシュです。キャッシュが温まった後のクエリレイテンシは、約 4 秒（Gemini API へのライブアクセス時）から約 1 ミリ秒に低下します。
• 深層グラフトラバーサル：ナレッジグラフのエッジをたどる、オプションのマルチホップ BFS 展開です。ホップごとのスコア減衰とドリフト防止に対応します。
• 予約スロットによるグラフ統合：最終的な上位 K 件のうち、グラフ展開された近傍用に保護スロットを設定できます。関連ファイルが、コア検索結果に埋もれることなく表示されます。
• BM25 フォールバックモード：埋め込みプロバイダーの障害時は、ハードエラーではなく、字句情報のみの検索（網羅率＋密度＋パス＋長さによるスコアリング）にシームレスにフォールバックします。
• クロスエンコーダーリランカー：オプションの 2 段階目の精度向上用リランカーです（デフォルトでは無効。有効時のウォームレイテンシは約 70 ミリ秒）。
• 来歴優先：すべての結果に id、content_hash、verified_at、source_file が含まれます。
• 再構成モード（RFC-003）：オプトインの reconstruct=true / reconstruct: true を指定すると、結果に fragment_id、line_range、original_markdown、スパンレベルの content_hash、excerpt、stale、バイトオフセットが追加されます。これにより、回答の根拠となったソーステキストをエージェントが正確に示せます。
• EP ネイティブのチャンク分割：ファイルは検索の原子的な単位として扱われます（大きすぎるコンテンツのみ ## / ### で分割）。分割されたチャンクでは、元のスパンが content / span_hash として保持され、計算された line_range と heading_path が記録されます（0.7.0+）。
• 見出しパス（0.7.0+）：すべての検索結果に heading_path（例：["Routing", "Setup", "Ports"]）が含まれるため、H3 の検索結果でも親の H2 を保持できます。ep_read(path, section=..., neighbors=true) を使うと、そのセクションと直前・直後の兄弟セクションのみを読み取れます。
• 鮮度（0.7.0+、ExpertPack Core 4.2）：検索結果と ep_read に verified_age_days、age_stale（verified_at がファイルの refresh またはマニフェストの freshness.refresh_cycle より古い場合）、expired、expires_at（揮発性 TTL）が含まれます。stale の意味は従来どおり、インデックスのずれ（インデックス作成後にファイルが変更された状態。再構成モードのみ）です。retrieval.freshness_penalty で任意の順位降下を設定できます（デフォルトの 0.0 は無効）。
• MCP 経由のスキル（0.7.0+、オプトイン）：パックの manifest.yaml に mcp.skills.enabled: true を設定すると、io.modelcontextprotocol/skills 拡張（SEP-2640）が宣言されます。各パックは skill://{slug}/SKILL.md（生成）に 1 つのスキルとして公開され、on_demand ではないすべてのファイルは skill://{slug}/{path} でそのまま提供されます。skills/list / skills/get は、SHA-256 ダイジェスト、サイズ、ttlMs、cacheScope を含むマニフェストを公開します。ホスト側の対応はまだ限られているため、引き続き ep_* ツールが主要な利用経路です。
• フロントマター対応：埋め込み時にはメタデータを除去し、ブースト・展開・フィルタリング用に type、tags、requires などを抽出します。
• 増分インデックス作成：コンテンツハッシュに基づいて古さを検出し、変更されたファイルのみを再埋め込みします。
• マルチパック対応：/packs/{slug}/mcp でパスベースのルーティングを行います。
• グラフ対応検索：_graph.yaml の隣接関係を使った、検索後のオプションの展開に対応します。グラフのエクスポートで提供される場合は、承認済みのオントロジー／エンティティノードも含まれます。
• context_prefix（RFC-004）：サイドカーの状況説明文字列は、インデックス作成時に埋め込みと BM25 のみに前置されます。返却されるテキストおよび再構成されるテキストは、元のアトム本文のままです。
• Tier / ナビゲーションフィルター：retrieval_strategy: navigation、_index.md、source-coverage.md、context.on_demand ファイルは RAG プールから除外されます（ep_read / リソースからは引き続き読み取り可能です）。
• ツール：
  • ep_search — 主要なハイブリッド検索ツール
  • ep_read — パスまたは来歴 ID でアトム全体を読み込みます（利用ループのステップ 2）。
  • ep_list_topics — パックの構造と利用可能なコンテンツタイプを閲覧します。
  • ep_graph_traverse
  • マルチパック stdio 対応：複数のパックが設定されている場合、すべてのツールでルーティング用の pack パラメーターを指定できます。単一パックの設定では pack は省略可能で、唯一設定されているパックがデフォルトになります。
• リソース：
  • ep://{slug}/manifest
  • ep://{slug}/authority
  • ep://{slug}/files
  • ep://{slug}/file/{+path}（フロントマターを含む未加工のコンテンツ）
  • skill://{slug}/SKILL.md、skill://{slug}/{+path}（mcp.skills.enabled: true の場合のみ）
• トランスポート：Streamable HTTP（主要、クラウド対応）、stdio（ローカル開発）
  • stdio のマルチパック対応（0.6.0+）：複数のパックが設定された状態で --transport stdio を使う場合、どのパックに問い合わせるかを指定するため、すべてのツールでオプションの pack パラメーター（スラッグ文字列）を指定できます。単一パックの設定では pack は省略可能で、唯一設定されているパックがデフォルトになります。これにより、MCP ホスト（Cursor、Claude Desktop）はパックごとに 1 つのプロセスを起動する代わりに、単一の stdio プロセスで複数のパックを利用できます。
• HTTP エンドポイント：GET /search（MCP 以外の HTTP クライアント向け）
• ゴールデン検索評価（0.7.0+）：tests/eval/ — YAML クエリセット（最良の結果から順に並ぶ expected、must_not、category）を、パックおよびカテゴリごとに recall@1/3/5、MRR、must_not 違反数で評価します。デフォルトの実行ではスキップされます。EP_EVAL_TODAY=2026-10-20 および任意の EP_EVAL_MIN="recall@5=0.9,mrr=0.7" を指定して pytest tests/eval -m golden --golden <dir> --packs-root <dir> を実行するか、python tests/eval/golden_eval.py --golden <dir> --today 2026-10-20 を実行してください。
• 認証：API キー（フェーズ 1）。OAuth 2.1 に対応する設計です（フェーズ 2）。

クイックスタート

インストール

git clone https://github.com/brianhearn/ep-mcp.git
cd ep-mcp
pip install -e .[dev]

設定

最低限、config.yaml を作成します。

server:
  host: "127.0.0.1"
  port: 8000
  log_level: "info"
  # Required for public Host headers (SDK v2 DNS-rebinding protection).
  # See DEPLOYMENT.md — omit and Streamable HTTP returns 421.
  mcp_allowed_hosts:
    - "localhost"
    - "localhost:*"
    - "127.0.0.1"
    - "127.0.0.1:*"

packs:
  - slug: "my-pack"
    path: "/path/to/your/expertpack"
    api_keys:
      - "your-secret-key-here"

embedding:
  provider: "gemini"           # "gemini" (default) or "azure-openai"
  model: "gemini-embedding-001"

設定の全リファレンス（埋め込みプロバイダー、検索チューニング（mmr_lambda、min_score、default_max_results、グラフ展開、再ランキング、requires: の展開など）、本番環境での systemd 設定、デプロイ時の注意事項）については、DEPLOYMENT.md を参照してください。

実行

ep-mcp serve --config config.yaml

サーバーは起動時に SQLite インデックス（FTS5 + sqlite-vec）を構築または更新します。0.5.0 では既存のインデックスの再構築が必要です（index_features=context_prefix_v1+nav_filter_v1）。起動時に自動で再構築されます。または、先に <pack>/.ep-mcp/ を削除してください。

GET /search HTTP エンドポイントは次の場所で利用できます。

GET /search?q=<query>&pack=<slug>&n=10

元の Markdown の範囲と検証用の出典ブロックを含めるには、&reconstruct=true を追加します。

ヘッダー Authorization: Bearer <key> を指定してください。

環境変数

設定した埋め込みプロバイダーのキーのみが必要です。

変数	必須	説明
GEMINI_API_KEY	embedding.provider: gemini の場合	Gemini 埋め込み API キー
AZURE_OPENAI_ENDPOINT	embedding.provider: azure-openai の場合	Azure OpenAI リソースのエンドポイント
AZURE_OPENAI_API_KEY	embedding.provider: azure-openai の場合	Azure OpenAI API キー
EP_MCP_KEY_{SLUG}	任意	パックごとの API キーの上書き（大文字のスラッグ、ハイフンはアンダースコアに置換）
EP_MCP_REMOTE_HOST	任意	scripts/deploy.sh のデプロイ先
EP_MCP_REMOTE_SRC	任意	deploy.sh のリモートソースパス
EP_MCP_REMOTE_SITE_PKG	任意	deploy.sh のリモート site-packages パス

技術スタック

• 言語：Python 3.12+
• MCP フレームワーク：公式 mcp SDK v2（MCPServer、仕様 2026-07-28、2025 クライアントとのデュアルエラ対応）
• ストレージ：SQLite（FTS5 + sqlite-vec）
• 埋め込み：Gemini（デフォルト）、設定可能な Azure OpenAI / OpenAI プロバイダー
• Web：Starlette + Uvicorn（Streamable HTTP 用）
• CLI：Click

依存関係の正確な一覧については、pyproject.toml を参照してください。

プロジェクト構成

モジュールの詳細な内訳、検索パイプライン、インデックス作成戦略、設計上の決定事項については、ARCHITECTURE.md を参照してください。

関連リンク

• expertpack.ai — フレームワークのウェブサイト、コミュニティパック、ドキュメント
• ExpertPack — スキーマフレームワーク、検証ツール、Obsidian 互換性、コミュニティパック
• ExpertPacks — 公開済みナレッジパック（非公開）
• EasyTerritory MCP（将来） — このリポジトリと ezt-designer パックを基盤として構築されるドメイン固有レイヤー

ライセンス

Apache 2.0 © 2026 Brian Hearn

作者

Brian Hearn — 3 日間（2026 年 4 月 10～11 日）で構築。