Справочник MCP API

Полный справочник по всем 11 клиентским MCP-инструментам Maguyva. Для каждого инструмента указаны параметры, рекомендации по использованию и сценарии применения.

Обзор API#

MCP API Maguyva сейчас предоставляет 11 клиентских инструментов, распределённых по 4 основным категориям:

Базовые инструменты поиска - Продвинутые возможности поиска по вашей кодовой базе
Структурные и графовые инструменты - AST-запросы, поиск символов и анализ зависимостей
Инструменты анализа кода - Глубокий анализ кода и построение карты связей
Системные и вспомогательные инструменты - Контекст репозитория, детерминированные вычисления и подсказки

Все инструменты используют единый формат идентификатора репозитория: "owner/repo:branch". Если ветка не указана, используется main.

Не указывайте repository, если MCP-клиент задаёт значение по умолчанию для запроса или ключ имеет доступ ровно к одному репозиторию; в остальных случаях передайте его явно. Используйте repository_context(action="info", repository="owner/repo"), чтобы проверить, как разрешается репозиторий.

Формат параметра репозитория#

Все MCP-инструменты используют такой формат идентификатора репозитория:

С веткой: "owner/repo:branch" - например, "owner/repository:develop"
Ветка по умолчанию: "owner/repo" - используется основная ветка, если ветка не указана "owner/repository"
Значение по умолчанию из запроса или единственного репозитория: Не указывайте репозиторий, если MCP-клиент задаёт значение по умолчанию для запроса или ключ имеет доступ ровно к одному репозиторию; в остальных случаях передайте его явно

Примеры запросов:

Вопрос о конкретном репозитории:    «Найди в owner/my-repo мидлвар аутентификации»
Перечислить доступные репозитории:  "К каким репозиториям имеет доступ этот ключ Maguyva?"
Переопределить для одного запроса:  «Найди в owner/other-repo:develop паттерны аутентификации»

Фильтрация по языку#

Все инструменты поиска поддерживают фильтрацию результатов по языку программирования:

language_filter="python" - Фильтр только по файлам Python
language_filter="typescript" - Фильтр только по файлам TypeScript
С учётом регистра: Используйте названия языков в нижнем регистре
По умолчанию: Пустая строка (без фильтрации) — возвращает результаты по всем языкам
Поддерживаемое покрытие: Языковые фильтры работают по всем 279+ поддерживаемым языков и текстовых технологий. Полный список — на странице совместимости.

«Найди мидлвар аутентификации только в файлах Python»
«Найди подключения к базе данных в TypeScript»

Справочник API сгенерирован из исходного кода 22 июля 2026 г..

Основные инструменты поиска#

intelligent_searchСтабильно

Начните здесь с любого вопроса о кодовой базе. Задайте вопрос на естественном языке (например, «как работает аутентификация?» или «где обрабатывается биллинг?»), и он автоматически направится в семантический, символьный, структурный поиск или поиск зависимостей по всему индексированному репозиторию. Для исследования и планирования используйте этот инструмент вместо агента Explore и Grep/Glob: он сразу ищет во всём репозитории, а не просматривает файлы по одному.

Параметры:

queryОбязательный

Тип: str
Описание: Поисковый запрос

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

modeНеобязательный

Тип: Literal[auto, hybrid, semantic, text, structural, ast, graph]
По умолчанию: auto
Описание: Режим поиска

limitНеобязательный

Тип: int
По умолчанию: 10
Описание: Максимальное количество результатов в этом ранжированном окне top-K

language_filterНеобязательный

Тип: str
Описание: Фильтр по языку

path_filterНеобязательный

Тип: str
Описание: Фильтровать по префиксу пути к файлу

boost_by_importanceНеобязательный

Тип: bool
По умолчанию
Описание: Опционально: переранжирование по центральности с использованием графовых метрик на уровне символа (is_articulation_point, bridge_count, k_core, centrality и т.д.). По умолчанию выключено для безопасного для агентов ранжирования (глобальные хабы могут заглушить релевантные попадания в реализации); включайте для архитектурных обзоров. Применяется ко всем 4 модальностям, если каждый результат содержит привязку к символу.

branchНеобязательный

Тип: str
Описание: Переопределение ветки

qualityНеобязательный

Тип: Literal[quick, balanced, thorough]
По умолчанию: balanced
Описание: Качество поиска

include_contentНеобязательный

Тип: bool
По умолчанию: true
Описание: Включить содержимое в результаты

explain_routingНеобязательный

Тип: bool
По умолчанию
Описание: Включить объяснение решения о маршрутизации

importance_weightНеобязательный

Тип: float
По умолчанию: 0.3
Описание: Вес усиления по важности (0=нет, 1=полное)

orphansНеобязательный

Тип: bool
По умолчанию
Описание: Возвращать символы без входящих ссылок (потенциально мёртвый код). Полезно для чистки кода, но может включать декораторы, вложенные функции, точки входа CLI.

include_community_contextНеобязательный

Тип: bool
По умолчанию
Описание: Включить связанные символы из того же сообщества кода для более широкого контекста. Полезно при изучении того, как работает функциональность или модуль.

community_depthНеобязательный

Тип: int
По умолчанию: 1
Описание: Глубина расширения контекста сообщества

graph_viewНеобязательный

Тип: Literal[dependency, type, data_flow, control_flow]
По умолчанию: dependency
Описание: Представление графа для метрик

seed_symbol_idsНеобязательный

Тип: list[str]
Описание: Tier-1 начальные числа задач: идентификаторы символов, имеющие решающее значение для текущей задачи. Если установлено, объединенные попадания переранжируются по степени близости к затуханию глубины Approach A (точное совпадение начального числа + скачки границ графа). Аддитив — опустить для глобального рейтинга.

seed_file_pathsНеобязательный

Тип: list[str]
Описание: Tier-1 Начальные значения задач: индексированные пути к файлам, которые агент открыл или только что отредактировал. Если установлено, объединенные попадания переранжируются по близости пути с затуханием глубины 1/(1+d) (тот же файл → тот же каталог → ближайшие пакеты). Аддитив — опустить для глобального рейтинга.

Параметр	Тип	Обязательный	По умолчанию	Описание
`query`	`str`	Да	-	Поисковый запрос
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`mode`	`Literal[auto, hybrid, semantic, text, structural, ast, graph]`	Нет	`auto`	Режим поиска
`limit`	`int`	Нет	`10`	Максимальное количество результатов в этом ранжированном окне top-K
`language_filter`	`str`	Нет	-	Фильтр по языку
`path_filter`	`str`	Нет	-	Фильтровать по префиксу пути к файлу
`boost_by_importance`	`bool`	Нет		Опционально: переранжирование по центральности с использованием графовых метрик на уровне символа (is_articulation_point, bridge_count, k_core, centrality и т.д.). По умолчанию выключено для безопасного для агентов ранжирования (глобальные хабы могут заглушить релевантные попадания в реализации); включайте для архитектурных обзоров. Применяется ко всем 4 модальностям, если каждый результат содержит привязку к символу.
`branch`	`str`	Нет	-	Переопределение ветки
`quality`	`Literal[quick, balanced, thorough]`	Нет	`balanced`	Качество поиска
`include_content`	`bool`	Нет	`true`	Включить содержимое в результаты
`explain_routing`	`bool`	Нет		Включить объяснение решения о маршрутизации
`importance_weight`	`float`	Нет	`0.3`	Вес усиления по важности (0=нет, 1=полное)
`orphans`	`bool`	Нет		Возвращать символы без входящих ссылок (потенциально мёртвый код). Полезно для чистки кода, но может включать декораторы, вложенные функции, точки входа CLI.
`include_community_context`	`bool`	Нет		Включить связанные символы из того же сообщества кода для более широкого контекста. Полезно при изучении того, как работает функциональность или модуль.
`community_depth`	`int`	Нет	`1`	Глубина расширения контекста сообщества
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Нет	`dependency`	Представление графа для метрик
`seed_symbol_ids`	`list[str]`	Нет	-	Tier-1 начальные числа задач: идентификаторы символов, имеющие решающее значение для текущей задачи. Если установлено, объединенные попадания переранжируются по степени близости к затуханию глубины Approach A (точное совпадение начального числа + скачки границ графа). Аддитив — опустить для глобального рейтинга.
`seed_file_paths`	`list[str]`	Нет	-	Tier-1 Начальные значения задач: индексированные пути к файлам, которые агент открыл или только что отредактировал. Если установлено, объединенные попадания переранжируются по близости пути с затуханием глубины 1/(1+d) (тот же файл → тот же каталог → ближайшие пакеты). Аддитив — опустить для глобального рейтинга.

