Перейти к содержимому

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

Изучите 11 MCP-инструментов Maguyva, их параметры и подходящие сценарии применения. Доступные аргументы указаны в ответе tools/list подключённого клиента.

Обзор API

#

Инструменты распределены по категориям: 4.

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

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

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

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

#

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

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

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

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

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

#

Используйте language_filter в поддерживаемых режимах поиска. Для text_pattern_search выберите search_scope="content"; для get_task_context используйте scope="semantic" без исходных точек и связанного контекста.

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

Справочник API сгенерирован из исходного кода 21 октября 2026 г..

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

#

intelligent_search Стабильно

Начните здесь с любого вопроса о кодовой базе. По умолчанию auto/balanced направляет вопросы об определениях с уверенно распознанным намерением в структурный поиск, вопросы о ссылках или влиянии — в граф, а запросы на точное совпадение — в текстовый поиск. Для остальных вопросов используются семантический поиск и индексированный текст. Чтобы запросить все четыре поисковые модальности, используйте mode=hybrid или auto с quality=thorough. Явно заданный mode имеет приоритет над quality. language_filter исключает граф из auto/hybrid и отклоняется при явном mode=graph. Предпочитайте этот инструмент Grep/Glob, если путь ещё неизвестен.

Параметры:

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

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

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

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

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

semantic_search Стабильно

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

Параметры:

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

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

  • Концептуальные запросы («как работает аутентификация?», «стратегия кеширования»)
  • Поиск похожего кода между пакетами

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

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

text_pattern_search Стабильно

Поиск индексированного содержимого. exact и regex применяют grep ко всему корпусу файлов/blob; fuzzy content ищет в ограниченном корпусе семантических фрагментов. Области file и symbol поддерживают только триграммы — стандартный mode=exact преобразуется в fuzzy. Настройки языка, регистра и собственного порога требуют области content. Фильтр путей использует ограниченное окно кандидатов и сообщает о неполном охвате. Для небольшого каталога на диске используйте локальный Grep.

Параметры:

query Обязательный
Тип
str minLength=1
Описание
Текстовый паттерн
repository Необязательный
Тип
str
Описание
Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. Приоритет отдаётся точно проиндексированным веткам; недоступная ветка может быть заменена на main или на единственную доступную ветку. Метаданные ответа показывают запрошенную и фактически использованную репозиторную идентичность и предупреждают о таком откате.
mode Необязательный
Тип
Literal[fuzzy, exact, regex]
По умолчанию
exact
Описание
Режим поиска. Regex выполняется в расширенном/POSIX-синтаксисе PostgreSQL; используйте \y для границ слова (\b означает символ возврата на одну позицию). Шаблоны также проходят проверку безопасности JavaScript, поэтому конструкции, специфичные только для PostgreSQL, такие как встроенные флаги (?i), отклоняются; вместо этого используйте case_sensitive.
search_scope Необязательный
Тип
Literal[content, symbols, files]
По умолчанию
content
Описание
Что искать
limit Необязательный
Тип
int minimum=1, maximum=50
По умолчанию
5
Описание
Максимальное число результатов на странице без cursor. Продолжение использует размер страницы, сохранённый в cursor; опустите cursor, чтобы начать с другим limit.
offset Необязательный
Тип
int minimum=0
Описание
Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
cursor Необязательный
Тип
str
Описание
Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и не меняйте query и фильтры. Его позиция и размер страницы имеют приоритет над offset и limit.
language_filter Необязательный
Тип
str
Описание
Фильтр по языку
path_filter Необязательный
Тип
str
Описание
Фильтровать по префиксу пути к файлу
case_sensitive Необязательный
Тип
bool
По умолчанию
false
Описание
С учётом регистра
branch Необязательный
Тип
str
Описание
Переопределение ветки
fuzzy_algorithm Необязательный
Тип
Literal[hybrid, trigram, levenshtein]
По умолчанию
hybrid
Описание
Алгоритм нечёткого сопоставления
threshold Необязательный
Тип
float minimum=0, maximum=1
По умолчанию
0.05
Описание
Минимальный порог сходства для нечёткого поиска
semantic_fallback Необязательный
Тип
bool
По умолчанию
false
Описание
Пробует семантический поиск после пустой первой лексической страницы; metadata.fallback_status различает состояния отката used, empty и unavailable.

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

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

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

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

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

