# Сборник рецептов

Canonical source: https://maguyva.ai/ru/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. Явно заданный mode имеет приоритет над 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), а затем используйте эти рецепты для повседневных задач.