Лучше всего подходит для:

Исследование по всему индексу или с нуля, когда неясно, какой инструмент выбрать
Мультимодальное объединённое ранжирование по семантике, тексту, структуре и графу

Не рекомендуется для:

Известное имя символа — используйте find_symbol напрямую
Известный путь на диске — сначала используйте локальный Read/Grep

semantic_searchСтабильно

Ищет код по смыслу, а не по точному тексту. Используйте для концептуальных запросов вроде «логика повторных попыток» или «процесс регистрации пользователя», когда ключевое слово или имя символа неизвестно. Возвращает наиболее подходящие фрагменты кода, ранжированные по важности. Для концептуального поиска предпочтительнее Grep.

Параметры:

queryОбязательный

Тип: str
Описание: Поисковый запрос (концептуальный, основанный на смысле)

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

limitНеобязательный

Тип: int
По умолчанию: 5
Описание: Максимальное количество результатов в этом ранжированном окне top-K

similarity_thresholdНеобязательный

Тип: float
По умолчанию: 0.6
Описание: Минимальный порог сходства

language_filterНеобязательный

Тип: str
Описание: Ограничить результаты файлами, определёнными как этот язык программирования

path_filterНеобязательный

Тип: str
Описание: Фильтровать по префиксу пути к файлу

boost_by_importanceНеобязательный

Тип: bool
По умолчанию
Описание: Опционально: переранжирование по центральности PageRank (по умолчанию выключено для безопасного для агентов ранжирования; включайте для архитектурных обзоров)

branchНеобязательный

Тип: str
Описание: Переопределение ветки (по умолчанию: параметр repository или main)

include_contentНеобязательный

Тип: bool
По умолчанию: true
Описание: Включить содержимое фрагмента в результаты

graph_viewНеобязательный

Тип: Literal[dependency, type, data_flow, control_flow]
По умолчанию: dependency
Описание: Представление графа для метрик

Параметр	Тип	Обязательный	По умолчанию	Описание
`query`	`str`	Да	-	Поисковый запрос (концептуальный, основанный на смысле)
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`limit`	`int`	Нет	`5`	Максимальное количество результатов в этом ранжированном окне top-K
`similarity_threshold`	`float`	Нет	`0.6`	Минимальный порог сходства
`language_filter`	`str`	Нет	-	Ограничить результаты файлами, определёнными как этот язык программирования
`path_filter`	`str`	Нет	-	Фильтровать по префиксу пути к файлу
`boost_by_importance`	`bool`	Нет		Опционально: переранжирование по центральности PageRank (по умолчанию выключено для безопасного для агентов ранжирования; включайте для архитектурных обзоров)
`branch`	`str`	Нет	-	Переопределение ветки (по умолчанию: параметр repository или main)
`include_content`	`bool`	Нет	`true`	Включить содержимое фрагмента в результаты
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Нет	`dependency`	Представление графа для метрик

Лучше всего подходит для:

Концептуальные запросы ("how does auth work?", "caching strategy")
Поиск похожего кода между пакетами

Не рекомендуется для:

Известное имя символа — вместо этого используйте find_symbol
Точные строки или сообщения об ошибках — используйте text_pattern_search

text_pattern_searchСтабильно

Ищет в индексированном содержимом. Режимы exact и regex просматривают полный корпус файлов/blobs; режим fuzzy content — ограниченный корпус семантических фрагментов. Области файлов и символов поддерживают только fuzzy. Для узкого каталога, уже имеющегося на диске, используйте локальный Grep.

Параметры:

queryОбязательный

Тип: str
Описание: Текстовый паттерн

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

modeНеобязательный

Тип: Literal[fuzzy, exact, regex]
По умолчанию: exact
Описание: Режим поиска

search_scopeНеобязательный

Тип: Literal[content, symbols, files]
По умолчанию: content
Описание: Что искать

limitНеобязательный

Тип: int
По умолчанию: 5
Описание: Максимальное количество результатов, возвращаемых на этой странице

offsetНеобязательный

Тип: int
Описание: Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.

cursorНеобязательный

Тип: str
Описание: Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.

language_filterНеобязательный

Тип: str
Описание: Фильтр по языку

path_filterНеобязательный

Тип: str
Описание: Фильтровать по префиксу пути к файлу

case_sensitiveНеобязательный

Тип: bool
По умолчанию
Описание: С учётом регистра

branchНеобязательный

Тип: str
Описание: Переопределение ветки

fuzzy_algorithmНеобязательный

Тип: Literal[hybrid, trigram, levenshtein]
По умолчанию: hybrid
Описание: Алгоритм нечёткого сопоставления

thresholdНеобязательный

Тип: float
По умолчанию: 0.05
Описание: Минимальный порог сходства для нечёткого поиска

semantic_fallbackНеобязательный

Тип: bool
По умолчанию
Описание: При отсутствии результатов перейти к семантическому поиску

Параметр	Тип	Обязательный	По умолчанию	Описание
`query`	`str`	Да	-	Текстовый паттерн
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`mode`	`Literal[fuzzy, exact, regex]`	Нет	`exact`	Режим поиска
`search_scope`	`Literal[content, symbols, files]`	Нет	`content`	Что искать
`limit`	`int`	Нет	`5`	Максимальное количество результатов, возвращаемых на этой странице
`offset`	`int`	Нет	-	Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
`cursor`	`str`	Нет	-	Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.
`language_filter`	`str`	Нет	-	Фильтр по языку
`path_filter`	`str`	Нет	-	Фильтровать по префиксу пути к файлу
`case_sensitive`	`bool`	Нет		С учётом регистра
`branch`	`str`	Нет	-	Переопределение ветки
`fuzzy_algorithm`	`Literal[hybrid, trigram, levenshtein]`	Нет	`hybrid`	Алгоритм нечёткого сопоставления
`threshold`	`float`	Нет	`0.05`	Минимальный порог сходства для нечёткого поиска
`semantic_fallback`	`bool`	Нет		При отсутствии результатов перейти к семантическому поиску

Лучше всего подходит для:

Точные строки, сообщения об ошибках и регулярные выражения
Нечёткое триграммное сопоставление для почти совпадающего текста

Не рекомендуется для:

Известный путь на диске — предпочтите локальный Grep
Концептуальные запросы — используйте semantic_search

Структурные инструменты и инструменты работы с графом#

structural_searchСтабильно

Предпочитайте preset=functions|classes|methods|imports|variables (или свободный pattern=). Ищите код по форме AST (не по тексту). Фильтры среднего уровня: name_pattern, node_type, decorator, parent_child. Path/ltree/call-фильтры относятся к продвинутым — установите advanced=true, когда используете их осознанно; плоские advanced-ключи по-прежнему поддерживаются для обратной совместимости. Укажите хотя бы один структурный селектор.