#

structural_search Стабильно

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

Параметры:

repository Необязательный
Тип
str
Описание
Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. Приоритет отдаётся точно проиндексированным веткам; недоступная ветка может быть заменена на main или на единственную доступную ветку. Метаданные ответа показывают запрошенную и фактически использованную репозиторную идентичность и предупреждают о таком откате.
preset Необязательный
Тип
Literal[functions, classes, methods, imports, variables]
Описание
Предпочтительный структурный селектор. Разворачивается в кросс-языковые типы узлов AST — functions (определения функций/стрелочных функций/методов на разных языках); classes (объявления классов/структур/интерфейсов, тела типов и реализации); methods (определения методов (и function_definition для языков без узла метода)); imports (операторы import/use/include); variables (объявления переменных variable/let/const/static). Предпочтительнее произвольных pattern/node_type для запросов в стиле обзора.
pattern Необязательный
Тип
str
Описание
Свободный pattern заполняет недостающие селекторы (автоопределение: 'def foo(' → node_type + name_pattern). Может сочетаться с preset; явные селекторы имеют приоритет. Для запросов обзора предпочтительнее preset=.
name_pattern Необязательный
Тип
str maxLength=256
Описание
Шаблон имени символа (шаблон оболочки, ограниченное POSIX-регулярное выражение или нечёткий текст; максимум 256 символов)
node_type Необязательный
Тип
str
Описание
Тип узла AST (function_definition, class_definition и т.д.) — для типовых форм предпочитайте preset=
decorator Необязательный
Тип
str
Описание
Фильтр по имени декоратора
base_class Необязательный
Тип
str
Описание
Фильтр по базовому классу
language_filter Необязательный
Тип
str
Описание
Фильтр по языку (python, typescript и т. д.)
limit Необязательный
Тип
int minimum=1, maximum=50
По умолчанию
20
Описание
Максимальное число результатов на странице без cursor. Продолжение использует размер страницы, сохранённый в cursor; опустите cursor, чтобы начать с другим limit.
offset Необязательный
Тип
int minimum=0
Описание
Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
cursor Необязательный
Тип
str
Описание
Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и не меняйте query и фильтры. Его позиция и размер страницы имеют приоритет над offset и limit.
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
По умолчанию
false
Описание
Задайте true при намеренном использовании расширенных фильтров путей, ltree или вызовов (ltree_ancestor, ltree_descendant, min_depth, max_depth, field_role, definition_name, callee_text, callee_name). При false переданные расширенные фильтры применяются с предупреждением в метаданных. Для обычных структурных запросов предпочитайте preset=.
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/диффа: передайте changed_paths и/или patch (unified diff) — символы разрешаются по каждому пути, возвращается компактная неглубокая (shallow) полезная нагрузка входящих зависимых без необходимости указывать имя символа. После редактирования установите verify_after_edit=true с targets и/или changed_paths для компактной многокорневой повторной проверки затронутых символов. Также поддерживает dependencies, centrality и orphans. analyze_dependencies использует тот же обход для многошагового анализа влияния. dependents/impact по умолчанию включают production_callers: уникальные места использования в рабочем коде по видам (call, instantiate, value_reference для функций, передаваемых как значения), а также места IMPORT; тесты исключены, достоверность EXTRACTED/INFERRED указана — это не просто набор метрик.

Параметры:

repository Необязательный
Тип
str
Описание
Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. Приоритет отдаётся точно проиндексированным веткам; недоступная ветка может быть заменена на main или на единственную доступную ветку. Метаданные ответа показывают запрошенную и фактически использованную репозиторную идентичность и предупреждают о таком откате.
query Необязательный
Тип
str
Описание
Имя символа или поисковый термин
target Необязательный
Тип
str
Описание
Имя символа (псевдоним query)
symbol_id Необязательный
Тип
UUID
Описание
Выберите по UUID конкретное вхождение среди кандидатов с именем, указанным в query/target, после фильтрации по пространству имён, пути и языку. Используйте ID, возвращённый find_symbol или альтернативными результатами графа. Только для обхода с указанным именем; ID вне ограниченного окна кандидатов вызывает ошибку.
changed_paths Необязательный
Тип
list[str] maxItems=50
Описание
Точные пути к файлам относительно корня репозитория для анализа влияния PR/diff (по умолчанию) или, при verify_after_edit=true, исходные точки проверки после редактирования. Неразрешённые пути могут вернуть помеченные предложения; предложенные файлы никогда не становятся исходными точками анализа влияния. PR/diff: без информации о строках обходит определения верхнего уровня в каждом пути (сначала экспортируемые, в порядке следования в файле) и сообщает changed_lines_unknown; чтобы получить символы, изменённые построчно, передайте patch=. Проверка: до 5 определений верхнего уровня на путь в качестве исходных точек проверки (в режиме проверки действует меньший верхний лимит). Для анализа влияния PR/diff не требуется query/target.
patch Необязательный
Тип
str maxLength=500000
Описание
Анализ влияния PR/diff: текст в формате unified diff / git patch. Пути берутся из заголовков diff --git / --- / +++; строки фрагментов изменений (старая сторона = проиндексированный коммит) сопоставляются с охватывающими их функциями, методами и классами, по которым затем ищутся точные зависимые элементы, public_api_changed и места вызова, которых изменения не касаются.
head_commit Необязательный
Тип
str pattern=^[0-9a-fA-F]{7,64}$
Описание
SHA коммита кода, о котором вы спрашиваете (git rev-parse HEAD или базовый коммит патча). Для complete:true индекс должен соответствовать этому коммиту и быть построен текущим резолвером; иначе остаётся complete:false с index_stale / index_freshness_unverified / index_built_by_older_resolver, а index_basis.statement сообщает, в каких пределах ответ полон. Значение также берётся из строки 'base-commit:' патча (git format-patch --base).
analysis_type Необязательный
Тип
Literal[centrality, dependencies, dependents, impact, orphans]
По умолчанию
dependencies
Описание
Режим анализа. impact = радиус влияния (входящие зависимые; неглубокая (shallow) глубина, если depth не указана). dependents тоже отвечает на impact. Если задан changed_paths или patch, анализ принудительно переключается на режим влияния PR/диффа. centrality/orphans не требуют target. orphans — это кандидаты на неиспользуемый код, а не доказательство того, что его можно безопасно удалить; проверьте ссылки в исходном коде.
depth Необязательный
Тип
Literal[shallow, balanced, deep]
Описание
Глубина обхода. По умолчанию balanced; impact и PR/diff impact по умолчанию используют shallow. Явно заданный depth переопределяет эти значения по умолчанию. Режим проверки всегда использует shallow.
limit Необязательный
Тип
int minimum=1, maximum=50
По умолчанию
20
Описание
Максимальное число результатов на странице без cursor. Продолжение использует размер страницы, сохранённый в cursor; опустите cursor, чтобы начать с другим limit.
offset Необязательный
Тип
int minimum=0
Описание
Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
cursor Необязательный
Тип
str
Описание
Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и не меняйте query и фильтры. Его позиция и размер страницы имеют приоритет над offset и limit.
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
По умолчанию
false
Описание
Исключить из результатов обхода пути сгенерированных объявлений, артефактов сборки, отчётов о покрытии, кеша, карт исходного кода и минифицированных артефактов
include_module_symbols Необязательный
Тип
bool
По умолчанию
false
Описание
По умолчанию: false — исключаются рёбра, у которых from_name или to_name — синтетический символ __module__ (шум на уровне модуля). Установите true, чтобы включить рёбра уровня модуля в результаты dependents/dependencies.
include_isolated Необязательный
Тип
bool
Описание
Только для orphans. По умолчанию false. Установите true, чтобы также возвращать символы без строки в метриках графа (вообще без рёбер в графе). Пока exclude_test_paths равен true, символы таблиц стилей, разметки и данных (CSS, HTML, ...), объявления .d.ts и пути test/fixture/vendor/example остаются исключёнными там, где это поддерживает бэкенд, если только language_filter не указывает этот язык; свойства объектных литералов TypeScript по-прежнему могут отображаться как изолированные функции.
exclude_exported Необязательный
Тип
bool
По умолчанию
false
Описание
Только для осиротевших символов. По умолчанию false: экспортируемые символы (публичный API), не используемые в репозитории, возвращаются с is_exported=true. Укажите true, чтобы оставить только внутренние кандидаты.
branch Необязательный
Тип
str
Описание
Переопределение ветки
per_hop_limit Необязательный
Тип
int minimum=1, maximum=300
Описание
Максимальное количество связей на один переход (1-300)
include_metrics Необязательный
Тип
bool
По умолчанию
false
Описание
Опциональные графовые метрики в строках результата (сжаты вместе с refactor_risk). Метрики также запрашиваются внутренне, когда min_centrality>0, но не возвращаются, если это не установлено в true.
metrics_detail Необязательный
Тип
Literal[summary, full]
По умолчанию
summary
Описание
Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.
include_edge_metadata Необязательный
Тип
bool
По умолчанию
false
Описание
Включить исходные метаданные и веса рёбер (большой объём данных). В компактных ответах анализа влияния этот параметр отключён.
symbol_types Необязательный
Тип
list[str]
Описание
Фильтрует возвращаемые символы по виду (function, class, method и т. д.). Не поддерживается в анализе orphan; в этом случае используйте path_filter или language_filter. Пустой список не применяет фильтр по виду.
exact_match Необязательный
Тип
bool
По умолчанию
false
Описание
Требовать точное совпадение имени символа
find_similar_patterns Необязательный
Тип
bool
По умолчанию
false
Описание
Найти похожие шаблоны использования
min_centrality Необязательный
Тип
float minimum=0
По умолчанию
0
Описание
Минимальный показатель PageRank для обхода именованных символов и анализа влияния PR/diff. Положительные пороговые значения не поддерживаются в режимах обзора centrality/orphans. Метрики запрашиваются внутренне для фильтрации; graph_metrics возвращаются только при include_metrics=true. Игнорируется в verify_after_edit, который использует фиксированные компактные параметры.
graph_view Необязательный
Тип
Literal[dependency, type, data_flow, control_flow]
По умолчанию
dependency
Описание
Представление графа, используемое для значений по умолчанию при обходе связей, метрик и ранжирования по centrality; анализ orphan рассчитывается по всем представлениям
verify_after_edit Необязательный
Тип
bool
По умолчанию
false
Описание
Повторно запрашивает индексированный граф влияния для изменённых символов в одном компактном ответе с несколькими корнями. Требует targets и/или changed_paths (или target/query). Использует фиксированный обход shallow и компактные бюджеты; элементы управления depth/limit/cursor/metrics не применяются. По умолчанию возвращает incoming dependents; результаты отражают индексированный граф (может отставать от правок в реальном времени). При true имеет приоритет над PR/diff impact для тех же changed_paths.
targets Необязательный
Тип
list[str] maxItems=15
Описание
При 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]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. Приоритет отдаётся точно проиндексированным веткам; недоступная ветка может быть заменена на main или на единственную доступную ветку. Метаданные ответа показывают запрошенную и фактически использованную репозиторную идентичность и предупреждают о таком откате.
scope Необязательный
Тип
Literal[definitions, references, both]
По умолчанию
both
Описание
Область поиска; references требует непустого symbol_name.
limit Необязательный
Тип
int minimum=1, maximum=50
По умолчанию
15
Описание
Максимальное число результатов на странице без cursor. Продолжение использует размер страницы, сохранённый в cursor; опустите cursor, чтобы начать с другим limit.
offset Необязательный
Тип
int minimum=0
Описание
Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
cursor Необязательный
Тип
str
Описание
Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и не меняйте query и фильтры. Его позиция и размер страницы имеют приоритет над offset и limit.
find_similar Необязательный
Тип
bool
По умолчанию
false
Описание
Включить похожие имена символов
include_metrics Необязательный
Тип
bool
По умолчанию
false
Описание
Включить метрики центральности
metrics_detail Необязательный
Тип
Literal[summary, full]
По умолчанию
summary
Описание
Когда include_metrics=true: summary (по умолчанию) возвращает сигналы решения + refactor_risk; full возвращает более крупный набор курируемых показателей.
path_filter Необязательный
Тип
str
Описание
Фильтровать по префиксу пути к файлу
branch Необязательный
Тип
str
Описание
Переопределение ветки
symbol_type Необязательный
Тип
str minLength=1
Описание
Фильтр по типу индексированного символа, например function, class, struct, enum или trait. Используйте тип, возвращаемый результатом символа; тип различается в зависимости от языка.
high_impact Необязательный
Тип
bool
По умолчанию
false
Описание
Просмотр архитектурно значимых символов (не указывайте symbol_name). Режим по умолчанию — popularity (верхний дециль PageRank без служебных мегахабов). Установите high_impact_mode=risk для поиска вершин-разделителей — точек сочленения и вершин, связывающих части графа.
high_impact_mode Необязательный
Тип
Literal[popularity, risk]
По умолчанию
popularity
Описание
При high_impact=true: popularity = верхний дециль PageRank без служебных мегахабов/модулей; risk = точки сочленения, ранжированные по SMV bridge_count, затем по k_core (структурный риск рефакторинга, а не популярность хаба)
in_cycle Необязательный
Тип
bool
По умолчанию
false
Описание
Отбирает символы с зафиксированным участием в цикле зависимостей.
exclude_test_paths Необязательный
Тип
bool
По умолчанию
true
Описание
При просмотре по метрикам графа исключать тесты, фикстуры, сторонний код и примеры до ранжирования; поиск символа по имени не изменяется
reference_views Необязательный
Тип
list[Literal[dependency, type, data_flow, control_flow, all]] minItems=1, maxItems=5
Описание
Представления графа, входящие рёбра которых заполняют references/reference_count (scope references/both). По умолчанию ["dependency", "type"]: вызовы, импорты, экспорты, ссылки, создание экземпляров, наследование, переопределения, декораторы и использование типов. Если data_flow не выбран, точно разрешённые использования data_flow (обратные вызовы, обработчики, ключи сортировки) возвращаются отдельно как value_references/value_reference_count, без совпадений, выведенных лишь по имени. Добавьте data_flow или control_flow либо передайте ["all"] для всех типов и уровней рёбер. Семейства представлений те же, что у graph_view в dependency_search.
relationship_types Необязательный
Тип
list[str]
Описание
Явно заданные типы рёбер ссылок (CALL, IMPORT, READS и т. д.). Непустой список заменяет reference_views.

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

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

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

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

