Перейти до вмісту

Довідник 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" - використовує гілку main, якщо гілку не вказано "owner/repository"
  • Типове значення запиту або єдиного репозиторію: Пропустіть repository, якщо MCP-клієнт передає типове значення для запиту або ключ має доступ рівно до одного репозиторію; інакше передайте його явно.

Приклади запитів:

Запит про конкретний репозиторій:  "Знайди middleware автентифікації в 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+ підтримуваних мов і текстових технологій. Повний список дивіться на сторінці «сумісність». 
"Знайди middleware автентифікації лише у файлах Python"
"Знайди підключення до бази даних у TypeScript"

Довідник API згенеровано з вихідного коду 21 жовтня 2026 р..

Основні інструменти пошуку

#

intelligent_search Стабільно

Почніть тут із будь-яким запитанням про кодову базу. За замовчуванням auto/balanced спрямовує запити, які з високою впевненістю визначено як запити про визначення, до структурного пошуку, запити про посилання чи вплив — до графа, а запити на точний збіг — до текстового пошуку. Інші запити використовують семантичний зміст та індексований текст. Використовуйте mode=hybrid або auto з quality=thorough, щоб запросити всі чотири різновиди пошуку; явно вказаний режим має пріоритет над 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
Опис
Початкові точки завдання Tier-1: ідентифікатори символів, ключових для поточного завдання. Якщо параметр задано, об’єднані результати переранжовуються за близькістю зі спаданням ваги з глибиною за Approach A (точний збіг із початковим символом + переходи ребрами графа). Це додатковий сигнал — пропустіть параметр для глобального ранжування.
seed_file_paths Необов'язковий
Тип
list[str] maxItems=10
Опис
Початкові точки завдання 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" (обхід вхідних зв’язків; для impact за замовчуванням shallow), include_metrics=false за замовчуванням (увімкніть для centrality + refactor_risk). dependents/impact типово містять production_callers: унікальні місця використання у виробничому коді за видами (call, instantiate, value_reference для функцій, переданих як значення), а також місця IMPORT; тести виключено, рівень довіри EXTRACTED/INFERRED указано — це не просто набір метрик. Для аналізу впливу PR/дифу передайте changed_paths та/або patch (unified diff): інструмент знаходить символи за кожним шляхом і повертає компактну відповідь із залежними елементами після неглибокого обходу вхідних зв’язків, без потреби вказувати ім’я символу. Після редагування встановіть verify_after_edit=true з targets та/або changed_paths для компактного повторного запиту щодо символів, яких стосуються зміни, з кількох початкових точок. Також підтримує dependencies, centrality та orphans. analyze_dependencies використовує той самий обхід для багатокрокового аналізу впливу.

Параметри:

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/дифу (за замовчуванням) або, за verify_after_edit=true, початкові точки перевірки після редагування. Нерозв'язані шляхи можуть повернути позначені пропозиції; запропоновані файли ніколи не стають початковими точками аналізу впливу. PR/диф: без інформації про рядки обходить визначення верхнього рівня кожного шляху (спершу експортовані, у порядку у файлі) і повідомляє changed_lines_unknown; щоб отримати символи, змінені на рівні рядків, передайте patch=. Перевірка: до 5 визначень верхнього рівня на шлях як початкові точки перевірки (у режимі перевірки діє нижча верхня межа). Для аналізу впливу PR/дифу query/target не потрібні.
patch Необов'язковий
Тип
str maxLength=500000
Опис
Аналіз впливу PR/дифу: текст у форматі 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 також дає відповідь про вплив. Якщо задано 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}). risk має значення "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]
Опис
Дія: 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 з action="list" або action="info", щоб переглянути репозиторії, доступні для API-ключа
  3. Почніть пошук: Розпочніть з intelligent_search і за потреби переходьте до спеціалізованих інструментів
  4. Комбінуйте інструменти: Поєднуйте кілька інструментів для повного аналізу коду

Детальні інструкції з інтеграції дивіться тут: гайд зі встановлення.

Пов'язане

Читати далі