Параметры:

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

presetНеобязательный

Тип: Literal[functions, classes, methods, imports, variables]
Описание: Предпочтительный структурный селектор. Разворачивается в кросс-языковые типы узлов AST — functions (определения функций/стрелочных функций/методов на разных языках); classes (определения классов/структур/impl); methods (определения методов (и function_definition для языков без узла метода)); imports (операторы import/use/include); variables (объявления переменных variable/let/const/static). Предпочтительнее произвольных pattern/node_type для запросов в стиле обзора.

patternНеобязательный

Тип: str
Описание: Произвольный шаблон, когда пресетов недостаточно (автоопределение: 'def foo(' → node_type + name_pattern). Для обзорных запросов предпочитайте preset=.

name_patternНеобязательный

Тип: str
Описание: Шаблон имени символа (шаблон оболочки, ограниченное POSIX-регулярное выражение или нечёткий текст; максимум 256 символов)

node_typeНеобязательный

Тип: str
Описание: Тип узла AST (function_definition, class_definition и т.д.) — для типовых форм предпочитайте preset=

decoratorНеобязательный

Тип: str
Описание: Фильтр по имени декоратора

base_classНеобязательный

Тип: str
Описание: Фильтр по имени базового класса (найти классы, наследующие от него)

language_filterНеобязательный

Тип: str
Описание: Фильтр по языку

limitНеобязательный

Тип: int
По умолчанию: 20
Описание: Максимальное количество результатов, возвращаемых на этой странице

offsetНеобязательный

Тип: int
Описание: Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.

cursorНеобязательный

Тип: str
Описание: Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.

path_filterНеобязательный

Тип: str
Описание: Фильтровать по префиксу пути к файлу

branchНеобязательный

Тип: str
Описание: Переопределение ветки

query_typeНеобязательный

Тип: Literal[node_type, name_pattern, parent_child]
Описание: Явный тип запроса

parent_typeНеобязательный

Тип: str
Описание: Фильтр типа родительского узла AST

relationshipНеобязательный

Тип: Literal[parent, ancestor]
По умолчанию: parent
Описание: Для запросов parent_child: только непосредственный родитель или любой предок (используйте ancestor для методов класса, вложенных в тело/блок класса)

has_modifierНеобязательный

Тип: str
Описание: Фильтровать по модификатору (export, async, static и т. д.)

advancedНеобязательный

Тип: bool
По умолчанию
Описание: Установите true при намеренном использовании расширенных фильтров путей, ltree или вызовов (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). По умолчанию false сохраняет интерфейс агента ориентированным на предустановки. Расширенные ключи в плоском формате по-прежнему работают для обратной совместимости с предупреждением о метаданных.

callee_textНеобязательный

Тип: str
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Фильтр по тексту callee вызова выражения. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

callee_nameНеобязательный

Тип: str
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Фильтр по имени callee вызова выражения. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

field_roleНеобязательный

Тип: str
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Фильтр по роли поля AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

ltree_ancestorНеобязательный

Тип: str
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Фильтр по пути предка ltree AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

ltree_descendantНеобязательный

Тип: str
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Фильтр по пути потомка ltree AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

definition_nameНеобязательный

Тип: str
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Фильтр по имени определения. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

min_depthНеобязательный

Тип: int
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Минимальная глубина AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

max_depthНеобязательный

Тип: int
Описание: Продвинутый параметр — предпочитайте preset=functions|classes|methods|imports|variables. Максимальная глубина AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

Параметр	Тип	Обязательный	По умолчанию	Описание
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`preset`	`Literal[functions, classes, methods, imports, variables]`	Нет	-	Предпочтительный структурный селектор. Разворачивается в кросс-языковые типы узлов AST — functions (определения функций/стрелочных функций/методов на разных языках); classes (определения классов/структур/impl); methods (определения методов (и function_definition для языков без узла метода)); imports (операторы import/use/include); variables (объявления переменных variable/let/const/static). Предпочтительнее произвольных pattern/node_type для запросов в стиле обзора.
`pattern`	`str`	Нет	-	Произвольный шаблон, когда пресетов недостаточно (автоопределение: 'def foo(' → node_type + name_pattern). Для обзорных запросов предпочитайте preset=.
`name_pattern`	`str`	Нет	-	Шаблон имени символа (шаблон оболочки, ограниченное POSIX-регулярное выражение или нечёткий текст; максимум 256 символов)
`node_type`	`str`	Нет	-	Тип узла AST (function_definition, class_definition и т.д.) — для типовых форм предпочитайте preset=
`decorator`	`str`	Нет	-	Фильтр по имени декоратора
`base_class`	`str`	Нет	-	Фильтр по имени базового класса (найти классы, наследующие от него)
`language_filter`	`str`	Нет	-	Фильтр по языку
`limit`	`int`	Нет	`20`	Максимальное количество результатов, возвращаемых на этой странице
`offset`	`int`	Нет	-	Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
`cursor`	`str`	Нет	-	Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.
`path_filter`	`str`	Нет	-	Фильтровать по префиксу пути к файлу
`branch`	`str`	Нет	-	Переопределение ветки
`query_type`	`Literal[node_type, name_pattern, parent_child]`	Нет	-	Явный тип запроса
`parent_type`	`str`	Нет	-	Фильтр типа родительского узла AST
`relationship`	`Literal[parent, ancestor]`	Нет	`parent`	Для запросов parent_child: только непосредственный родитель или любой предок (используйте ancestor для методов класса, вложенных в тело/блок класса)
`has_modifier`	`str`	Нет	-	Фильтровать по модификатору (export, async, static и т. д.)
`advanced`	`bool`	Нет		Установите true при намеренном использовании расширенных фильтров путей, ltree или вызовов (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). По умолчанию false сохраняет интерфейс агента ориентированным на предустановки. Расширенные ключи в плоском формате по-прежнему работают для обратной совместимости с предупреждением о метаданных.
`callee_text`	`str`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Фильтр по тексту callee вызова выражения. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.
`callee_name`	`str`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Фильтр по имени callee вызова выражения. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.
`field_role`	`str`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Фильтр по роли поля AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.
`ltree_ancestor`	`str`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Фильтр по пути предка ltree AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.
`ltree_descendant`	`str`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Фильтр по пути потомка ltree AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.
`definition_name`	`str`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Фильтр по имени определения. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.
`min_depth`	`int`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Минимальная глубина AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.
`max_depth`	`int`	Нет	-	Продвинутый параметр — предпочитайте preset=functions\|classes\|methods\|imports\|variables. Максимальная глубина AST. Установите advanced=true, если намеренно используете path/ltree/call-фильтры.

Лучше всего подходит для:

Структура на уровне AST: классы, декораторы, пресеты функций/методов
Поиск кода по форме, а не по тексту

Не рекомендуется для:

Произвольный текст или концептуальные запросы — используйте semantic_search или intelligent_search

dependency_searchСтабильно

Основная поверхность для анализа радиуса воздействия / графа. Отвечает на вопросы «что вызывает это?» / «что использует это?» через реальный граф вызовов/импортов. Для оценки влияния перед изменением: analysis_type="dependents" или analysis_type="impact" (входящие, по умолчанию shallow для impact), include_metrics=false по умолчанию (включайте для centrality + refactor_risk). Анализ влияния PR/диффа (P1-8): передайте changed_paths и/или patch (unified diff) — символы разрешаются по каждому пути, возвращается компактная неглубокая (shallow) полезная нагрузка входящих зависимых без необходимости указывать имя символа. После редактирования установите verify_after_edit=true с targets и/или changed_paths для компактной многокорневой повторной проверки затронутых символов. Также поддерживает dependencies, centrality и orphans. analyze_dependencies — это тонкий алиас для пути impact — для новых агентов предпочитайте этот инструмент.