analyze_dependencies Стабильно

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

Параметры:

repository Необязательный
Тип
str
Описание
Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. Приоритет отдаётся точно проиндексированным веткам; недоступная ветка может быть заменена на main или на единственную доступную ветку. Метаданные ответа показывают запрошенную и фактически использованную репозиторную идентичность и предупреждают о таком откате.
target Обязательный
Тип
str minLength=1
Описание
Имя символа для анализа
symbol_id Необязательный
Тип
UUID
Описание
Выберите по UUID конкретное вхождение среди кандидатов target после фильтрации по пространству имён, пути и языку; ID вне ограниченного окна кандидатов вызывают ошибку.
depth Необязательный
Тип
Literal[shallow, balanced, deep]
По умолчанию
balanced
Описание
Глубина анализа
limit Необязательный
Тип
int minimum=1, maximum=50
По умолчанию
10
Описание
Максимальное число результатов на странице без cursor. Продолжение использует размер страницы, сохранённый в cursor; опустите cursor, чтобы начать с другим limit.
offset Необязательный
Тип
int minimum=0
Описание
Устаревшее смещение для обратной совместимости. Предпочитайте cursor из pagination.next_cursor.
cursor Необязательный
Тип
str
Описание
Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и не меняйте query и фильтры. Его позиция и размер страницы имеют приоритет над offset и limit.
direction Необязательный
Тип
Literal[incoming, outgoing, 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 minimum=1, maximum=300
Описание
Максимальное количество связей на один переход (1-300)
include_metrics Необязательный
Тип
bool
По умолчанию
false
Описание
Включить в результаты метрики графа, дополнив каждую производным блоком 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
По умолчанию
false
Описание
Включить исходные метаданные и веса рёбер. По умолчанию отключено, поскольку метаданные экстрактора могут быть объёмными; при включении сообщается охват обогащения данных.
exclude_test_paths Необязательный
Тип
bool
По умолчанию
true
Описание
По умолчанию: true — из возвращаемых рёбер графа исключаются пути тестов, фикстур, стороннего кода и примеров. Установите false, чтобы включить их.
include_module_symbols Необязательный
Тип
bool
По умолчанию
false
Описание
По умолчанию: false — исключаются рёбра, у которых from_name или to_name — синтетический символ __module__. Установите true, чтобы включить рёбра уровня модуля.
head_commit Необязательный
Тип
str pattern=^[0-9a-fA-F]{7,64}$
Описание
SHA коммита кода, о котором вы спрашиваете (git rev-parse HEAD или базовый коммит патча). Для complete:true индекс должен соответствовать этому коммиту и быть построен текущим резолвером; иначе остаётся complete:false с index_stale / index_freshness_unverified / index_built_by_older_resolver, а index_basis.statement сообщает, в каких пределах ответ полон. Значение также берётся из строки 'base-commit:' патча (git format-patch --base).

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

  • Многошаговый анализ влияния, когда нужны поля ответа graph и connection_summary

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

  • Общий анализ влияния — предпочитайте dependency_search для гибкого обхода и проверок с несколькими исходными точками

get_task_context Стабильно

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

Параметры:

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

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

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

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

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

get_file Стабильно

Читает файл из индексированного репозитория по пути. Для файлов на диске предпочтительнее использовать локальные файловые инструменты; это предназначено для удалённых индексированных снимков. Продолжайте ограниченные ответы с помощью metadata.next_line_start и next_character_start. Удаляйте завершающий перевод строки и маркер [truncated] только когда metadata.truncated=true; в противном случае это может быть буквальный исходный текст.

Параметры:

file_path Обязательный
Тип
str
Описание
Путь к файлу относительно корня репозитория
repository Необязательный
Тип
str
Описание
Репозиторий в формате owner/repo[:branch]. Необязательно — не указывайте, чтобы использовать клиентское значение по умолчанию в рамках запроса (если оно задано) или единственный доступный репозиторий; передавайте явно только для выбора другого проиндексированного репозитория. Приоритет отдаётся точно проиндексированным веткам; недоступная ветка может быть заменена на main или на единственную доступную ветку. Метаданные ответа показывают запрошенную и фактически использованную репозиторную идентичность и предупреждают о таком откате.
line_start Необязательный
Тип
int minimum=1
Описание
Начальная строка (нумерация с 1)
line_end Необязательный
Тип
int minimum=1
Описание
Конечная строка (нумерация с 1, включительно; должна быть не меньше line_start)
character_start Необязательный
Тип
int minimum=0
По умолчанию
0
Описание
Смещение в кодовых единицах UTF-16 только внутри начальной строки (нумерация с 0). Используйте metadata.next_character_start для продолжения частично прочитанной строки.
branch Необязательный
Тип
str
Описание
Переопределение ветки
max_tokens Необязательный
Тип
int minimum=1, maximum=50000
По умолчанию
5000
Описание
Приблизительный бюджет содержимого (4 кодовые единицы UTF-16 на токен; не точный предел токенизатора).
include_metadata Необязательный
Тип
bool
По умолчанию
true
Описание
Включить описательные метаданные файла. Метаданные усечения и продолжения возвращаются всегда.

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

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

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

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

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

#

repository_context Стабильно

Выводит список репозиториев, доступных для поиска, либо получает идентификационную информацию об одном из них (namespace/branch, indexed_commit_sha / актуальность индекса). Используйте action:"list", если slug репозитория неизвестен; инструменты поиска принимают известный slug напрямую либо по умолчанию используют единственный репозиторий вашего ключа. list использует pattern и пагинацию; info требует repository и поддерживает branch, а также опциональный include_statistics=true.

Параметры:

action Обязательный
Тип
Literal[list, info]
Описание
Действие: перечислить доступные репозитории или получить сведения о репозитории
repository Необязательный
Тип
str
Описание
Только для info: репозиторий в формате owner/repo или owner/repo:branch (обязателен для info)
branch Необязательный
Тип
str
Описание
Только для info: переопределение ветки
pattern Необязательный
Тип
str
Описание
Только для list: подстрока имени репозитория без учёта регистра
include_statistics Необязательный
Тип
bool
По умолчанию
false
Описание
Только для информации: включает ограниченные подсчёты индексированных данных. Подсчёты file/blob точны; более крупные подсчёты индекса являются оценками. См. count_accuracy и estimate_analyzed_at. По умолчанию false.
limit Необязательный
Тип
int minimum=1, maximum=50
По умолчанию
20
Описание
Максимальное число результатов на странице без cursor. Продолжение использует размер страницы, сохранённый в cursor; опустите cursor, чтобы начать с другим limit.
offset Необязательный
Тип
int minimum=0
Описание
Устаревшее смещение совместимости. Предпочитайте cursor из pagination.next_cursor.
cursor Необязательный
Тип
str
Описание
Непрозрачный cursor из pagination.next_cursor. Передавайте его без изменений и не меняйте query и фильтры. Его позиция и размер страницы имеют приоритет над offset и limit.

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

  • Перечисление доступных репозиториев
  • Определение идентичности репозитория, ветки и актуальности 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 maxLength=500
Описание
Тема справки (например, tool_selection, semantic_search) или строка выражения для evaluate.
description Необязательный
Тип
str minLength=1, maxLength=4000
Описание
Обязательно для 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

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

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

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

#
  1. Осознанно используйте явные переопределения: Не указывайте репозиторий, если MCP-клиент задаёт значение по умолчанию для запроса или ключ имеет доступ ровно к одному репозиторию; в остальных случаях передайте его явно.
  2. Выбирайте подходящий режим поиска: Используйте intelligent_search с mode="auto" в большинстве случаев. Указывайте конкретный режим, когда точно знаете, что вам нужно.
  3. Используйте языковые фильтры: Используйте language_filter, чтобы сузить результаты и повысить производительность.
  4. Усиление GraphRAG: Усиление важности GraphRAG по умолчанию выключено для семантического поиска (boost_by_importance=false), чтобы ранжирование оставалось безопасным для агентов. Передайте boost_by_importance=true, чтобы включить переранжирование с учётом центральности для обзоров архитектуры.
  5. Сопоставление репозитория регистронезависимо, но не нечёткое: repository_context сопоставляет имена репозиториев без учёта регистра — но не исправляет опечатки. Когда выданная идентичность отличается от запрошенной, metadata.resolution_reason сообщает "defaulted" (ветка не запрашивалась) или "fallback" (запрошенная ветка или репозиторий недоступны). При точном совпадении запроса поле опускается.
  6. Комбинируйте инструменты: Используйте несколько методов API вместе для всестороннего анализа.
  7. Обрабатывайте большие результаты: Используйте limit и специфичные для инструмента параметры пагинации (например, line_start/line_end в get_file).
  8. Используйте ask_maguyva для подсказок по инструментам: Вызовите ask_maguyva с operation="guidance" и query="tool_selection", чтобы получить советы и примеры выбора инструментов. Для вычислений и преобразования строк используйте локальные инструменты.
  9. Проверяйте влияние до и после редактирования: Перед изменением общего символа вызовите dependency_search с analysis_type="impact" (или передайте changed_paths для анализа влияния PR/диффа), чтобы увидеть его радиус влияния. После редактирования установите verify_after_edit=true с targets и/или changed_paths для компактной повторной проверки индексированного графа. Проверка читает индексированный граф, а не незакоммиченные локальные изменения, и не заменяет локальные тесты. Проверьте indexed_commit_sha и актуальность индекса, прежде чем считать результаты свидетельством для новой ревизии.

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

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

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

#

Ответы инструментов содержат общие поля статуса и собственные поля полезной нагрузки на верхнем уровне. Поиск возвращает results; get_file возвращает content. Общие поля включают:

  • status: Строка — "success" или "error". Сигналы ухудшенного совпадения и актуальности индекса лежат в отдельных полях: metadata.resolution_reason внутри metadata и index_freshness.status на верхнем уровне действия info у repository_context.
  • timing_ms: Время выполнения инструмента в миллисекундах
  • applied_filters: Фактически применённые параметры запроса, записанные для операции
  • error: Строка сообщения об ошибке, когда status равен "error"; может содержать рекомендации по восстановлению.
  • metadata: Дополнительная информация об операции (маршрутизация, кеширование, корректировки параметров)
  • pagination: Присутствует в ответах коллекций с курсорной пагинацией — включает has_more и next_cursor. Окна ранжированного поиска — это ограниченные результаты top-K, а не полные коллекции с пагинацией.

Проверяйте поле status, прежде чем обрабатывать полезную нагрузку инструмента: его значения — "success" или "error". Обрабатывайте также транспортные ошибки MCP/JSON-RPC и ошибки валидации запроса, которые могут возникнуть ещё до появления полезной нагрузки. Для сигналов ухудшенного совпадения или актуальности читайте специально отведённое поле: metadata.resolution_reason внутри metadata или index_freshness.status на верхнем уровне действия info у repository_context (known/partial/unknown/unavailable).

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

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

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

По теме

Читать дальше