本文へスキップ

MCP APIリファレンス

顧客向けのMaguyva MCPツール全11個に関する完全なリファレンス。各ツールには、パラメータ、使い方のガイダンス、最適な利用場面の推奨事項が含まれる。

API概要#

Maguyva MCP APIは現在、4個の主要カテゴリーにわたり、11個の顧客向けツールを提供している:

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

すべてのツールは一貫したリポジトリ識別子形式を使用します:"owner/repo:branch"。ブランチを指定しない場合はmainがデフォルトになります。

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

リポジトリパラメータ形式#

すべてのMCPツールは次のリポジトリ識別子形式を使用します:

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

プロンプト例:

特定のリポジトリについて質問する:   "Search owner/my-repo for authentication middleware"
アクセス可能なリポジトリを一覧表示：  "この Maguyva キーがアクセスできるリポジトリは？"
1回のクエリだけオーバーライドする:  "Search owner/other-repo:develop for auth patterns"

言語フィルタリング#

すべての検索ツールはプログラミング言語による結果の絞り込みに対応しています:

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

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

コア検索ツール#

intelligent_search安定版

コードベースについての質問は、まずここから始めてください。自然言語のクエリ（例：「認証はどう動く？」「課金処理はどこ？」）を渡すと、インデックス済みリポジトリ全体を対象に、セマンティック、シンボル、構造、依存関係の各検索へ自動で振り分けます。ファイルを一つずつ走査せず、リポジトリ全体を一度に検索するため、調査や計画では Explore エージェントや Grep/Glob より優先してください。

パラメータ:

query必須
型
str
説明
検索クエリ
repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
mode任意
型
Literal[auto, hybrid, semantic, text, structural, ast, graph]
デフォルト
auto
説明
検索モード
limit任意
型
int
デフォルト
10
説明
このランク付けされた top-K ウィンドウでの最大結果件数
language_filter任意
型
str
説明
言語フィルタ
path_filter任意
型
str
説明
ファイルパスのプレフィックスで絞り込む
boost_by_importance任意
型
bool
デフォルト
説明
オプトイン: シンボルごとのグラフメトリクス（is_articulation_point、bridge_count、k_core、centrality など）を用いて中心性で再ランク付けします。エージェントにとって安全なランク付けのためデフォルトは無効です（グローバルなハブが実装のヒットを埋もれさせることがあります）。アーキテクチャの俯瞰には有効にしてください。各結果がシンボルとリンクしている場合、4 つのモダリティすべてに適用されます。
branch任意
型
str
説明
ブランチの上書き
quality任意
型
Literal[quick, balanced, thorough]
デフォルト
balanced
説明
検索品質
include_content任意
型
bool
デフォルト
true
説明
結果にコンテンツを含める
explain_routing任意
型
bool
デフォルト
説明
ルーティング判断の説明を含める
importance_weight任意
型
float
デフォルト
0.3
説明
重要度ブーストの重み（0=なし、1=最大）
orphans任意
型
bool
デフォルト
説明
参照元が存在しないシンボル（デッドコードの可能性がある）を返します。クリーンアップに役立ちますが、デコレータ、内部関数、CLIのエントリーポイントが含まれる場合があります。
include_community_context任意
型
bool
デフォルト
説明
より広いコンテキストを得るため、同じコードコミュニティに属する関連シンボルを含めます。機能やモジュールの動作を調べる際に役立ちます。
community_depth任意
型
int
デフォルト
1
説明
コミュニティコンテキストを展開する深さ
graph_view任意
型
Literal[dependency, type, data_flow, control_flow]
デフォルト
dependency
説明
メトリクスに使用するグラフビュー
seed_symbol_ids任意
型
list[str]
説明
Tier-1 タスク シード: 現在のタスクの中心となるシンボル ID。設定すると、Approach A 深度減衰近接度 (正確なシード マッチ + グラフ エッジ ホップ) によって融合ヒットが再ランク付けされます。加算 — グローバル ランキングでは省略されます。
seed_file_paths任意
型
list[str]
説明
Tier-1 タスク シード: エージェントが開いているか編集したばかりのインデックス付きファイル パス。設定すると、1/(1+d) 深度減衰 (同じファイル → 同じディレクトリ → 近くのパッケージ) を使用したパスの近さによって、融合ヒットが再ランク付けされます。加算 — グローバル ランキングでは省略されます。