Параметры:

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

queryНеобязательный

Тип: str
Описание: Имя символа или поисковый термин

targetНеобязательный

Тип: str
Описание: Имя символа (псевдоним query)

changed_pathsНеобязательный

Тип: list[str]
Описание: Относительные пути к репозиторию для воздействия PR/diff (по умолчанию) или, с помощью verify_after_edit=true, проверки корней после редактирования. PR/diff: разрешает символы для каждого пути и обходит мелкие входящие зависимости; можно комбинировать с patch=. Проверка: разрешает до 5 символов на путь в качестве корней проверки (ограничено ниже в режиме проверки). Для воздействия PR/diff не требуется query/target.

patchНеобязательный

Тип: str
Описание: Влияние PR/diff: унифицированный текст патча diff/git. Пути анализируются из заголовков diff --git/---/+++; такая же компактная траектория удара, как у changed_paths.

analysis_typeНеобязательный

Тип: Literal[centrality, dependencies, dependents, impact, orphans]
По умолчанию: dependencies
Описание: Режим анализа. impact = радиус воздействия (входящие зависимые; неглубокая (shallow) глубина, если depth не указана). dependents тоже отвечает на impact. Если задан changed_paths или patch, анализ принудительно переключается на режим влияния PR/диффа. centrality/orphans не требуют target.

depthНеобязательный

Тип: Literal[shallow, balanced, deep]
По умолчанию: balanced
Описание: Глубина обхода. Для analysis_type=impact и анализа влияния PR/диффа эффективное значение по умолчанию — shallow, если вы явно не укажете depth.

limitНеобязательный

Тип: int
По умолчанию: 20
Описание: Максимальное количество результатов, возвращаемых на этой странице

offsetНеобязательный

Тип: int
Описание: Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.

cursorНеобязательный

Тип: str
Описание: Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.

path_filterНеобязательный

Тип: str
Описание: Ограничивает разрешение целевого символа по префиксу пути к файлу; возвращённые связи графа могут выходить за пределы этого пути

language_filterНеобязательный

Тип: str
Описание: Фильтрует разрешение цели и результаты обзора по языку

directionНеобязательный

Тип: Literal[outgoing, incoming, both]
Описание: Направление обхода (переопределяет вывод из analysis_type)

relationship_typesНеобязательный

Тип: list[str]
Описание: Фильтр типов рёбер (CALL, IMPORT, INHERITS_FROM и т.д.). Непустой список переопределяет значения по умолчанию graph_view.

exclude_test_pathsНеобязательный

Тип: bool
По умолчанию: true
Описание: По умолчанию true: исключает пути тестов, фикстур, вендорного кода и примеров из результатов обхода и centrality. Установите false, чтобы включить их. Анализ orphan всегда применяет собственные, более строгие исключения шума.

exclude_generated_pathsНеобязательный

Тип: bool
По умолчанию
Описание: Исключить из результатов обхода сгенерированные объявления, а также пути сборки, покрытия, кэша, исходной карты и минимизированных артефактов.

include_module_symbolsНеобязательный

Тип: bool
По умолчанию
Описание: По умолчанию false исключает ребра графа, если from_name или to_name является синтетическим символом __module__ (шум на уровне модуля). Установите true, чтобы включать ребра уровня модуля в результаты для отношений зависимости и зависимости.

branchНеобязательный

Тип: str
Описание: Переопределение ветки

per_hop_limitНеобязательный

Тип: int
Описание: Максимальное количество связей на один переход (1-300)

include_metricsНеобязательный

Тип: bool
По умолчанию
Описание: Опциональные графовые метрики в строках результата (сжаты вместе с refactor_risk). Метрики также запрашиваются внутренне, когда min_centrality>0, но не возвращаются, если это не установлено в true.

metrics_detailНеобязательный

Тип: Literal[summary, full]
По умолчанию: summary
Описание: Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.

include_edge_metadataНеобязательный

Тип: bool
По умолчанию
Описание: Включите метаданные и веса необработанных краев (большие). Компактные ударные нагрузки исключают это.

symbol_typesНеобязательный

Тип: list[str]
Описание: Фильтрует возвращаемые символы по типу (function, class, method и т.д.)

exact_matchНеобязательный

Тип: bool
По умолчанию
Описание: Требовать точное совпадение имени символа (без учёта регистра). Отключает нечёткое сопоставление

find_similar_patternsНеобязательный

Тип: bool
По умолчанию
Описание: Найти похожие шаблоны использования

min_centralityНеобязательный

Тип: float
По умолчанию: 0
Описание: Минимальный показатель PageRank. Метрики запрашиваются внутренне для фильтрации; graph_metrics возвращаются только при include_metrics=true.

graph_viewНеобязательный

Тип: Literal[dependency, type, data_flow, control_flow]
По умолчанию: dependency
Описание: Представление графа, используемое для значений по умолчанию при обходе связей, метрик и ранжирования по centrality; анализ orphan рассчитывается по всем представлениям

verify_after_editНеобязательный

Тип: bool
По умолчанию
Описание: P2-7 Режим проверки после редактирования: повторный запрос индексированного графа воздействия для недавно отредактированных символов в одном компактном многокорневом ответе. Требуется targets и/или changed_paths (или target/query). По умолчанию используются мелкие входящие иждивенцы; результаты отражают индексированный график (может отставать от оперативного редактирования). Если это правда, имеет приоритет над воздействием PR/diff на тот же changed_paths.

targetsНеобязательный

Тип: list[str]
Описание: Когда verify_after_edit=true: имена символов для повторной проверки (вызывающие абоненты/иждивенцы). Объединяется с target/query, если оба указаны.

