# レシピ集

Canonical source: https://maguyva.ai/ja/docs/cookbook

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

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

### 適切なツールを選ぶ

ほとんどの質問は1回の呼び出しから始められます。最初の回答の範囲が広すぎる、または情報が不足している場合にだけ、さらに掘り下げます。

- `intelligent_search` — コードベースについて自然言語で質問する場合は、ここから始めてください。 デフォルトの auto/balanced は、意図を高い確度で判定できる定義の質問を構造検索へ、参照や影響の質問をグラフへ、完全一致の質問をテキスト検索へ振り分けます。それ以外の質問には、意味に基づく検索とインデックス済みテキストを使います。 4 つすべてを要求するには mode=hybrid、または auto と quality=thorough を指定します。明示的に指定した mode は quality より優先されます。
- `find_symbol` — 関数、クラス、変数の名前がすでに分かっている場合に使います。
- `dependency_search` — 編集前後の影響範囲、つまり呼び出し元、依存元、変更の波及を確認します。
- `get_task_context` — 不慣れな領域で、タスク記述に関係するファイル、シンボル、依存関係を 1 つの限定された束として取得します。
- `repository_context` — アクセス可能なリポジトリを一覧表示するか、リポジトリ名の解決方法を調べます。
- `operation="guidance"` を指定した `ask_maguyva` — ツール選択と Maguyva の使い方をローカルで案内します(リポジトリは変更しません)。

JSONブロックはMCP tools/callへの入力です。owner/repo、ブランチ名、シンボル名を、ご自身のリポジトリの値に置き換えてください。

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

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

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

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "list"
  }
}
```

キー、ブリッジ、見つからないリポジトリで詰まった場合は [トラブルシューティング](https://maguyva.ai/docs/troubleshooting) を参照してください。

### 編集する前に尋ねる

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

1. シンボル名が分かっている場合は `find_symbol` を呼び出し、定義と使用箇所へ移動します。
2. タスク記述(「SSO を追加」「請求 Webhook を修正」など)しかない場合は、`get_task_context` または `intelligent_search` から始めます。
3. 共有シンボルを編集する前に、dependents/impact分析を指定して `dependency_search` を呼び出し、影響範囲を確認します(またはPR形式の影響確認用に変更パスを渡します)。
4. 参照されたファイルを開き(ディスク上のファイルはローカルで読み、リモートまたは別リポジトリのパスは `get_file` を使います)、実際のコードに照らして計画を確認します。
5. 編集後は、`dependency_search` に verify_after_edit=true と targets または changed_paths を指定し、同じシンボルを再確認します。読み取るのはインデックス済みグラフであり、未コミットのローカル変更ではありません。新しいリビジョンの根拠として扱う前に indexed_commit_sha とインデックスの鮮度を確認し、ローカルテストも実行してください。

```json
{
  "name": "dependency_search",
  "arguments": {
    "repository": "owner/repo",
    "target": "getCurrentUser",
    "exact_match": true,
    "analysis_type": "impact",
    "depth": "shallow",
    "include_metrics": true,
    "limit": 10
  }
}
```

全パラメータ: [MCP API リファレンス](https://maguyva.ai/docs/mcp-api)。

### 検索してから変更する

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

1. `intelligent_search` と自然言語の質問(「セッションの有効期限はどう動くか」「再試行ロジックはどこか」など)から始めます。
2. 最初の結果にノイズが多ければ、言語やパスのフィルターで絞り込みます。language_filter を指定すると auto/hybrid からグラフが除外されます。auto でグラフだけに振り分けられた質問は、意味検索とテキスト検索にフォールバックします。明示的なグラフモードと language_filter の併用は拒否されます。選択された検索計画は routing_decision.modalities_used で確認できます。warnings はサーバーが警告を出したときにのみ現れます。
3. 有望な結果は、同じ曖昧な質問を繰り返す代わりに `find_symbol` または `dependency_search` で掘り下げます。
4. ディスク上にない特定のインデックス済みパスが必要な場合にだけ `get_file` を使います。
5. 通常のクライアントツールで編集します。Maguyva は探索と検証のためのもので、書き込み用ではありません。

```json
{
  "name": "intelligent_search",
  "arguments": {
    "repository": "owner/repo",
    "query": "How does session expiry work?",
    "limit": 5
  }
}
```

このループが機能する理由: [仕組み](https://maguyva.ai/docs/how-it-works)。

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

ツールから有用な結果が返らない場合、延々と質問を書き換える前に、リポジトリ名の解決とインデックス作成の状態を確認・修正します。

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

```json
{
  "name": "repository_context",
  "arguments": {
    "action": "info",
    "repository": "owner/repo:main"
  }
}
```

セットアップの問題: [トラブルシューティング](https://maguyva.ai/docs/troubleshooting)。

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

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 リファレンス](https://maguyva.ai/docs/mcp-api)。

初めて設定しますか? まず[クイックスタート](https://maguyva.ai/docs/quickstart)から始め、その後の日常的な作業にはこちらの手順集を使ってください。