最適な用途:

  • 適切なツールが不明なときの、インデックス全体の探索やコールドスタート探索
  • セマンティック・テキスト・構造・グラフを横断した多モーダル融合ランキング

非推奨の用途:

  • 既知のシンボル名 — find_symbol を直接使う
  • ディスク上の既知のパス — まずローカルの Read/Grep を使う

semantic_search安定版

完全一致するテキストではなく、意味でコードを探します。キーワードやシンボル名が分からないときの「再試行ロジック」「ユーザー登録フロー」のような概念的な検索に使います。重要度で順位付けされた関連コードチャンクを返します。概念検索では Grep より優先してください。

パラメータ:

query必須
型
str
説明
検索クエリ（概念的・意味ベース）
repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
limit任意
型
int
デフォルト
5
説明
このランク付けされた top-K ウィンドウでの最大結果件数
similarity_threshold任意
型
float
デフォルト
0.6
説明
最小類似度スコア
language_filter任意
型
str
説明
指定したプログラミング言語として検出されたファイルに結果を絞り込みます
path_filter任意
型
str
説明
ファイルパスのプレフィックスで絞り込む
boost_by_importance任意
型
bool
デフォルト
説明
オプトイン: PageRank による中心性で再ランク付けします（エージェントにとって安全なランク付けのためデフォルトは無効。アーキテクチャの俯瞰には有効にしてください）。
branch任意
型
str
説明
ブランチの上書き（既定：repository パラメータまたは main）
include_content任意
型
bool
デフォルト
true
説明
結果にチャンクの内容を含める
graph_view任意
型
Literal[dependency, type, data_flow, control_flow]
デフォルト
dependency
説明
メトリクス用のグラフビュー

最適な用途:

  • 概念的なクエリ（"how does auth work?"、"caching strategy"）
  • パッケージ横断の類似検索

非推奨の用途:

  • 既知のシンボル名 — 代わりに find_symbol を使う
  • 厳密な文字列やエラーメッセージ — text_pattern_search を使う

text_pattern_search安定版

インデックス済みコンテンツを検索します。exact と regex モードはファイル／blob の全コーパスを grep し、fuzzy content モードは範囲を限定したセマンティックチャンクのコーパスを検索します。file と symbol スコープは fuzzy 専用です。ディスク上の狭いディレクトリならローカルの Grep を使ってください。

パラメータ:

query必須
型
str
説明
テキストパターン
repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
mode任意
型
Literal[fuzzy, exact, regex]
デフォルト
exact
説明
検索モード
search_scope任意
型
Literal[content, symbols, files]
デフォルト
content
説明
検索対象
limit任意
型
int
デフォルト
5
説明
このページで返される最大結果件数
offset任意
型
int
説明
非推奨の互換用 offset。pagination.next_cursor の cursor を使用してください。
cursor任意
型
str
説明
pagination.next_cursor から得た不透明な cursor。変更せずにそのまま渡し、query とフィルターも変更しないでください。
language_filter任意
型
str
説明
言語フィルタ
path_filter任意
型
str
説明
ファイルパスのプレフィックスで絞り込む
case_sensitive任意
型
bool
デフォルト
説明
大文字・小文字を区別
branch任意
型
str
説明
ブランチの上書き
fuzzy_algorithm任意
型
Literal[hybrid, trigram, levenshtein]
デフォルト
hybrid
説明
あいまい一致アルゴリズム
threshold任意
型
float
デフォルト
0.05
説明
あいまい検索の最小類似度しきい値
semantic_fallback任意
型
bool
デフォルト
説明
結果がない場合はセマンティック検索にフォールバック

最適な用途:

  • 厳密な文字列、エラーメッセージ、正規表現
  • 曖昧一致に対するトライグラムのファジーマッチング

非推奨の用途:

  • ディスク上の既知のパス — ローカルの Grep を優先する
  • 概念的なクエリ — semantic_search を使う

構造・グラフツール#

structural_search安定版

preset=functions|classes|methods|imports|variables（または自由な pattern=）を優先してください。コードを AST の形状（テキストではなく）で検索します。中間層のフィルター: name_pattern、node_type、decorator、parent_child。path/ltree/call 系のフィルターは高度な用途です。意図して使う場合は advanced=true を設定してください。後方互換のためフラットな advanced キーも引き続き受け付けます。少なくとも 1 つの構造セレクターを指定してください。

パラメータ:

repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
preset任意
型
Literal[functions, classes, methods, imports, variables]
説明
推奨される構造セレクター。言語横断的な AST ノードタイプに展開されます — functions（各言語の function/arrow/method 定義）、classes（class/struct/impl 定義）、methods（method 定義。method ノードを持たない言語では function_definition）、imports（import/use/include 文）、variables（variable/let/const/static 宣言）。ブラウズ形式のクエリでは自由形式の pattern/node_type より優先してください。
pattern任意
型
str
説明
preset では粗すぎる場合の自由形式パターン（自動検出: 'def foo(' → node_type + name_pattern）。ブラウズ系クエリでは preset= を優先してください。
name_pattern任意
型
str
説明
シンボル名のパターン（シェルのワイルドカード、範囲を限定した POSIX 正規表現、またはあいまいテキスト。最大 256 文字）
node_type任意
型
str
説明
AST ノードタイプ（function_definition、class_definition など）。一般的な形状には preset= を優先してください。
decorator任意
型
str
説明
デコレータ名フィルタ
base_class任意
型
str
説明
基底クラス名フィルタ（これを継承しているクラスを検索）
language_filter任意
型
str
説明
言語フィルタ
limit任意
型
int
デフォルト
20
説明
このページで返される最大結果件数
offset任意
型
int
説明
非推奨の互換用 offset。pagination.next_cursor の cursor を使用してください。
cursor任意
型
str
説明
pagination.next_cursor から得た不透明な cursor。変更せずにそのまま渡し、query とフィルターも変更しないでください。
path_filter任意
型
str
説明
ファイルパスのプレフィックスで絞り込む
branch任意
型
str
説明
ブランチの上書き
query_type任意
型
Literal[node_type, name_pattern, parent_child]
説明
明示的なクエリ種別
parent_type任意
型
str
説明
親 AST ノード種別の絞り込み
relationship任意
型
Literal[parent, ancestor]
デフォルト
parent
説明
parent_child クエリの場合：直接の親のみ、または任意の祖先（クラス本体やブロック内にネストされたクラスメソッドには ancestor を使用）
has_modifier任意
型
str
説明
修飾子で絞り込む（export、async、static など）
advanced任意
型
bool
デフォルト
説明
高度なパス、ltree、または呼び出しフィルター (ltree_ancestor、ltree_descendant、min_depth、max_depth、field_role、definition_name、callee_text、callee_name) を意図的に使用する場合は、true を設定します。デフォルトでは、false はエージェント インターフェイスをプリセットに重点を置いたままにします。フラット形式の高度なキーは、下位​​互換性のために引き続き機能しますが、メタデータの警告が表示されます。
callee_text任意
型
str
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。呼び出し式の callee テキストによるフィルター。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。
callee_name任意
型
str
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。呼び出し式の callee 名によるフィルター。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。
field_role任意
型
str
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。AST の field role によるフィルター。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。
ltree_ancestor任意
型
str
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。AST の ltree 祖先パスによるフィルター。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。
ltree_descendant任意
型
str
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。AST の ltree 子孫パスによるフィルター。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。
definition_name任意
型
str
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。定義名によるフィルター。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。
min_depth任意
型
int
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。AST の最小の深さ。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。
max_depth任意
型
int
説明
高度 — preset=functions|classes|methods|imports|variables を優先してください。AST の最大の深さ。path/ltree/call 系のフィルターを意図的に使う場合は advanced=true を設定してください。

最適な用途:

  • AST レベルの構造：クラス、デコレータ、関数／メソッドのプリセット
  • テキストではなく形状でコードを探す

非推奨の用途:

  • 自由文や概念的なクエリ — semantic_search または intelligent_search を使う

dependency_search安定版

主要な blast-radius／グラフ用サーフェス。実際の呼び出し／インポートグラフを介して「何がこれを呼び出しているか」「これが何を使っているか」に答えます。編集前の影響範囲には: analysis_type="dependents" または analysis_type="impact"（incoming、impact のデフォルトの深さは shallow）、include_metrics はデフォルトで false（中心性 + refactor_risk にはオプトイン）。PR/diff の影響（P1-8）: changed_paths や patch（unified diff）を渡すと、パスごとにシンボルを解決し、シンボル名を必要とせずコンパクトな shallow-incoming の dependents ペイロードを返します。編集後は、verify_after_edit=true に targets や changed_paths を指定すると、影響を受けたシンボルをコンパクトにマルチルート再クエリします。dependencies、centrality、orphans もサポートします。analyze_dependencies は impact パスへの薄いエイリアスです — 新しいエージェントではこのツールを優先してください。