Параметр	Тип	Обязательный	По умолчанию	Описание
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`query`	`str`	Нет	-	Имя символа или поисковый термин
`target`	`str`	Нет	-	Имя символа (псевдоним query)
`changed_paths`	`list[str]`	Нет	-	Относительные пути к репозиторию для воздействия PR/diff (по умолчанию) или, с помощью verify_after_edit=true, проверки корней после редактирования. PR/diff: разрешает символы для каждого пути и обходит мелкие входящие зависимости; можно комбинировать с patch=. Проверка: разрешает до 5 символов на путь в качестве корней проверки (ограничено ниже в режиме проверки). Для воздействия PR/diff не требуется query/target.
`patch`	`str`	Нет	-	Влияние PR/diff: унифицированный текст патча diff/git. Пути анализируются из заголовков diff --git/---/+++; такая же компактная траектория удара, как у changed_paths.
`analysis_type`	`Literal[centrality, dependencies, dependents, impact, orphans]`	Нет	`dependencies`	Режим анализа. impact = радиус воздействия (входящие зависимые; неглубокая (shallow) глубина, если depth не указана). dependents тоже отвечает на impact. Если задан changed_paths или patch, анализ принудительно переключается на режим влияния PR/диффа. centrality/orphans не требуют target.
`depth`	`Literal[shallow, balanced, deep]`	Нет	`balanced`	Глубина обхода. Для analysis_type=impact и анализа влияния PR/диффа эффективное значение по умолчанию — shallow, если вы явно не укажете depth.
`limit`	`int`	Нет	`20`	Максимальное количество результатов, возвращаемых на этой странице
`offset`	`int`	Нет	-	Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
`cursor`	`str`	Нет	-	Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.
`path_filter`	`str`	Нет	-	Ограничивает разрешение целевого символа по префиксу пути к файлу; возвращённые связи графа могут выходить за пределы этого пути
`language_filter`	`str`	Нет	-	Фильтрует разрешение цели и результаты обзора по языку
`direction`	`Literal[outgoing, incoming, both]`	Нет	-	Направление обхода (переопределяет вывод из analysis_type)
`relationship_types`	`list[str]`	Нет	-	Фильтр типов рёбер (CALL, IMPORT, INHERITS_FROM и т.д.). Непустой список переопределяет значения по умолчанию graph_view.
`exclude_test_paths`	`bool`	Нет	`true`	По умолчанию true: исключает пути тестов, фикстур, вендорного кода и примеров из результатов обхода и centrality. Установите false, чтобы включить их. Анализ orphan всегда применяет собственные, более строгие исключения шума.
`exclude_generated_paths`	`bool`	Нет		Исключить из результатов обхода сгенерированные объявления, а также пути сборки, покрытия, кэша, исходной карты и минимизированных артефактов.
`include_module_symbols`	`bool`	Нет		По умолчанию false исключает ребра графа, если from_name или to_name является синтетическим символом __module__ (шум на уровне модуля). Установите true, чтобы включать ребра уровня модуля в результаты для отношений зависимости и зависимости.
`branch`	`str`	Нет	-	Переопределение ветки
`per_hop_limit`	`int`	Нет	-	Максимальное количество связей на один переход (1-300)
`include_metrics`	`bool`	Нет		Опциональные графовые метрики в строках результата (сжаты вместе с refactor_risk). Метрики также запрашиваются внутренне, когда min_centrality>0, но не возвращаются, если это не установлено в true.
`metrics_detail`	`Literal[summary, full]`	Нет	`summary`	Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.
`include_edge_metadata`	`bool`	Нет		Включите метаданные и веса необработанных краев (большие). Компактные ударные нагрузки исключают это.
`symbol_types`	`list[str]`	Нет	-	Фильтрует возвращаемые символы по типу (function, class, method и т.д.)
`exact_match`	`bool`	Нет		Требовать точное совпадение имени символа (без учёта регистра). Отключает нечёткое сопоставление
`find_similar_patterns`	`bool`	Нет		Найти похожие шаблоны использования
`min_centrality`	`float`	Нет	`0`	Минимальный показатель PageRank. Метрики запрашиваются внутренне для фильтрации; graph_metrics возвращаются только при include_metrics=true.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Нет	`dependency`	Представление графа, используемое для значений по умолчанию при обходе связей, метрик и ранжирования по centrality; анализ orphan рассчитывается по всем представлениям
`verify_after_edit`	`bool`	Нет		P2-7 Режим проверки после редактирования: повторный запрос индексированного графа воздействия для недавно отредактированных символов в одном компактном многокорневом ответе. Требуется targets и/или changed_paths (или target/query). По умолчанию используются мелкие входящие иждивенцы; результаты отражают индексированный график (может отставать от оперативного редактирования). Если это правда, имеет приоритет над воздействием PR/diff на тот же changed_paths.
`targets`	`list[str]`	Нет	-	Когда verify_after_edit=true: имена символов для повторной проверки (вызывающие абоненты/иждивенцы). Объединяется с target/query, если оба указаны.

Лучше всего подходит для:

Анализ радиуса воздействия перед изменением общего символа
Влияние PR/диффа через changed_paths или patch
Проверка после правки через verify_after_edit

Не рекомендуется для:

Простой поиск текста или символов — используйте text_pattern_search или find_symbol

Инструменты анализа кода#

find_symbolСтабильно

Переходит к определению и местам использования функции, класса или переменной. Используйте, когда известно имя (например, «getCurrentUser»): быстрее и точнее Grep и охватывает весь индексированный репозиторий. Может также вернуть ссылки и метрики важности.

Параметры:

symbol_nameНеобязательный

Тип: str
Описание: Имя символа для поиска (необязательно — не указывайте, чтобы просматривать по метрикам)

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

scopeНеобязательный

Тип: Literal[definitions, references, both]
По умолчанию: both
Описание: Область: definitions|references|both

limitНеобязательный

Тип: int
По умолчанию: 15
Описание: Максимальное количество результатов, возвращаемых на этой странице

offsetНеобязательный

Тип: int
Описание: Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.

cursorНеобязательный

Тип: str
Описание: Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.

find_similarНеобязательный

Тип: bool
По умолчанию
Описание: Найти похожие символы

include_metricsНеобязательный

Тип: bool
По умолчанию
Описание: Включить метрики центральности

metrics_detailНеобязательный

Тип: Literal[summary, full]
По умолчанию: summary
Описание: Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.

path_filterНеобязательный

Тип: str
Описание: Фильтровать по префиксу пути к файлу

branchНеобязательный

Тип: str
Описание: Переопределение ветки

symbol_typeНеобязательный

Тип: Literal[function, class, variable, method, constant, module, interface, type]
Описание: Фильтр по типу символа

high_impactНеобязательный

Тип: bool
По умолчанию
Описание: Просмотр архитектурно значимых символов (без указания symbol_name). Режим по умолчанию — популярность (верхний дециль PageRank за вычетом служебных мегахабов). Установите high_impact_mode=risk для точек сочленения/мостовых вершин (точек сочленения и мостовых вершин-разделителей).

high_impact_modeНеобязательный

Тип: Literal[popularity, risk]
По умолчанию: popularity
Описание: Когда high_impact=true: популярность = верхний дециль PageRank минус служебные мега-концентраторы/модули; риск = точки сочленения, ранжированные по SMV bridge_count, затем k_core (риск структурного рефакторинга, а не популярность хаба)

in_cycleНеобязательный

Тип: bool
По умолчанию
Описание: Только в цикле

exclude_test_pathsНеобязательный

Тип: bool
По умолчанию: true
Описание: При просмотре по метрикам графика исключайте тесты, fixtures, сторонний код и примеры перед ранжированием. Поиск по именованному символу не изменяется.

Параметр	Тип	Обязательный	По умолчанию	Описание
`symbol_name`	`str`	Нет	-	Имя символа для поиска (необязательно — не указывайте, чтобы просматривать по метрикам)
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`scope`	`Literal[definitions, references, both]`	Нет	`both`	Область: definitions\|references\|both
`limit`	`int`	Нет	`15`	Максимальное количество результатов, возвращаемых на этой странице
`offset`	`int`	Нет	-	Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
`cursor`	`str`	Нет	-	Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.
`find_similar`	`bool`	Нет		Найти похожие символы
`include_metrics`	`bool`	Нет		Включить метрики центральности
`metrics_detail`	`Literal[summary, full]`	Нет	`summary`	Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.
`path_filter`	`str`	Нет	-	Фильтровать по префиксу пути к файлу
`branch`	`str`	Нет	-	Переопределение ветки
`symbol_type`	`Literal[function, class, variable, method, constant, module, interface, type]`	Нет	-	Фильтр по типу символа
`high_impact`	`bool`	Нет		Просмотр архитектурно значимых символов (без указания symbol_name). Режим по умолчанию — популярность (верхний дециль PageRank за вычетом служебных мегахабов). Установите high_impact_mode=risk для точек сочленения/мостовых вершин (точек сочленения и мостовых вершин-разделителей).
`high_impact_mode`	`Literal[popularity, risk]`	Нет	`popularity`	Когда high_impact=true: популярность = верхний дециль PageRank минус служебные мега-концентраторы/модули; риск = точки сочленения, ранжированные по SMV bridge_count, затем k_core (риск структурного рефакторинга, а не популярность хаба)
`in_cycle`	`bool`	Нет		Только в цикле
`exclude_test_paths`	`bool`	Нет	`true`	При просмотре по метрикам графика исключайте тесты, fixtures, сторонний код и примеры перед ранжированием. Поиск по именованному символу не изменяется.

