MCP APIリファレンス

Maguyva の 11 個の MCP ツールとそのパラメーター、用途を確認できます。利用できる引数は、接続中のクライアントの tools/list 応答で確認してください。

ツールは 4 のカテゴリに分かれています:

• コア検索ツール - コードベース全体を対象とした高度な検索機能
• 構造・グラフツール - ASTクエリ、シンボルルックアップ、依存関係解析
• コード解析ツール - 詳細なコード解析と関係性のマッピング
• システム・ユーティリティツール - リポジトリのコンテキスト、ツールの使い方、フィードバック

リポジトリを受け付けるツールでは、次のリポジトリ識別子形式を使います: "owner/repo:branch"。ブランチを指定しない場合は main になります。

MCP クライアントがリクエストの既定値を提供する場合、またはキーがアクセスできるリポジトリが一つだけの場合は repository を省略し、それ以外では明示的に渡します。リポジトリがどのように解決されるかを確認するには repository_context(action="info", repository="owner/repo") を使用します。

リポジトリを指定するときは、次の形式を使ってください:

• ブランチ指定あり: "owner/repo:branch" - 例: "owner/repository:develop"
• デフォルトブランチ: "owner/repo" - ブランチが指定されない場合はmainブランチを使用 "owner/repository"
• リクエストまたは唯一のリポジトリの既定値: MCP クライアントがリクエストの既定値を提供する場合、またはキーがアクセスできるリポジトリが一つだけの場合はリポジトリを省略し、それ以外では明示的に渡します

プロンプト例:

特定のリポジトリについて質問する:   "owner/my-repoで認証ミドルウェアを検索して"
アクセス可能なリポジトリを一覧表示:  "この Maguyva キーがアクセスできるリポジトリは?"
1回のクエリだけオーバーライドする:  "owner/other-repo:developで認証パターンを検索して"

対応する検索モードで language_filter を使います。text_pattern_search では search_scope="content" を選択してください。get_task_context では、シードや関連コンテキストを指定せずに scope="semantic" を使ってください。

• language_filter="python" - Pythonファイルのみにフィルタ
• language_filter="typescript" - TypeScriptファイルのみにフィルタ
• 大文字小文字を区別: 言語名は小文字で指定
• デフォルト: 空文字列(フィルタなし)。すべての言語の結果を返す
• 対応カバレッジ: 言語フィルタは、対応する285+件の言語およびテキストベースの技術全体で機能する。 完全な一覧は互換性をご覧ください。

"Pythonファイルだけで認証ミドルウェアを探して"
"TypeScriptでデータベース接続を検索して"

2026年10月21日にソースから生成されたAPIリファレンス。

1. 明示的なオーバーライドを意図的に使う: MCP クライアントがリクエストの既定値を提供する場合、またはキーがアクセスできるリポジトリが一つだけの場合はリポジトリを省略し、それ以外では明示的に渡してください。
2. 適切な検索モードを選ぶ: ほとんどの場合は mode="auto" を指定した intelligent_search を使ってください。必要なものが明確な場合はモードを指定します。
3. 言語フィルタを活用する: language_filter を使って結果を絞り込み、パフォーマンスを向上させてください。
4. GraphRAG ブースティング: GraphRAG による重要度ブーストは、ランキングをエージェントにとって安全に保つため、セマンティック検索ではデフォルトで無効です(boost_by_importance=false)。アーキテクチャ全体を俯瞰する用途では boost_by_importance=true を渡すと、中心性を考慮した再ランキングを有効にできます。
5. リポジトリ照合は大文字小文字を区別しません(あいまい照合ではありません): repository_context はリポジトリ名を大文字小文字を区別せずに照合します。タイプミスを訂正するわけではありません。提供される識別子が要求されたものと異なる場合、metadata.resolution_reason は "defaulted"(ブランチが指定されなかった)または "fallback"(要求されたブランチまたはリポジトリが利用できない)を報告します。要求どおりに一致した場合、このフィールドは省略されます。
6. ツールを組み合わせる: 複数の API メソッドを組み合わせて、包括的な分析を行ってください。
7. 大量の結果を扱う: limit や、ツール固有のページング制御(例えば get_file の line_start/line_end)を使ってください。
8. ツールガイダンスには ask_maguyva を使う: ツール選択の助言や例を確認するには、ask_maguyva に operation="guidance" と query="tool_selection" を指定します。計算や文字列変換にはローカルのツールを使ってください。
9. 編集の前後で影響を確認する: 共有シンボルを編集する前に、dependency_search を analysis_type="impact" で呼び出して(または PR／差分の影響を見るには changed_paths を渡して)、その影響範囲を確認してください。編集後は verify_after_edit=true を targets や changed_paths とともに設定すると、同じシンボルをコンパクトに再チェックできます。 確認するのはインデックス済みグラフです。未コミットのローカル変更は読み取らず、ローカルテストの代わりにもなりません。新しいリビジョンの根拠として結果を扱う前に、indexed_commit_sha とインデックスの鮮度を確認してください。

ツールの応答には、共通のステータスフィールドとツール固有のペイロードフィールドが最上位に含まれます。検索は results を返し、get_file は content を返します。共通フィールドには次のものがあります:

• status: 文字列 — "success" または "error"。低下した一致や鮮度のシグナルは専用のフィールドに入ります。metadata 配下の metadata.resolution_reason と、repository_context の info アクションのトップレベルにある index_freshness.status です。
• timing_ms: ツールの実行にかかった時間(ミリ秒)
• applied_filters: 操作に対して記録された、実際に適用されたリクエストパラメーター
• error: status が "error" の場合のエラーメッセージ文字列。復旧の案内を含む場合があります。
• metadata: 操作に関する追加情報(ルーティング、キャッシュ、パラメータ調整)
• pagination: カーソルでページ分割されるコレクションの応答に含まれ、has_more と next_cursor を持ちます。順位付き検索の結果枠は上位 K 件に限定されており、全件をページ分割したコレクションではありません。

ツールのペイロードを処理する前に status フィールドを確認してください。値は "success" か "error" です。ツールのペイロードが生成される前に発生しうる MCP/JSON-RPC のトランスポートエラーやリクエスト検証エラーにも対応してください。低下した一致や鮮度のシグナルについては、専用のフィールドを参照します。metadata 配下の metadata.resolution_reason、または repository_context の info アクションのトップレベルにある index_freshness.status(known/partial/unknown/unavailable)です。

1. MCPクライアントを設定: MCPクライアントをMaguyvaサーバーのエンドポイントに向ける
2. リポジトリアクセスを確認: repository_context の list または info を使い、API キーで利用できるリポジトリを確認します
3. 検索を開始: intelligent_searchから始め、必要に応じて専用ツールを試す
4. ツールを組み合わせる: 複数のツールを組み合わせて、包括的なコード解析を行う

詳しい導入手順はインストールガイドをご覧ください。