パラメータ:

repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
query任意
型
str
説明
シンボル名または検索語
target任意
型
str
説明
シンボル名（query の別名）
changed_paths任意
型
list[str]
説明
PR/diff のリポジトリ相対パスは影響します (デフォルト)、または verify_after_edit=true の場合は編集後にルートを確認します。 PR/diff: パス​​ごとにシンボルを解決し、浅い受信依存をたどります。 patch=と組み合わせることができます。検証: パスごとに最大 5 つのシンボルを検証ルートとして解決します (検証モード内で上限が設定されています)。 PR/diff インパクトには query/target は必要ありません。
patch任意
型
str
説明
PR/diff の影響: 統合された diff / git パッチ テキスト。パスは diff --git / --- / +++ ヘッダーから解析されます。 changed_pathsと同じコンパクトなインパクトパス。
analysis_type任意
型
Literal[centrality, dependencies, dependents, impact, orphans]
デフォルト
dependencies
説明
解析モード。impact = 影響範囲（incoming の dependents。depth を省略すると shallow の深さ）。dependents も impact に答えます。changed_paths または patch を設定すると、解析は PR/diff の impact に強制されます。centrality/orphans は target を必要としません。
depth任意
型
Literal[shallow, balanced, deep]
デフォルト
balanced
説明
トラバースの深さ。analysis_type=impact および PR/diff の impact では、depth を明示的に設定しない限り実効デフォルトは shallow です。
limit任意
型
int
デフォルト
20
説明
このページで返される最大結果件数
offset任意
型
int
説明
非推奨の互換用 offset。pagination.next_cursor の cursor を使用してください。
cursor任意
型
str
説明
pagination.next_cursor から得た不透明な cursor。変更せずにそのまま渡し、query とフィルターも変更しないでください。
path_filter任意
型
str
説明
対象シンボルの解決を指定したファイルパスのプレフィックスに限定します。返されるグラフのリレーションはそのパスの外に及ぶ場合があります。
language_filter任意
型
str
説明
対象の解決とブラウズ結果を言語でフィルターします
direction任意
型
Literal[outgoing, incoming, both]
説明
走査方向（analysis_type の推論を上書き）
relationship_types任意
型
list[str]
説明
エッジタイプをフィルターします（CALL、IMPORT、INHERITS_FROM など）。空でないリストは graph_view のデフォルトを上書きします。
exclude_test_paths任意
型
bool
デフォルト
true
説明
デフォルトは true: テスト、フィクスチャ、ベンダー、サンプルのパスをトラバースおよび中心性の結果から除外します。含めるには false を設定してください。orphan 解析は常に独自のより厳格なノイズ除外を適用します。
exclude_generated_paths任意
型
bool
デフォルト
説明
生成された宣言とビルド、カバレッジ、キャッシュ、ソースマップ、および縮小されたアーティファクト パスをトラバーサル結果から除外します。
include_module_symbols任意
型
bool
デフォルト
説明
デフォルトでは、from_name または to_name が合成 __module__ シンボル (モジュールレベルのノイズ) である場合、false はグラフのエッジを除外します。依存関係および依存関係の結果にモジュールレベルのエッジを含めるように true を設定します。
branch任意
型
str
説明
ブランチの上書き
per_hop_limit任意
型
int
説明
ホップごとの最大リレーション数（1〜300）
include_metrics任意
型
bool
デフォルト
説明
結果行へのオプトインのグラフメトリクス（refactor_risk とともにコンパクト化）。min_centrality>0 のときメトリクスは内部的にも取得されますが、これが true でない限り返されません。
metrics_detail任意
型
Literal[summary, full]
デフォルト
summary
説明
include_metrics=true の場合: summary (デフォルト) は決定信号 + refactor_risk を返します。 full は、より大きな厳選されたメトリクス セットを返します
include_edge_metadata任意
型
bool
デフォルト
説明
生のエッジ メタデータと重み (大) を含めます。コンパクトな衝撃ペイロードでは、これはオフのままです。
symbol_types任意
型
list[str]
説明
返されるシンボルを種類でフィルターします（function、class、method など）
exact_match任意
型
bool
デフォルト
説明
シンボル名の完全一致を要求します（大文字・小文字は区別しません）。あいまい一致は無効になります
find_similar_patterns任意
型
bool
デフォルト
説明
類似する利用パターンを探す
min_centrality任意
型
float
デフォルト
0
説明
最小の PageRank スコア。メトリクスはフィルタリングのため内部的に取得されます。graph_metrics は include_metrics=true のときのみ返されます。
graph_view任意
型
Literal[dependency, type, data_flow, control_flow]
デフォルト
dependency
説明
トラバースのリレーションのデフォルト、メトリクス、中心性ランキングに使用するグラフビュー。orphan 解析はすべてのビューにわたって計算されます。
verify_after_edit任意
型
bool
デフォルト
説明
P2-7 編集後検証モード: 1 つのコンパクトなマルチルート応答で、最近編集されたシンボルのインデックス付きインパクト グラフを再クエリします。 targets および/または changed_paths (または target/query) が必要です。デフォルトでは浅い受信依存関係になります。結果はインデックス付きグラフを反映します (ライブ編集より遅れる可能性があります)。 true の場合、同じ changed_paths に対する PR/diff の影響よりも優先されます。
targets任意
型
list[str]
説明
verify_after_edit=true の場合: 再検証するシンボル名 (呼び出し元/依存関係)。両方が指定されている場合は、target/query と結合されます。

