本文へスキップ

レシピ集

日常的な Maguyva MCP 作業のための実践的なレシピです。各レシピではツールと手順を示しますが、パラメータの完全なリファレンスではありません。ツールのパラメータは MCP API リファレンス、初回セットアップは クイックスタート を参照してください。

適切なツールを選ぶ#

ほとんどの質問は 1 回の呼び出しから始められます。最初の答えが広すぎる、または薄すぎる場合にだけ次へ進みます。

  • intelligent_search — 自然言語によるコードベースの質問はここから始めます。セマンティック、シンボル、構造、依存関係の各検索へ振り分けます。
  • find_symbol — 関数、クラス、変数の名前がすでに分かっている場合に使います。
  • dependency_search — 編集前後の影響範囲、つまり呼び出し元、依存先、変更の波及を確認します。
  • get_task_context — 不慣れな領域で、タスク記述に関係するファイル、シンボル、依存関係を 1 つの限定された束として取得します。
  • repository_context — アクセス可能なリポジトリを一覧表示するか、リポジトリ名の解決方法を調べます。
  • operation="guidance" を指定した ask_maguyva — ツール選択と Maguyva の使い方をローカルで案内します（リポジトリは変更しません）。

クライアントをインストールして確認する#

MCP クライアントに Maguyva を追加し、実際のリポジトリ一覧で接続を確認します。

  1. app.maguyva.ai で API キーを作成します（キーは mgv_ で始まります）。
  2. 内容を把握している GitHub リポジトリを少なくとも 1 つ接続し、インデックスを作成します。
  3. インストールガイド に従ってクライアントを設定します（Claude Code プラグイン、または Cursor、VS Code、Windsurf、Zed などのネイティブなリモート設定）。
  4. エージェントに "接続しているリポジトリは何ですか？" と尋ねます。これで認証と repository_context を最初から最後まで確認できます。
  5. 答えを評価できる実際の質問をそのリポジトリについて 1 つ尋ねます。インデックス済みツリーのファイルパスと行番号が表示されるはずです。

キー、ブリッジ、見つからないリポジトリで詰まった場合は トラブルシューティング を参照してください。

編集する前に尋ねる#

共有コードを変更する前に、シンボルと影響範囲を把握します。Maguyva のツールはリポジトリを変更せず、クライアントがローカルで行う編集に根拠を与えます。

  1. シンボル名が分かっている場合は find_symbol を呼び出し、定義と使用箇所へ移動します。
  2. タスク記述（「SSO を追加」「請求 Webhook を修正」など）しかない場合は、get_task_context または intelligent_search から始めます。
  3. 共有シンボルを編集する前に、依存先や影響分析を指定して dependency_search を呼び出します（または PR 形式の影響確認用に変更パスを渡します）。
  4. 参照されたファイルを開き（ディスク上のファイルはローカルで読み、リモートまたは別リポジトリのパスは get_file を使います）、実際のコードに照らして計画を確認します。
  5. 編集後、同じシンボルを dependency_search でもう一度確認し（クライアントが対応していれば編集後検証フラグも使用）、呼び出し元が期待どおり解決されることを確かめます。

全パラメータ: MCP API リファレンス。

検索してから変更する#

標準的なエージェントのループ: 探索 → シンボルを特定 → 根拠を持って編集。

  1. intelligent_search と自然言語の質問（「セッションの有効期限はどう動くか」「再試行ロジックはどこか」など）から始めます。
  2. 最初の結果が騒がしい場合は、言語またはパスのフィルターで絞り込みます。
  3. 有望な結果は、同じ曖昧な質問を繰り返す代わりに find_symbol または dependency_search で掘り下げます。
  4. ディスク上にない特定のインデックス済みパスが必要な場合にだけ get_file を使います。
  5. 通常のクライアントツールで編集します。Maguyva は探索と検証のためのもので、書き込み用ではありません。

このループが機能する理由: 仕組み。

結果が空、または情報が少ない場合#

ツールから有用な結果が返らない場合、延々と質問を書き換える前に、解決方法とインデックス作成を直します。

  1. app.maguyva.ai でリポジトリが接続済みで、インデックス作成が完了していることを確認します。
  2. リポジトリ文字列を確認します。"owner/repo" は既定ブランチを使用し、"owner/repo:branch" はブランチを固定します。照合は大文字小文字を区別しませんが、あいまい検索ではないため、入力ミスは自動修正されません。
  3. action="info" を指定して repository_context を呼び出し、解決メタデータ（例: metadata.resolution_reason）を調べます。
  4. MCP クライアントがリクエストの既定値を提供するか、そのキーがちょうど 1 つのリポジトリにしかアクセスできない場合にだけ repository を省略します。それ以外は明示的に渡します。
  5. より具体的な質問、find_symbol に渡す既知のシンボル名、または言語・パスのフィルターで再試行します。接続自体が壊れている場合は トラブルシューティング を参照してください。

セットアップの問題: トラブルシューティング。

複数のリポジトリを横断して作業する#

1 つのキーから複数のリポジトリが見える場合に、正しいインデックス済みリポジトリを対象にします。

  1. action="list" を指定して repository_context を一度呼び出し、そのキーが検索できる正確なスラッグを確認します。
  2. 既定でないリポジトリが必要な場合は、検索ツールやシンボルツールに repository を明示的に渡します（例: "owner/other-repo" または "owner/other-repo:develop"）。
  3. 別々の呼び出しで意図的に比較する場合を除き、1 つの質問は 1 つのリポジトリに限定します。
  4. ファイルが現在の作業ツリーではなくインデックス済みリポジトリにある場合は get_file を使います。
  5. 覚えておいてください。ツールは GitHub へ書き戻しません。複数リポジトリのコンテキストは読み取りと計画のためだけにあります。

リポジトリ形式の詳細: MCP API リファレンス。

Maguyva が初めてなら、まず クイックスタート を一通り実行し、日常運用のループが必要になったらここへ戻ってきてください。

次のステップ#