# Збірник рецептів

Canonical source: https://maguyva.ai/uk/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)».

### Виберіть правильний інструмент

Для більшості запитань почніть з одного виклику. Переходьте до додаткових інструментів, лише якщо перша відповідь надто загальна або містить замало інформації.

- `intelligent_search` — почніть тут із запитання про кодову базу природною мовою. За замовчуванням auto/balanced спрямовує запити, які з високою впевненістю визначено як запити про визначення, до структурного пошуку, запити про посилання чи вплив — до графа, а запити на точний збіг — до текстового пошуку. Інші запити використовують семантичний зміст та індексований текст. Використовуйте mode=hybrid або auto з quality=thorough, щоб запросити всі чотири різновиди пошуку; явно вказаний режим має пріоритет над quality.
- `find_symbol` — ви вже знаєте назву функції, класу чи змінної.
- `dependency_search` — радіус впливу: код, що викликає символ, код, що залежить від нього, або наслідки до й після редагування.
- `get_task_context` — незнайома область коду; один обмежений набір файлів, символів і залежностей за описом завдання.
- `repository_context` — список доступних репозиторіїв або перевірка того, як розпізнається назва репозиторію.
- `ask_maguyva` з `operation="guidance"` — локальна довідка щодо вибору інструменту та використання Maguyva (без мутації репо).

Блоки JSON містять вхідні дані для MCP tools/call. Замініть owner/repo, назву гілки та імена символів на значення зі свого репозиторію.

### Встановити та перевірити клієнта

Встановіть Maguyva у свій клієнт MCP і підтвердьте підключення за допомогою справжнього списку репозиторіїв.

1. Створіть ключ API у [app.maguyva.ai](https://app.maguyva.ai) (ключі починаються з `mgv_`).
2. Підключіть та проіндексуйте принаймні один репозиторій GitHub, який ви вже знаєте.
3. Налаштуйте підключення клієнта за інструкціями з розділу «[Посібник зі встановлення](https://maguyva.ai/docs/installation)» (плагін Claude Code або нативна конфігурація віддаленого підключення для Cursor, VS Code, Devin Desktop, Zed та інших).
4. Поставте своєму агенту запитання "Які репозиторії я підключив?" — це перевірить автентифікацію та `repository_context` від початку до кінця.
5. Поставте одне справжнє запитання про це репо, відповідь на яке ви можете оцінити. Ви повинні побачити шляхи до файлів і номери рядків з індексованого дерева.

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

Застрягли на ключах, мостах або відсутніх репо? [Усунення несправностей](https://maguyva.ai/docs/troubleshooting).

### Запитайте, перш ніж редагувати

Визначте символи та радіус впливу перед зміною спільного коду. Інструменти Maguyva не змінюють ваші репозиторії — вони надають дані для правок, які ваш клієнт застосовує локально.

1. Якщо ви знаєте назву символу, викличте `find_symbol`, щоб знайти визначення й місця використання.
2. Якщо у вас є лише опис завдання («додати SSO», «виправити платіжний вебхук»), почніть із `get_task_context` або `intelligent_search`.
3. Перед редагуванням спільного символу викличте `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. Викличте `repository_context` з `action="info"` і перевірте метадані визначення репозиторію (наприклад, `metadata.resolution_reason`).
4. Пропустіть `repository` лише тоді, коли ваш MCP-клієнт надає значення за замовчуванням для поточного запиту або ключ має доступ рівно до одного репозиторію; інакше передайте параметр явно.
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. Один раз викличте `repository_context` з `action="list"`, щоб дізнатися точні ідентифікатори репозиторіїв, у яких ваш ключ дозволяє шукати.
2. Передайте `repository` явно в інструменти пошуку та роботи із символами, коли вам потрібне репо не за замовчуванням (наприклад, `"owner/other-repo"` або `"owner/other-repo:develop"`).
3. Дотримуйтеся правила «одне запитання = один репозиторій», якщо не порівнюєте репозиторії навмисно в окремих викликах.
4. Використовуйте `get_file`, коли файл знаходиться в індексованому репо, яке не є вашим поточним робочим деревом.
5. Пам’ятайте: інструменти ніколи не записують назад до GitHub — контекст кількох репозиторіїв призначено лише для читання та планування.

Деталі формату репозиторію: [Довідник MCP API](https://maguyva.ai/docs/mcp-api).

Налаштовуєте вперше? Почніть із [Швидкий старт](https://maguyva.ai/docs/quickstart), а потім використовуйте ці рецепти для щоденних завдань.