最適な用途:

  • 共有シンボルを編集する前の影響範囲／インパクト分析
  • changed_paths や patch による PR／差分の影響分析
  • verify_after_edit による編集後の検証

非推奨の用途:

  • 単純なテキストやシンボルの検索 — text_pattern_search または find_symbol を使う

コード解析ツール#

find_symbol安定版

関数、クラス、変数が定義・使用されている場所へ移動します。名前（例：「getCurrentUser」）が分かっているときに使います。Grep より高速かつ正確で、インデックス済みリポジトリ全体が対象です。参照と重要度メトリクスも任意で返せます。

パラメータ:

symbol_name任意
型
str
説明
検索するシンボル名（省略可 — 省略するとメトリクスで参照）
repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
scope任意
型
Literal[definitions, references, both]
デフォルト
both
説明
スコープ: definitions|references|both
limit任意
型
int
デフォルト
15
説明
このページで返される最大結果件数
offset任意
型
int
説明
非推奨の互換用 offset。pagination.next_cursor の cursor を使用してください。
cursor任意
型
str
説明
pagination.next_cursor から得た不透明な cursor。変更せずにそのまま渡し、query とフィルターも変更しないでください。
find_similar任意
型
bool
デフォルト
説明
類似シンボルを検索
include_metrics任意
型
bool
デフォルト
説明
中心性メトリクスを含める
metrics_detail任意
型
Literal[summary, full]
デフォルト
summary
説明
include_metrics=true の場合: summary (デフォルト) は決定信号 + refactor_risk を返します。 full は、より大きな厳選されたメトリクス セットを返します
path_filter任意
型
str
説明
ファイルパスのプレフィックスで絞り込む
branch任意
型
str
説明
ブランチの上書き
symbol_type任意
型
Literal[function, class, variable, method, constant, module, interface, type]
説明
シンボルタイプフィルタ
high_impact任意
型
bool
デフォルト
説明
アーキテクチャ上重要なシンボルをブラウズします（symbol_name を省略）。デフォルトのモードは人気度（PageRank の上位 10 パーセンタイルからユーティリティのメガハブを除いたもの）です。分岐点／ブリッジの切断頂点には high_impact_mode=risk を設定してください。
high_impact_mode任意
型
Literal[popularity, risk]
デフォルト
popularity
説明
high_impact=true の場合: 人気 = トップ PageRank 十分位からユーティリティ メガ ハブ/モジュールを差し引いた数。リスク = SMV、bridge_count、次に k_core によってランク付けされたアーティキュレーション ポイント (ハブの人気ではなく、構造リファクタリングのリスク)
in_cycle任意
型
bool
デフォルト
説明
サイクル内のみ
exclude_test_paths任意
型
bool
デフォルト
true
説明
グラフ メトリクスで参照する場合は、ランキングの前にテスト、fixtures、サードパーティのコード、および例を除外します。名前付きシンボルによる検索は変更されません。

最適な用途:

  • 既知のシンボルの定義、参照、グラフ指標を特定する
  • symbol_name を省略したときに centrality、high_impact、in_cycle で一覧する

非推奨の用途:

  • 概念的なクエリや未知の領域のクエリ — intelligent_search または semantic_search を使う

analyze_dependencies安定版