Лучше всего подходит для:

Фиксация определения, ссылок и метрик графа известного символа
Просмотр по centrality, high_impact или in_cycle, когда symbol_name опущен

Не рекомендуется для:

Концептуальные запросы или неизвестные области — используйте intelligent_search или semantic_search

analyze_dependenciesСтабильно

Алиас для радиуса воздействия через dependency_search (dependents/incoming). Для новых агентов предпочитайте dependency_search с analysis_type="dependents" или "impact". Сохраняет устаревшую форму многошагового ответа impact (graph, connection_summary, опциональные метрики с refactor_risk). Используйте graph_view, чтобы задать область семейства связей: dependency (по умолчанию), type, data_flow, control_flow.

Параметры:

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

targetОбязательный

Тип: str
Описание: Имя символа для анализа

depthНеобязательный

Тип: Literal[shallow, balanced, deep]
По умолчанию: balanced
Описание: Глубина анализа (поддерживает псевдонимы: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)

limitНеобязательный

Тип: int
По умолчанию: 10
Описание: Максимальное количество результатов, возвращаемых на этой странице

offsetНеобязательный

Тип: int
Описание: Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.

cursorНеобязательный

Тип: str
Описание: Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.

directionНеобязательный

Тип: Literal[incoming, outgoing, both]
По умолчанию: incoming
Описание: Направление обхода: 'outgoing' — от чего зависит этот символ (его зависимости), 'incoming' — что зависит от этого символа (его зависимые), 'both' — полный контекст. Используйте 'incoming', чтобы найти всех вызывающих/пользователей символа.

relationship_typesНеобязательный

Тип: list[str]
Описание: Фильтровать по типам рёбер (CALL, IMPORT, INHERITS_FROM и т. д.). Если параметр задан, он всегда переопределяет значение по умолчанию, полученное из graph_view ниже.

graph_viewНеобязательный

Тип: Literal[dependency, type, data_flow, control_flow]
По умолчанию: dependency
Описание: Представление графа: при include_metrics=true определяет и типы рёбер обхода по умолчанию, и представление, метрики которого используются. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (по умолчанию), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Применяется как значение relationship_types по умолчанию, только если relationship_types не задан явно. Имя соответствует существующему параметру graph_view в dependency_search для единообразия инструментов.

path_filterНеобязательный

Тип: str
Описание: Ограничивает разрешение целевого символа по префиксу пути к файлу; возвращённые связи графа могут выходить за пределы этого пути

language_filterНеобязательный

Тип: str
Описание: Ограничить результаты одним языком

branchНеобязательный

Тип: str
Описание: Переопределение ветки

per_hop_limitНеобязательный

Тип: int
Описание: Максимальное количество связей на один переход (1-300)

include_metricsНеобязательный

Тип: bool
По умолчанию
Описание: Включить в результаты метрики графа, дополнив каждую производным блоком refactor_risk ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). Риск равен "low", если символ не является точкой сочленения в выбранном представлении, "medium", если такая точка соединяет мало рёбер, и "high", если много (эвристический, эмпирически не проверенный порог). Блок не добавляется, если для символа/представления нет строки метрик.

metrics_detailНеобязательный

Тип: Literal[summary, full]
По умолчанию: summary
Описание: Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.

include_edge_metadataНеобязательный

Тип: bool
По умолчанию
Описание: Включите метаданные и веса необработанных краев. По умолчанию отключено, поскольку метаданные экстрактора могут быть большими; О покрытии обогащения сообщается, если оно включено.

exclude_test_pathsНеобязательный

Тип: bool
По умолчанию: true
Описание: По умолчанию true: исключить пути тестов, приспособлений, поставщиков и примеров из возвращаемых ребер графа. Установите false, чтобы включить их.

include_module_symbolsНеобязательный

Тип: bool
По умолчанию
Описание: По умолчанию false исключает ребра графа, если from_name или to_name является синтетическим символом __module__. Установите true, чтобы включить ребра на уровне модуля.

