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

Практичні рецепти для щоденної роботи з Maguyva MCP. Кожен рецепт називає інструменти та послідовність дій, але не замінює повного довідника параметрів. Параметри інструментів наведено в розділі «Довідник MCP API». Для першого налаштування скористайтеся розділом «Швидкий старт».

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

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

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

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

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

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

Застрягли на ключах, мостах або відсутніх репо? Усунення несправностей.

Визначте символи та радіус впливу перед зміною спільного коду. Інструменти 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 та актуальність індексу, перш ніж вважати результат доказом для нової ревізії, і запустіть локальні тести.

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

Повні параметри: Довідник 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 призначений для виявлення та перевірки, а не для запису.

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

Чому цей цикл працює: Як це працює.

Якщо інструменти не повертають нічого корисного, перевірте визначення репозиторію та індексацію, перш ніж нескінченно переписувати запит.

1. Переконайтеся, що репозиторій підключено та завершено індексування в app.maguyva.ai.
2. Перевірте рядок репозиторію: "owner/repo" використовує гілку за замовчуванням; "owner/repo:branch" прикріплює гілку. Зіставлення не залежить від регістру, не є нечітким — помилки не виправляються автоматично.
3. Викличте repository_context з action="info" і перевірте метадані визначення репозиторію (наприклад, metadata.resolution_reason).
4. Пропустіть repository лише тоді, коли ваш MCP-клієнт надає значення за замовчуванням для поточного запиту або ключ має доступ рівно до одного репозиторію; інакше передайте параметр явно.
5. Повторіть спробу з більш конкретним запитом, відомою назвою символу через find_symbol або фільтром мови/шляху. Якщо саме з'єднання порушено, використовуйте Усунення несправностей.

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

Помилки налаштування: Усунення несправностей.

Націлюйтеся на правильне індексоване репо, коли ключ може бачити більше одного.

1. Один раз викличте repository_context з action="list", щоб дізнатися точні ідентифікатори репозиторіїв, у яких ваш ключ дозволяє шукати.
2. Передайте repository явно в інструменти пошуку та роботи із символами, коли вам потрібне репо не за замовчуванням (наприклад, "owner/other-repo" або "owner/other-repo:develop").
3. Дотримуйтеся правила «одне запитання = один репозиторій», якщо не порівнюєте репозиторії навмисно в окремих викликах.
4. Використовуйте get_file, коли файл знаходиться в індексованому репо, яке не є вашим поточним робочим деревом.
5. Пам’ятайте: інструменти ніколи не записують назад до GitHub — контекст кількох репозиторіїв призначено лише для читання та планування.

Деталі формату репозиторію: Довідник MCP API.

• Швидкий старт — ключ, індекс, підключення, перша оцінена відповідь
• Посібник зі встановлення — конфігурація MCP для кожного клієнта
• Довідник MCP API — кожен інструмент, параметр за параметром
• Усунення несправностей — проблеми з API-ключем, мостом і репозиторієм