dependency_search（dependents/incoming）を介した blast-radius のエイリアス。新しいエージェントでは analysis_type="dependents" または "impact" を指定した dependency_search を優先してください。従来のマルチホップ impact のレスポンス形状（graph、connection_summary、refactor_risk を含む任意のメトリクス）を保持します。リレーションのファミリーをスコープするには graph_view を使用してください: dependency（デフォルト）、type、data_flow、control_flow。

パラメータ:

repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
target必須
型
str
説明
分析するシンボル名
depth任意
型
Literal[shallow, balanced, deep]
デフォルト
balanced
説明
分析の深さ（エイリアス対応: auto、shallow/quick=1、balanced/medium=2、deep/thorough=3）
limit任意
型
int
デフォルト
10
説明
このページで返される最大結果件数
offset任意
型
int
説明
非推奨の互換用 offset。pagination.next_cursor の cursor を使用してください。
cursor任意
型
str
説明
pagination.next_cursor から得た不透明な cursor。変更せずにそのまま渡し、query とフィルターも変更しないでください。
direction任意
型
Literal[incoming, outgoing, both]
デフォルト
incoming
説明
走査方向: 'outgoing' = このシンボルが依存しているもの（依存先）、'incoming' = このシンボルに依存しているもの（依存元）、'both' = 両方を含む全体のコンテキスト。あるシンボルの呼び出し元/利用元をすべて見つけるには 'incoming' を使用してください。
relationship_types任意
型
list[str]
説明
エッジ種別（CALL、IMPORT、INHERITS_FROM など）で絞り込みます。指定した場合は、後述の graph_view から導出される既定値を常に上書きします。
graph_view任意
型
Literal[dependency, type, data_flow, control_flow]
デフォルト
dependency
説明
グラフビュー：include_metrics=true のとき、既定の走査エッジ種別と、メトリクスに使用するビューの両方を決めます。dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES]（既定）、type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE]、data_flow=[READS,WRITES,ASSIGNS_TO]、control_flow=[CONTROL_FLOW,THROWS,CATCHES]。relationship_types が明示されていない場合にのみ、その既定値として適用されます。ツール間の一貫性を保つため、dependency_search の既存パラメータ名 graph_view と合わせています。
path_filter任意
型
str
説明
対象シンボルの解決を指定したファイルパスのプレフィックスに限定します。返されるグラフのリレーションはそのパスの外に及ぶ場合があります。
language_filter任意
型
str
説明
結果を特定の言語に限定します
branch任意
型
str
説明
ブランチの上書き
per_hop_limit任意
型
int
説明
ホップごとの最大リレーション数（1〜300）
include_metrics任意
型
bool
デフォルト
説明
グラフメトリクスを結果に含め、各要素に派生 refactor_risk ブロック（{risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}）を付加します。選択ビューで関節点でなければ "low"、少数のエッジを橋渡しする関節点なら "medium"、多数なら "high" です（経験的検証をしていないヒューリスティックなしきい値）。そのシンボル／ビューにメトリクス行がなければ省略されます。
metrics_detail任意
型
Literal[summary, full]
デフォルト
summary
説明
include_metrics=true の場合: summary (デフォルト) は決定信号 + refactor_risk を返します。 full は、より大きな厳選されたメトリクス セットを返します
include_edge_metadata任意
型
bool
デフォルト
説明
生のエッジメタデータと重みを含めます。エクストラクターのメタデータは大きくなる可能性があるため、デフォルトでは無効になっています。エンリッチメント カバレッジは、有効にすると報告されます。
exclude_test_paths任意
型
bool
デフォルト
true
説明
デフォルトの true: 返されたグラフ エッジからテスト、フィクスチャ、ベンダー、サンプル パスを除外します。それらを含めるように false を設定します。
include_module_symbols任意
型
bool
デフォルト
説明
デフォルトでは、from_name または to_name が合成 __module__ シンボルである場合、false はグラフのエッジを除外します。モジュールレベルのエッジを含むように true を設定します。

最適な用途:

  • そのレスポンス形状（graph、connection_summary）に既に依存しているレガシーな呼び出し元

非推奨の用途:

  • 新しいエージェントのループ — 同じ走査コアを共有する dependency_search を優先する

get_task_context安定版

不慣れな領域で作業を始めますか? タスクを説明すると（例: "add SSO support"、"fix the billing webhook"）、関連するファイル、コード、シンボル、依存関係を境界付きの 1 回の呼び出しでまとめて取得します。シードされたファイルは、シンボルを定義していなくても直接インデックスされた内容を提供します。より多くの結果が必要な場合は、そのレイヤー専用の検索ツールに続けてください。