Параметр	Тип	Обязательный	По умолчанию	Описание
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`target`	`str`	Да	-	Имя символа для анализа
`depth`	`Literal[shallow, balanced, deep]`	Нет	`balanced`	Глубина анализа (поддерживает псевдонимы: auto, shallow/quick=1, balanced/medium=2, deep/thorough=3)
`limit`	`int`	Нет	`10`	Максимальное количество результатов, возвращаемых на этой странице
`offset`	`int`	Нет	-	Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
`cursor`	`str`	Нет	-	Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и сохраняйте query и фильтры неизменными.
`direction`	`Literal[incoming, outgoing, both]`	Нет	`incoming`	Направление обхода: 'outgoing' — от чего зависит этот символ (его зависимости), 'incoming' — что зависит от этого символа (его зависимые), 'both' — полный контекст. Используйте 'incoming', чтобы найти всех вызывающих/пользователей символа.
`relationship_types`	`list[str]`	Нет	-	Фильтровать по типам рёбер (CALL, IMPORT, INHERITS_FROM и т. д.). Если параметр задан, он всегда переопределяет значение по умолчанию, полученное из graph_view ниже.
`graph_view`	`Literal[dependency, type, data_flow, control_flow]`	Нет	`dependency`	Представление графа: при include_metrics=true определяет и типы рёбер обхода по умолчанию, и представление, метрики которого используются. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (по умолчанию), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Применяется как значение relationship_types по умолчанию, только если relationship_types не задан явно. Имя соответствует существующему параметру graph_view в dependency_search для единообразия инструментов.
`path_filter`	`str`	Нет	-	Ограничивает разрешение целевого символа по префиксу пути к файлу; возвращённые связи графа могут выходить за пределы этого пути
`language_filter`	`str`	Нет	-	Ограничить результаты одним языком
`branch`	`str`	Нет	-	Переопределение ветки
`per_hop_limit`	`int`	Нет	-	Максимальное количество связей на один переход (1-300)
`include_metrics`	`bool`	Нет		Включить в результаты метрики графа, дополнив каждую производным блоком refactor_risk ({risk: "low"\|"medium"\|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). Риск равен "low", если символ не является точкой сочленения в выбранном представлении, "medium", если такая точка соединяет мало рёбер, и "high", если много (эвристический, эмпирически не проверенный порог). Блок не добавляется, если для символа/представления нет строки метрик.
`metrics_detail`	`Literal[summary, full]`	Нет	`summary`	Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.
`include_edge_metadata`	`bool`	Нет		Включите метаданные и веса необработанных краев. По умолчанию отключено, поскольку метаданные экстрактора могут быть большими; О покрытии обогащения сообщается, если оно включено.
`exclude_test_paths`	`bool`	Нет	`true`	По умолчанию true: исключить пути тестов, приспособлений, поставщиков и примеров из возвращаемых ребер графа. Установите false, чтобы включить их.
`include_module_symbols`	`bool`	Нет		По умолчанию false исключает ребра графа, если from_name или to_name является синтетическим символом __module__. Установите true, чтобы включить ребра на уровне модуля.

Лучше всего подходит для:

Устаревшие вызывающие стороны, уже завязанные на его форму ответа (graph, connection_summary)

Не рекомендуется для:

Новые агентные циклы — предпочтите dependency_search, который использует то же ядро обхода

get_task_contextСтабильно

Начинаете работу в незнакомой области? Опишите задачу (например, «добавить поддержку SSO», «исправить платёжный вебхук») и получите ограниченный по объёму набор релевантных файлов, кода, символов и зависимостей за один вызов. Файлы-сиды дают прямые индексированные данные, даже если в них не определены символы. Для получения дополнительных результатов продолжайте со специализированным инструментом поиска для соответствующего уровня.

Параметры:

task_descriptionОбязательный

Тип: str
Описание: Описание задачи

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

limitНеобязательный

Тип: int
По умолчанию: 15
Описание: Максимум результатов на слой

scopeНеобязательный

Тип: Literal[semantic, symbols, dependencies, all]
По умолчанию: all
Описание: Слои контекста для включения. Допустимо: 'semantic', 'symbols', 'dependencies', 'all'. По умолчанию: ['semantic', 'symbols', 'dependencies']

language_filterНеобязательный

Тип: str
Описание: Ограничить результаты файлами, определёнными как этот язык программирования

path_filterНеобязательный

Тип: str
Описание: Фильтровать по префиксу пути к файлу

branchНеобязательный

Тип: str
Описание: Переопределение ветки

include_related_contextНеобязательный

Тип: bool
По умолчанию
Описание: Включить связанный контекст из соседних символов

seed_symbol_idsНеобязательный

Тип: list[str]
Описание: Явные исходные точки уровня 1: ID символов, которые агент уже считает центральными для задачи (например, символы в открытых файлах). В слоях dependencies/related_context они ранжируются выше точек, полученных из ключевых слов. Параметр аддитивный — не указывайте его, чтобы сохранить текущее поведение только по ключевым словам.

seed_file_pathsНеобязательный

Тип: list[str]
Описание: Явные сиды уровня 1: индексированные пути файлов, которые агент открыл или только что отредактировал. Возвращает ограниченные прямые файловые данные и разрешает до 5 символов на файл для графового контекста, включая документацию и конфигурацию без символов. Аддитивно — опустите для поведения по умолчанию, основанного только на ключевых словах.

Параметр	Тип	Обязательный	По умолчанию	Описание
`task_description`	`str`	Да	-	Описание задачи
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`limit`	`int`	Нет	`15`	Максимум результатов на слой
`scope`	`Literal[semantic, symbols, dependencies, all]`	Нет	`all`	Слои контекста для включения. Допустимо: 'semantic', 'symbols', 'dependencies', 'all'. По умолчанию: ['semantic', 'symbols', 'dependencies']
`language_filter`	`str`	Нет	-	Ограничить результаты файлами, определёнными как этот язык программирования
`path_filter`	`str`	Нет	-	Фильтровать по префиксу пути к файлу
`branch`	`str`	Нет	-	Переопределение ветки
`include_related_context`	`bool`	Нет		Включить связанный контекст из соседних символов
`seed_symbol_ids`	`list[str]`	Нет	-	Явные исходные точки уровня 1: ID символов, которые агент уже считает центральными для задачи (например, символы в открытых файлах). В слоях dependencies/related_context они ранжируются выше точек, полученных из ключевых слов. Параметр аддитивный — не указывайте его, чтобы сохранить текущее поведение только по ключевым словам.
`seed_file_paths`	`list[str]`	Нет	-	Явные сиды уровня 1: индексированные пути файлов, которые агент открыл или только что отредактировал. Возвращает ограниченные прямые файловые данные и разрешает до 5 символов на файл для графового контекста, включая документацию и конфигурацию без символов. Аддитивно — опустите для поведения по умолчанию, основанного только на ключевых словах.

Лучше всего подходит для:

Контекст с учётом задачи, объединяющий начальные файлы со слоями семантики, символов и зависимостей

Не рекомендуется для:

Поиск одним инструментом, когда более специфичный инструмент уже отвечает на вопрос

get_fileСтабильно

Читает файл из индексированного репозитория по пути. Для файлов на диске предпочитайте локальный инструмент Read — используйте этот инструмент для межрепозиторных или удалённых запросов, когда файла нет в вашей рабочей копии. Поддерживает необязательный диапазон строк; продолжайте обрезанный по токенам ответ с metadata.next_line_start.

Параметры:

file_pathОбязательный

Тип: str
Описание: Путь к файлу относительно корня репозитория

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.

line_startНеобязательный

Тип: int
Описание: Начальная строка (нумерация с 1)

line_endНеобязательный

Тип: int
Описание: Конечная строка (нумерация с 1, включительно; должна быть не меньше line_start)

branchНеобязательный

Тип: str
Описание: Переопределение ветки

max_tokensНеобязательный

Тип: int
По умолчанию: 5000
Описание: Максимум токенов

include_metadataНеобязательный

Тип: bool
По умолчанию: true
Описание: Включить метаданные

Параметр	Тип	Обязательный	По умолчанию	Описание
`file_path`	`str`	Да	-	Путь к файлу относительно корня репозитория
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. В ответе указано, какой репозиторий использован.
`line_start`	`int`	Нет	-	Начальная строка (нумерация с 1)
`line_end`	`int`	Нет	-	Конечная строка (нумерация с 1, включительно; должна быть не меньше line_start)
`branch`	`str`	Нет	-	Переопределение ветки
`max_tokens`	`int`	Нет	`5000`	Максимум токенов
`include_metadata`	`bool`	Нет	`true`	Включить метаданные

Лучше всего подходит для:

Снимки удалённых или проиндексированных файлов (диапазоны строк, лимиты токенов)

Не рекомендуется для:

Путь, уже находящийся на локальном диске — используйте локальный инструмент Read

Системные и вспомогательные инструменты#

repository_contextСтабильно

Выводит список репозиториев, доступных вам для поиска, или получает идентификационную информацию об одном из них (namespace/branch, indexed_commit_sha / актуальность индекса). Вызовите с action:"list" один раз, чтобы узнать точный slug репозитория, который принимают инструменты поиска. (Если ваш ключ имеет доступ к единственному репозиторию, инструменты поиска используют его по умолчанию — это можно пропустить.) Счётчики file/blob/edge по всему пространству имён доступны опционально через include_statistics=true.

Параметры:

actionОбязательный

Тип: Literal[list, info]
Описание: Действие: перечислить доступные репозитории или получить сведения о репозитории

repositoryНеобязательный

Тип: str
Описание: Репозиторий в формате owner/repo или owner/repo:branch (обязателен для info)

branchНеобязательный

Тип: str
Описание: Переопределение ветки

patternНеобязательный

Тип: str
Описание: Шаблон фильтра

include_statisticsНеобязательный

Тип: bool
По умолчанию
Описание: Опционально: включает счётчики индексированных данных по всему пространству имён (file/blob/edge). По умолчанию false — идентификация репозитория не требует этого более медленного агрегата.

limitНеобязательный

Тип: int
По умолчанию: 20
Описание: Максимальное количество результатов, возвращаемых на этой странице

offsetНеобязательный

Тип: int
Описание: Устаревшее смещение совместимости. Предпочитайте cursor из pagination.next_cursor.

cursorНеобязательный

Тип: str
Описание: Непрозрачный cursor от pagination.next_cursor. Передайте его без изменений, оставив без изменений запрос и фильтры.

Параметр	Тип	Обязательный	По умолчанию	Описание
`action`	`Literal[list, info]`	Да	-	Действие: перечислить доступные репозитории или получить сведения о репозитории
`repository`	`str`	Нет	-	Репозиторий в формате owner/repo или owner/repo:branch (обязателен для info)
`branch`	`str`	Нет	-	Переопределение ветки
`pattern`	`str`	Нет	-	Шаблон фильтра
`include_statistics`	`bool`	Нет		Опционально: включает счётчики индексированных данных по всему пространству имён (file/blob/edge). По умолчанию false — идентификация репозитория не требует этого более медленного агрегата.
`limit`	`int`	Нет	`20`	Максимальное количество результатов, возвращаемых на этой странице
`offset`	`int`	Нет	-	Устаревшее смещение совместимости. Предпочитайте cursor из pagination.next_cursor.
`cursor`	`str`	Нет	-	Непрозрачный cursor от pagination.next_cursor. Передайте его без изменений, оставив без изменений запрос и фильтры.

Лучше всего подходит для:

Перечисление доступных репозиториев
Определение идентичности репозитория, ветки и актуальности HEAD относительно индекса

Не рекомендуется для:

Статистика по всему пространству имён по умолчанию — передавайте include_statistics=true явно, так как это может быть медленнее, чем разрешение

ask_maguyvaСтабильно

Справка и обратная связь по Maguyva. Основное: получить рекомендации по инструментам или отправить отчёт об ошибке / запрос функции, который сохраняется для мейнтейнеров Maguyva. Никогда не включайте в обратную связь секреты или конфиденциальные персональные данные. Операция evaluate сохранена только для обратной совместимости — для математики/хешей/строковых операций предпочитайте локальные вычисления или инструменты хоста.

Параметры:

operationОбязательный

Тип: Literal[guidance, report_bug, request_feature, evaluate]
Описание: Основные: guidance, report_bug, request_feature. Только устаревшие/для совместимости: evaluate (детерминированный движок выражений; не входит в основной рабочий процесс агента).

queryНеобязательный

Тип: str
Описание: Тема рекомендаций (например, tool_selection, semantic_search). Только для устаревшей evaluate: строка выражения.

descriptionНеобязательный

Тип: str
Описание: Обязательно для report_bug и request_feature. Обратная связь в произвольной форме для мейнтейнеров Maguyva. Никогда не включайте секреты или конфиденциальные персональные данные.

related_toolНеобязательный

Тип: Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]
Описание: Дополнительный инструмент Maguyva, наиболее тесно связанный с обратной связью.