パラメータ:

task_description必須
型
str
説明
タスクの説明
repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
limit任意
型
int
デフォルト
15
説明
レイヤーごとの最大結果数
scope任意
型
Literal[semantic, symbols, dependencies, all]
デフォルト
all
説明
含めるコンテキストレイヤー。有効な値: 'semantic'、'symbols'、'dependencies'、'all'。デフォルト: ['semantic', 'symbols', 'dependencies']
language_filter任意
型
str
説明
指定したプログラミング言語として検出されたファイルに結果を絞り込みます
path_filter任意
型
str
説明
ファイルパスのプレフィックスで絞り込む
branch任意
型
str
説明
ブランチの上書き
include_related_context任意
型
bool
デフォルト
説明
隣接シンボルから関連コンテキストを含める
seed_symbol_ids任意
型
list[str]
説明
Tier 1 の明示的シード：エージェントがタスクの中心だと既に把握しているシンボル ID（例：開いているファイル内のシンボル）。dependencies/related_context レイヤーでは、キーワードから導出したシードより先にランク付けされます。追加指定なので、現在のキーワードのみの動作を使う場合は省略してください。
seed_file_paths任意
型
list[str]
説明
Tier-1 の明示的なシード: エージェントが開いている、または編集したばかりのインデックス済みファイルパス。境界付きの直接ファイル証拠を返し、グラフのコンテキスト用にファイルごとに最大 5 つのシンボルを解決します（シンボルのないドキュメントや設定も含む）。付加的です — キーワードのみの動作にする場合は省略してください。

最適な用途:

  • シードしたファイルをセマンティック・シンボル・依存関係のレイヤーと組み合わせる、タスクを意識したコンテキスト

非推奨の用途:

  • より特化したツールで既に答えが出せる、単一ツールの検索

get_file安定版

パスを指定してインデックス済みリポジトリからファイルを読み取ります。ディスク上のファイルにはローカルの Read ツールを優先してください — これは作業ツリーにないクロスリポジトリまたはリモートの参照に使用します。任意の行範囲をサポートします。トークンで切り詰められたレスポンスは metadata.next_line_start から続行してください。

パラメータ:

file_path必須
型
str
説明
リポジトリルートからの相対ファイルパス
repository任意
型
str
説明
owner/repo[:branch] 形式のリポジトリ。省略可能です。省略すると、リクエストスコープのクライアント既定値（提供されている場合）またはアクセス可能な唯一のリポジトリを使用します。別のインデックス済みリポジトリを対象にする場合だけ明示的に渡してください。レスポンスには使用されたリポジトリが表示されます。
line_start任意
型
int
説明
開始行（1 始まり）
line_end任意
型
int
説明
終了行（1 始まり、両端を含む。line_start 以上である必要があります）
branch任意
型
str
説明
ブランチの上書き
max_tokens任意
型
int
デフォルト
5000
説明
最大トークン数
include_metadata任意
型
bool
デフォルト
true
説明
メタデータを含める

最適な用途:

  • リモートまたはインデックス済みファイルのスナップショット（行範囲、トークン上限）

非推奨の用途:

  • 既にローカルディスク上にあるパス — ローカルの Read ツールを使う

システム・ユーティリティツール#

repository_context安定版

検索できるリポジトリを一覧表示するか、いずれかのアイデンティティ情報（namespace/branch、indexed_commit_sha／インデックスの鮮度）を取得します。検索ツールが受け付ける正確なリポジトリスラッグを知るには、一度 action:"list" で呼び出してください。（キーにリポジトリが 1 つだけの場合、検索ツールはそれをデフォルトにするため省略できます。）namespace 全体のファイル／ブロブ／エッジ数は include_statistics=true でオプトインできます。

パラメータ:

action必須
型
Literal[list, info]
説明
操作：利用可能なリポジトリの一覧、またはリポジトリ情報の取得
repository任意
型
str
説明
owner/repo または owner/repo:branch 形式のリポジトリ（info では必須）
branch任意
型
str
説明
ブランチの上書き
pattern任意
型
str
説明
フィルタパターン
include_statistics任意
型
bool
デフォルト
説明
オプトイン: namespace 全体のインデックスデータ数（ファイル／ブロブ／エッジ）を含めます。デフォルトは false — リポジトリのアイデンティティにはこの低速な集計は不要です。
limit任意
型
int
デフォルト
20
説明
このページで返される最大結果件数
offset任意
型
int
説明
非推奨の互換性オフセット。 pagination.next_cursor よりも cursor を優先します。
cursor任意
型
str
説明
pagination.next_cursor の不透明 cursor。これを変更せずに渡し、クエリとフィルターは変更しないでください。

最適な用途:

  • アクセス可能なリポジトリの一覧表示
  • リポジトリの識別、ブランチ、HEAD とインデックスの鮮度の解決

非推奨の用途:

  • 既定でのネームスペース全体の統計 — 解決処理より遅くなりうるため、include_statistics=true を明示的に渡す

ask_maguyva安定版

Maguyva のヘルプとフィードバック。主な用途: ツールのガイダンスを得る、または Maguyva のメンテナー向けに保存されるバグレポート／機能リクエストを送信します。フィードバックに秘密情報や機微な個人データを含めないでください。evaluate 操作は後方互換のためだけに残っています — 計算／ハッシュ／文字列処理にはローカル計算やホストのツールを優先してください。

パラメータ:

operation必須
型
Literal[guidance, report_bug, request_feature, evaluate]
説明
主な用途: guidance、report_bug、request_feature。レガシー／互換用のみ: evaluate（決定論的な式エンジン。主要なエージェントワークフローの一部ではありません）。
query任意
型
str
説明
ガイダンスのトピック（例: tool_selection、semantic_search）。レガシーの evaluate 用のみ: 式の文字列。
description任意
型
str
説明
report_bug と request_feature に必須。Maguyva のメンテナー向けの自由形式フィードバックです。秘密情報や機微な個人データを含めないでください。
related_tool任意
型
Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
説明
フィードバックに最も密接に関連するオプションの Maguyva ツール

最適な用途:

  • ツールのガイダンス（operation="guidance"）
  • Maguyva のメンテナー向けの永続的なバグ報告や機能要望

非推奨の用途:

  • 数値／ハッシュ／文字列の計算 — evaluate 操作はレガシー／後方互換専用であり、ローカルホストでの計算を優先する

ベストプラクティス#

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

パフォーマンス特性#

操作パフォーマンスに関する注記
セマンティック検索1秒未満ですが、毎回ライブの埋め込みAPI呼び出しを伴います（キャッシュされません）。ベクトルクエリに加えて追加のレイテンシが発生する点にご注意ください
テキスト検索exact/regex は1秒未満です。あいまいなコンテンツ検索はクライアント側でページングされるため、深いオフセットほどコストが増えます。path_filter/language_filter で絞り込んでください
構造検索AST でインデックス化されており、コストはリポジトリのサイズではなく結果の件数に比例します
依存関係検索コストは深さに比例します。マルチホップのコンテキストが必要でない限り depth="shallow" を推奨します。per_hop_limit で展開の広がりを制限できます
ファイル取得単一ファイルならほぼ瞬時です。大きなファイルは一度に大量取得するのではなく、line_start/line_end または max_tokens でページングしてください
リポジトリコンテキスト名前空間の解決はリクエストごとにのみキャッシュされ、呼び出しをまたいでは保持されません。ツールを呼び出すたびに再解決されます
ask_maguyva（guidance / evaluate）ほぼ瞬時です。データベース呼び出しなしで Worker 内で実行されます

エラー処理#

すべてのAPIメソッドは構造化されたエンベロープを返します:

  • status: 文字列 — "success" または "error"。低下した一致や鮮度のシグナルは、repository_context の metadata.resolution_reason や metadata.index_freshness.status といったネストされたフィールドに含まれます。
  • tool: レスポンスを生成したツールの名前
  • data: 成功時の結果ペイロード（構造はツールによって異なります）
  • error: status が "error" の場合の構造化エラーオブジェクト — type、message、suggestions、recovery_actions を含みます
  • metadata: 操作に関する追加情報（ルーティング、キャッシュ、パラメータ調整）
  • pagination: リスト応答に含まれます — has_more と next_cursor を含みます

結果を処理する前に必ず status フィールドを確認してください。値は必ず "success" か "error" のどちらかです。低下した一致や鮮度のシグナルについては、代わりにネストされたフィールドを参照してください。repository_context の metadata.resolution_reason、または metadata.index_freshness.status（known/partial/unknown/unavailable）です。

はじめに#

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

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