Параметр	Тип	Обязательный	По умолчанию	Описание
`operation`	`Literal[guidance, report_bug, request_feature, evaluate]`	Да	-	Основные: guidance, report_bug, request_feature. Только устаревшие/для совместимости: evaluate (детерминированный движок выражений; не входит в основной рабочий процесс агента).
`query`	`str`	Нет	-	Тема рекомендаций (например, tool_selection, semantic_search). Только для устаревшей evaluate: строка выражения.
`description`	`str`	Нет	-	Обязательно для report_bug и request_feature. Обратная связь в произвольной форме для мейнтейнеров Maguyva. Никогда не включайте секреты или конфиденциальные персональные данные.
`related_tool`	`Literal[ask_maguyva, get_file, repository_context, find_symbol, structural_search, dependency_search, analyze_dependencies, semantic_search, text_pattern_search, intelligent_search, get_task_context]`	Нет	-	Дополнительный инструмент Maguyva, наиболее тесно связанный с обратной связью.

Лучше всего подходит для:

Руководство по инструментам (operation="guidance")
Долговременные отчёты об ошибках и запросы функций для сопровождающих Maguyva

Не рекомендуется для:

Вычисления с математикой/хешем/строками — операция evaluate только устаревшая/для обратной совместимости; предпочтите локальные вычисления на хосте

Лучшие практики#

Осознанно используйте явные переопределения: Не указывайте репозиторий, если MCP-клиент задаёт значение по умолчанию для запроса или ключ имеет доступ ровно к одному репозиторию; в остальных случаях передайте его явно.
Выбирайте подходящий режим поиска: Используйте intelligent_search с mode="auto" в большинстве случаев. Указывайте конкретный режим, когда точно знаете, что вам нужно.
Используйте языковые фильтры: Используйте language_filter, чтобы сузить результаты и повысить производительность.
Усиление GraphRAG: Усиление важности GraphRAG по умолчанию выключено для семантического поиска (boost_by_importance=false), чтобы ранжирование оставалось безопасным для агентов. Передайте boost_by_importance=true, чтобы включить переранжирование с учётом центральности для обзоров архитектуры.
Сопоставление репозитория регистронезависимо, но не нечёткое: repository_context сопоставляет названия репозиториев без учёта регистра — опечатки он не исправляет. Проверьте metadata.resolution_reason в действии info ("exact" или "corrected"), чтобы понять, как было разрешено имя.
Комбинируйте инструменты: Используйте несколько методов API вместе для всестороннего анализа.
Обрабатывайте большие результаты: Используйте limit и специфичные для инструмента параметры пагинации (например, line_start/line_end в get_file).
Используйте ask_maguyva для подсказок по инструментам: Операция evaluate у ask_maguyva (хеши, base64, JSON, математика) — это устаревший режим, оставленный только для обратной совместимости. Вместо неё вызывайте ask_maguyva с operation="guidance" и query="tool_selection" — так вы получите матрицу приоритета локальных инструментов и полную шпаргалку по каждому инструменту.
Проверяйте влияние до и после редактирования: Перед изменением общего символа вызовите dependency_search с analysis_type="impact" (или передайте changed_paths для анализа влияния PR/диффа), чтобы увидеть его радиус воздействия. После редактирования установите verify_after_edit=true с targets и/или changed_paths для компактной повторной проверки тех же символов.

Характеристики производительности#

Операция	Примечания по производительности
Семантический поиск	Меньше секунды, но при этом каждый раз выполняется отдельный вызов API эмбеддинга (без кеширования) — ожидайте дополнительную задержку сверх времени векторного запроса
Текстовый поиск	Меньше секунды для точного/regex-поиска; нечёткий поиск по содержимому пагинируется на стороне клиента, поэтому глубокие смещения обходятся дороже — сужайте выборку через path_filter/language_filter
Структурный поиск	Индексируется через AST — стоимость масштабируется по объёму результатов, а не по размеру репозитория
Поиск зависимостей	Стоимость масштабируется по глубине — предпочитайте depth="shallow", если не нужен многошаговый контекст; per_hop_limit ограничивает разрастание
Получение файлов	Почти мгновенно для одного файла — постранично читайте большие файлы через line_start/line_end или max_tokens вместо одной большой выборки
Контекст репозитория	Разрешение пространства имён кешируется только в рамках одного запроса, а не между вызовами — каждый вызов инструмента выполняет его заново
ask_maguyva (guidance / evaluate)	Почти мгновенно — выполняется внутри Worker без обращения к базе данных

Обработка ошибок#

Все методы API возвращают структурированный конверт ответа:

status: Строка — "success" или "error". Признаки неполного совпадения и устаревания данных содержатся во вложенных полях, например metadata.resolution_reason у repository_context или metadata.index_freshness.status.
tool: Имя инструмента, сгенерировавшего ответ
data: Полезная нагрузка результата при успехе (структура зависит от инструмента)
error: Структурированный объект ошибки, когда status равен "error" — включает type, message, suggestions и recovery_actions
metadata: Дополнительная информация об операции (маршрутизация, кеширование, корректировки параметров)
pagination: Присутствует в ответах со списками — включает has_more и next_cursor

Всегда проверяйте поле status, прежде чем обрабатывать результаты — оно принимает только значения "success" или "error". Для признаков неполного совпадения или устаревания данных читайте вложенное поле: metadata.resolution_reason у repository_context или metadata.index_freshness.status (known/partial/unknown/unavailable).

Начало работы#

Настройте MCP-клиент: Укажите в MCP-клиенте адрес сервера Maguyva
Подтвердить доступ к репозиторию: Используйте repository_context с list или info, чтобы проверить доступные API-ключу репозитории
Начните поиск: Начните с intelligent_search и переходите к специализированным инструментам по мере необходимости
Комбинируйте инструменты: Используйте несколько инструментов вместе для всестороннего анализа кода

Подробные инструкции по интеграции смотрите здесь: руководство по установке.