Довідник MCP API

Повний довідник усіх 11 клієнтських MCP-інструментів Maguyva. Кожен інструмент містить параметри, рекомендації щодо використання та поради, для чого він найкраще підходить.

Огляд API#

Наразі MCP API Maguyva надає 11 клієнтських інструментів у 4 основних категоріях:

Основні інструменти пошуку - Розширені можливості пошуку по вашій кодовій базі
Структурні та графові інструменти - AST-запити, пошук символів і аналіз залежностей
Інструменти аналізу коду - Глибокий аналіз коду та картування зв'язків
Системні та допоміжні інструменти - Контекст репозиторію, детерміновані обчислення та підказки

Усі інструменти використовують послідовний формат ідентифікатора репозиторію: "owner/repo:branch". Якщо гілку не вказано, за замовчуванням використовується main.

Пропускайте repository, коли ваш клієнт MCP надає значення за замовчуванням у межах запиту або ключ має доступ лише до одного репозиторію; інакше передавайте його явно. Використовуйте repository_context(action="info", repository="owner/repo"), щоб перевірити, як визначається репозиторій.

Формат параметра репозиторію#

Усі MCP-інструменти використовують такий формат ідентифікатора репозиторію:

З гілкою: "owner/repo:branch" - наприклад, "owner/repository:develop"
Гілка за замовчуванням: "owner/repo" - використовує основну гілку, якщо гілку не вказано "owner/repository"
Типове значення запиту або єдиного репозиторію: Пропустіть repository, якщо MCP-клієнт передає типове значення для запиту або ключ має доступ рівно до одного репозиторію; інакше передайте його явно.

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

Запит про конкретний репозиторій:  "Знайди middleware автентифікації в owner/my-repo"
Перелік доступних репозиторіїв:    "До яких репозиторіїв має доступ цей ключ Maguyva?"
Перевизначення для одного запиту:  "Знайди патерни автентифікації в owner/other-repo:develop"

Фільтрація за мовою#

Усі інструменти пошуку підтримують фільтрацію результатів за мовою програмування:

language_filter="python" - Фільтрувати лише файли Python
language_filter="typescript" - Фільтрувати лише файли TypeScript
Чутливо до регістру: Використовуйте назви мов у нижньому регістрі
За замовчуванням: Порожній рядок (без фільтрації) — повертає результати з усіх мов
Підтримуване покриття: Мовні фільтри працюють для всіх 279+ підтримуваних мов і текстових технологій. Повний список дивіться в сумісність.

"Знайди middleware автентифікації лише у файлах Python"
"Знайди підключення до бази даних у TypeScript"

Довідник API згенеровано з початкового коду 22 липня 2026 р..

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

intelligent_searchСтабільно

Почніть тут, щоб відповісти на будь-яке запитання щодо бази коду. Дайте йому запит природною мовою (наприклад, «як працює автентифікація», «де обробляється виставлення рахунків»), і він автоматично перенаправить семантичний, символьний, структурний пошук і пошук залежностей індексованого репо. Віддавайте перевагу цьому, ніж агенту Explore і Grep/Glob для дослідження та планування — він виконує пошук у всьому проіндексованому сховищі одночасно замість сканування файлів.

Параметри:

queryОбов'язковий

Тип: str
Опис: Пошуковий запит

repositoryНеобов'язковий

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

modeНеобов'язковий

Тип: Literal[auto, hybrid, semantic, text, structural, ast, graph]
За замовчуванням: auto
Опис: Режим пошуку

limitНеобов'язковий

Тип: int
За замовчуванням: 10
Опис: Максимальна кількість результатів у цьому ранжованому вікні top-K

language_filterНеобов'язковий

Тип: str
Опис: Фільтр за мовою

path_filterНеобов'язковий

Тип: str
Опис: Фільтр за префіксом шляху файлу

boost_by_importanceНеобов'язковий

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

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

qualityНеобов'язковий

Тип: Literal[quick, balanced, thorough]
За замовчуванням: balanced
Опис: Пресет якості пошуку

include_contentНеобов'язковий

Тип: bool
За замовчуванням: true
Опис: Включати вміст у результати

explain_routingНеобов'язковий

Тип: bool
За замовчуванням
Опис: Включити пояснення рішення про маршрутизацію

importance_weightНеобов'язковий

Тип: float
За замовчуванням: 0.3
Опис: Вага підсилення важливості (0=немає, 1=повне)

orphansНеобов'язковий

Тип: bool
За замовчуванням
Опис: Включати орфанні символи (без вхідних посилань)

include_community_contextНеобов'язковий

Тип: bool
За замовчуванням
Опис: Включати пов’язані символи з тієї самої спільноти коду для ширшого контексту

community_depthНеобов'язковий

Тип: int
За замовчуванням: 1
Опис: Глибина розширення контексту спільноти

graph_viewНеобов'язковий

Тип: Literal[dependency, type, data_flow, control_flow]
За замовчуванням: dependency
Опис: Graph view для метрик

seed_symbol_idsНеобов'язковий

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

seed_file_pathsНеобов'язковий

Тип: list[str]
Опис: Засідання завдання Tier-1: індексовані шляхи до файлів, які агент відкрив або щойно відредагував. Якщо встановлено, об’єднані попадання змінюються за близькістю шляху з розпадом глибини 1/(1+d) (той самий файл → той самий каталог → найближчі пакунки). Додаток — пропуск для глобального рейтингу.

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

Найкраще підходить для:

Дослідження по всьому індексу або з нуля, коли незрозуміло, який інструмент обрати
Мультимодальне об'єднане ранжування за семантикою, текстом, структурою та графом

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

Відоме ім'я символу — використовуйте find_symbol напряму
Відомий шлях на диску — спочатку використовуйте локальний Read/Grep

semantic_searchСтабільно

Знайдіть код за змістом, а не за точним текстом. Використовуйте для концептуальних запитів, як-от «логіка повторних спроб» або «потік реєстрації користувача», якщо ви не знаєте ключового слова чи назви символу. Повертає найбільш відповідні фрагменти коду, упорядковані за важливістю. Віддавайте перевагу Grep, коли пошук концептуальний.

Параметри:

queryОбов'язковий

Тип: str
Опис: Пошуковий запит (концептуальний, на основі значення)

repositoryНеобов'язковий

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

limitНеобов'язковий

Тип: int
За замовчуванням: 5
Опис: Максимальна кількість результатів у цьому ранжованому вікні top-K

similarity_thresholdНеобов'язковий

Тип: float
За замовчуванням: 0.6
Опис: Мінімальний бал подібності

language_filterНеобов'язковий

Тип: str
Опис: Мовний фільтр (python, typescript тощо)

path_filterНеобов'язковий

Тип: str
Опис: Фільтр за префіксом шляху файлу

boost_by_importanceНеобов'язковий

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

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

include_contentНеобов'язковий

Тип: bool
За замовчуванням: true
Опис: Включати вміст фрагмента в результати

graph_viewНеобов'язковий

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

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

Найкраще підходить для:

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

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

Відоме ім'я символу — натомість використовуйте find_symbol
Точні рядки або повідомлення про помилки — використовуйте text_pattern_search

text_pattern_searchСтабільно

Шукайте в індексованому вмісті: точний збіг, regex або нечіткий режим. Exact та regex режими grep‑ять по всьому файлу/блобу; fuzzy режим шукає по обмеженому корпусу семантичних фрагментів. Використовуйте local Grep для вузьких директорій, що вже на диску.

Параметри:

queryОбов'язковий

Тип: str
Опис: Текстовий шаблон для пошуку

repositoryНеобов'язковий

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

modeНеобов'язковий

Тип: Literal[fuzzy, exact, regex]
За замовчуванням: exact
Опис: Режим пошуку

search_scopeНеобов'язковий

Тип: Literal[content, symbols, files]
За замовчуванням: content
Опис: Що шукати

limitНеобов'язковий

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

offsetНеобов'язковий

Тип: int
Опис: Застарілий зсув для сумісності. Використовуйте cursor з pagination.next_cursor.

cursorНеобов'язковий

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

language_filterНеобов'язковий

Тип: str
Опис: Фільтр за мовою

path_filterНеобов'язковий

Тип: str
Опис: Фільтр за префіксом шляху файлу

case_sensitiveНеобов'язковий

Тип: bool
За замовчуванням
Опис: Розрізняти регістр

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

fuzzy_algorithmНеобов'язковий

Тип: Literal[hybrid, trigram, levenshtein]
За замовчуванням: hybrid
Опис: Алгоритм нечітого зіставлення

thresholdНеобов'язковий

Тип: float
За замовчуванням: 0.05
Опис: Мінімальний поріг подібності для нечіткого пошуку

semantic_fallbackНеобов'язковий

Тип: bool
За замовчуванням
Опис: Відкат до семантичного пошуку, якщо немає результатів

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

Найкраще підходить для:

Точні рядки, повідомлення про помилки та регулярні вирази
Нечітке триграмне зіставлення для майже збіжного тексту

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

Відомий шлях на диску — надайте перевагу локальному Grep
Концептуальні запити — використовуйте semantic_search

Структурні та графові інструменти#

structural_searchСтабільно

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

Параметри:

repositoryНеобов'язковий

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

presetНеобов'язковий

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

patternНеобов'язковий

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

name_patternНеобов'язковий

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

node_typeНеобов'язковий

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

decoratorНеобов'язковий

Тип: str
Опис: Фільтр за назвою декоратора

base_classНеобов'язковий

Тип: str
Опис: Фільтр за назвою базового класу

language_filterНеобов'язковий

Тип: str
Опис: Мовний фільтр (python, typescript тощо)

limitНеобов'язковий

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

offsetНеобов'язковий

Тип: int
Опис: Застарілий зсув для сумісності. Використовуйте cursor з pagination.next_cursor.

cursorНеобов'язковий

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

path_filterНеобов'язковий

Тип: str
Опис: Фільтр за префіксом шляху файлу

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

query_typeНеобов'язковий

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

parent_typeНеобов'язковий

Тип: str
Опис: Фільтр за типом батьківського AST-вузла

relationshipНеобов'язковий

Тип: Literal[parent, ancestor]
За замовчуванням: parent
Опис: Для parent_child-запитів: direct parent тільки або будь-який ancestor (використовуйте ancestor для методів класу всередині тіла класу/блоку)

has_modifierНеобов'язковий

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

advancedНеобов'язковий

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

callee_textНеобов'язковий

Тип: str
Опис: Розширено — надавайте перевагу preset=functions|classes|methods|imports|variables. Фільтр за текстом callee виразу виклику. Встановіть advanced=true, коли навмисно використовуєте фільтри path/ltree/call.

callee_nameНеобов'язковий

Тип: str
Опис: Розширено — надавайте перевагу preset=functions|classes|methods|imports|variables. Фільтр за іменем callee виразу виклику. Встановіть advanced=true, коли навмисно використовуєте фільтри path/ltree/call.

field_roleНеобов'язковий

Тип: str
Опис: Розширено — надавайте перевагу preset=functions|classes|methods|imports|variables. Фільтр за роллю поля AST. Встановіть advanced=true, коли навмисно використовуєте фільтри path/ltree/call.

ltree_ancestorНеобов'язковий

Тип: str
Опис: Розширено — надавайте перевагу preset=functions|classes|methods|imports|variables. Фільтр за шляхом предка ltree AST. Встановіть advanced=true, коли навмисно використовуєте фільтри path/ltree/call.

ltree_descendantНеобов'язковий

Тип: str
Опис: Розширено — надавайте перевагу preset=functions|classes|methods|imports|variables. Фільтр за шляхом нащадка ltree AST. Встановіть advanced=true, коли навмисно використовуєте фільтри path/ltree/call.

definition_nameНеобов'язковий

Тип: str
Опис: Розширено — надавайте перевагу preset=functions|classes|methods|imports|variables. Фільтр за іменем визначення. Встановіть advanced=true, коли навмисно використовуєте фільтри path/ltree/call.

min_depthНеобов'язковий

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

max_depthНеобов'язковий

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

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

Найкраще підходить для:

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

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

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

dependency_searchСтабільно

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

Параметри:

repositoryНеобов'язковий

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

queryНеобов'язковий

Тип: str
Опис: Назва символу або пошуковий термін

targetНеобов'язковий

Тип: str
Опис: Ім’я символу (синонім параметра query)

changed_pathsНеобов'язковий

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

patchНеобов'язковий

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

analysis_typeНеобов'язковий

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

depthНеобов'язковий

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

limitНеобов'язковий

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

offsetНеобов'язковий

Тип: int
Опис: Застарілий зсув для сумісності. Використовуйте cursor з pagination.next_cursor.

cursorНеобов'язковий

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

path_filterНеобов'язковий

Тип: str
Опис: Обмежує розв'язання цільового символу за префіксом шляху файлу; повернені зв'язки графа можуть виходити за межі цього шляху

language_filterНеобов'язковий

Тип: str
Опис: Фільтрує розв'язання цілі та результати перегляду за мовою

directionНеобов'язковий

Тип: Literal[outgoing, incoming, both]
Опис: Напрямок обходу (перевизначає виведення з analysis_type)

relationship_typesНеобов'язковий

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

exclude_test_pathsНеобов'язковий

Тип: bool
За замовчуванням: true
Опис: За замовчуванням true: виключає шляхи тестів, фікстур, вендорного коду та прикладів із результатів обходу та centrality. Встановіть false, щоб включити їх. Аналіз orphan завжди застосовує власні, суворіші винятки шуму.

exclude_generated_pathsНеобов'язковий

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

include_module_symbolsНеобов'язковий

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

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

per_hop_limitНеобов'язковий

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

include_metricsНеобов'язковий

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

metrics_detailНеобов'язковий

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

include_edge_metadataНеобов'язковий

Тип: bool
За замовчуванням
Опис: Включіть необроблені метадані краю та ваги (великі). Компактні ударні корисні навантаження виключають це.

symbol_typesНеобов'язковий

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

exact_matchНеобов'язковий

Тип: bool
За замовчуванням
Опис: Вимагати точного збігу назви символу

find_similar_patternsНеобов'язковий

Тип: bool
За замовчуванням
Опис: Знаходити подібні патерни використання

min_centralityНеобов'язковий

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

graph_viewНеобов'язковий

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

verify_after_editНеобов'язковий

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

targetsНеобов'язковий

Тип: list[str]
Опис: Коли verify_after_edit=true: імена символів для повторної перевірки (автори/утриманці). Об’єднано з target/query, якщо надано обидва.

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

Найкраще підходить для:

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

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

Простий пошук тексту або символів — використовуйте text_pattern_search або find_symbol

Інструменти аналізу коду#

find_symbolСтабільно

Перейти до місця, де функція, клас або змінна визначені та використовуються. Використовуйте коли знаєте ім'я (наприклад, "getCurrentUser") — швидше і точніше за Grep, охоплює весь індексований репозиторій. Опційно повертає посилання та метрики значущості.

Параметри:

symbol_nameНеобов'язковий

Тип: str
Опис: Назва символу для пошуку (необов’язково — пропустіть, щоб переглянути за метриками)

repositoryНеобов'язковий

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

scopeНеобов'язковий

Тип: Literal[definitions, references, both]
За замовчуванням: both
Опис: Область пошуку

limitНеобов'язковий

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

offsetНеобов'язковий

Тип: int
Опис: Застарілий зсув для сумісності. Використовуйте cursor з pagination.next_cursor.

cursorНеобов'язковий

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

find_similarНеобов'язковий

Тип: bool
За замовчуванням
Опис: Включати подібні назви символів

include_metricsНеобов'язковий

Тип: bool
За замовчуванням
Опис: Включати метрики центральності

metrics_detailНеобов'язковий

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

path_filterНеобов'язковий

Тип: str
Опис: Фільтр за префіксом шляху файлу

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

symbol_typeНеобов'язковий

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

high_impactНеобов'язковий

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

high_impact_modeНеобов'язковий

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

in_cycleНеобов'язковий

Тип: bool
За замовчуванням
Опис: Фільтрувати лише символи в циклах залежностей

exclude_test_pathsНеобов'язковий

Тип: bool
За замовчуванням: true
Опис: Під час перегляду за показниками графіка виключіть тести, fixtures, код сторонніх розробників і приклади перед ранжуванням. Пошук за іменованим символом не змінюється.

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

Найкраще підходить для:

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

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

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

analyze_dependenciesСтабільно

Псевдонім для blast radius через dependency_search (dependents/incoming). Для нових агентів надавайте перевагу dependency_search з analysis_type="dependents" або "impact". Зберігає застарілу багатокрокову форму відповіді impact (graph, connection_summary, опційні метрики з refactor_risk). Використовуйте graph_view, щоб визначити сімейство зв'язків: dependency (за замовчуванням), type, data_flow, control_flow.

Параметри:

repositoryНеобов'язковий

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

targetОбов'язковий

Тип: str
Опис: Назва символу для аналізу

depthНеобов'язковий

Тип: Literal[shallow, balanced, deep]
За замовчуванням: balanced
Опис: Глибина аналізу

limitНеобов'язковий

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

offsetНеобов'язковий

Тип: int
Опис: Застарілий зсув для сумісності. Використовуйте cursor з pagination.next_cursor.

cursorНеобов'язковий

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

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
Опис: Graph view: визначає типи ребер для обходу за замовчуванням і які метрики використовуються при include_metrics=true. dependency=[CALL,IMPORT,EXPORTS,REFERENCE,INSTANTIATES] (за замовчуванням), type=[INHERITS_FROM,IMPLEMENTS,OVERRIDE,DECORATES,OF_TYPE], data_flow=[READS,WRITES,ASSIGNS_TO], control_flow=[CONTROL_FLOW,THROWS,CATCHES]. Застосовується лише як значення relationship_types за замовчуванням, коли relationship_types не передано. Узгоджено з параметром graph_view у dependency_search для консистентності.

path_filterНеобов'язковий

Тип: str
Опис: Обмежує розв'язання цільового символу за префіксом шляху файлу; повернені зв'язки графа можуть виходити за межі цього шляху

language_filterНеобов'язковий

Тип: str
Опис: Мовний фільтр

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

per_hop_limitНеобов'язковий

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

include_metricsНеобов'язковий

Тип: bool
За замовчуванням
Опис: Включайте показники графіка в результати, кожен з яких збагачений похідним блоком refactor_risk ({risk: "low"|"medium"|"high", is_articulation_point, bridge_count, k_core, graph_view, reasons}). risk є "low", якщо не є точкою артикуляції (у вибраному поданні), "medium", коли точка артикуляції об’єднує кілька країв, "high", коли об’єднує багато (евристичний поріг, не підтверджено емпірично). Опущено для кожного символу, якщо для цього символу/подання не існує рядка показників.

metrics_detailНеобов'язковий

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

include_edge_metadataНеобов'язковий

Тип: bool
За замовчуванням
Опис: Додайте необроблені метадані та ваги. Вимкнено за замовчуванням, оскільки метадані екстрактора можуть бути великими; Покриття збагачення повідомляється, коли ввімкнено.

exclude_test_pathsНеобов'язковий

Тип: bool
За замовчуванням: true
Опис: За замовчуванням true: виключити шляхи тесту, приладу, постачальника та прикладу з ребер повернутого графіка. Встановіть false, щоб включити їх.

include_module_symbolsНеобов'язковий

Тип: bool
За замовчуванням
Опис: За замовчуванням false виключає ребра графіка, якщо from_name або to_name є синтетичним символом __module__. Встановіть true для включення ребер на рівні модуля.

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

Найкраще підходить для:

Застарілі виклики, уже прив'язані до його форми відповіді (graph, connection_summary)

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

Нові агентні цикли — надайте перевагу dependency_search, який використовує те саме ядро обходу

get_task_contextСтабільно

Починаєте роботу в незнайомій частині коду? Опишіть завдання (наприклад, "додати підтримку SSO", "виправити webhook білінгу") та отримайте набір релевантного коду, символів і залежностей в одному виклику — контекст, який інакше довелося б збирати з кількох пошуків.

Параметри:

task_descriptionОбов'язковий

Тип: str
Опис: Опис завдання, для якого потрібен контекст

repositoryНеобов'язковий

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

limitНеобов'язковий

Тип: int
За замовчуванням: 15
Опис: Максимум елементів на шар

scopeНеобов'язковий

Тип: Literal[semantic, symbols, dependencies, all]
За замовчуванням: all
Опис: Які шари контексту включити

language_filterНеобов'язковий

Тип: str
Опис: Мовний фільтр

path_filterНеобов'язковий

Тип: str
Опис: Фільтр за префіксом шляху файлу

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

include_related_contextНеобов'язковий

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

seed_symbol_idsНеобов'язковий

Тип: list[str]
Опис: Явні затравки Tier‑1: ідентифікатори символів, які агент уже знає як центральні для завдання (наприклад, символи у відкритих файлах). Ранжуються вище за затравки, отримані з ключових слів, у шарах dependencies/related_context. Адитивні — пропустіть для сьогоднішньої поведінки лише за ключовими словами.

seed_file_pathsНеобов'язковий

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

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

Найкраще підходить для:

Контекст із урахуванням задачі, що поєднує початкові файли зі шарами семантики, символів і залежностей

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

Пошук одним інструментом, коли більш специфічний інструмент уже відповідає на питання

get_fileСтабільно

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

Параметри:

file_pathОбов'язковий

Тип: str
Опис: Шлях до файлу від кореня репозиторію

repositoryНеобов'язковий

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

line_startНеобов'язковий

Тип: int
Опис: Початкова рядок (нумерація від 1)

line_endНеобов'язковий

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

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

max_tokensНеобов'язковий

Тип: int
За замовчуванням: 5000
Опис: Максимум токенів для повернення

include_metadataНеобов'язковий

Тип: bool
За замовчуванням: true
Опис: Включати метадані файлу у відповідь

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

Найкраще підходить для:

Знімки віддалених або проіндексованих файлів (діапазони рядків, ліміти токенів)

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

Шлях, що вже є на локальному диску — використовуйте локальний інструмент Read

Системні та допоміжні інструменти#

repository_contextСтабільно

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

Параметри:

actionОбов'язковий

Тип: Literal[list, info]
Опис: Дія: list (перелік) або info (інформація про репозиторій)

repositoryНеобов'язковий

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

branchНеобов'язковий

Тип: str
Опис: Перевизначення гілки (застосовується тільки для цього виклику)

patternНеобов'язковий

Тип: str
Опис: Шаблон для фільтрації списку репозиторіїв

include_statisticsНеобов'язковий

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

limitНеобов'язковий

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

offsetНеобов'язковий

Тип: int
Опис: Застаріле зміщення сумісності. Віддайте перевагу cursor від pagination.next_cursor.

cursorНеобов'язковий

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

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

Найкраще підходить для:

Перелік доступних репозиторіїв
Визначення ідентичності репозиторію, гілки та актуальності HEAD відносно індексу

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

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

ask_maguyvaСтабільно

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

Параметри:

operationОбов'язковий

Тип: Literal[guidance, report_bug, request_feature, evaluate]
Опис: Основні: guidance, report_bug, request_feature. Лише застаріле/для сумісності: evaluate (детермінований рушій виразів; не є частиною основного робочого процесу агента).

queryНеобов'язковий

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

descriptionНеобов'язковий

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

related_toolНеобов'язковий

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

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

Найкраще підходить для:

Настанови щодо інструментів (operation="guidance")
Довготривалі звіти про помилки та запити функцій для супроводжувачів Maguyva

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

Обчислення з математикою/хешем/рядками — операція evaluate лише застаріла/для зворотної сумісності; надайте перевагу локальним обчисленням на хості

Найкращі практики#

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

Характеристики продуктивності#

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

Обробка помилок#

Усі методи API повертають структурований конверт відповіді:

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

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

Початок роботи#

Налаштуйте MCP-клієнт: Спрямувати MCP-клієнт на ендпоінт сервера Maguyva
Підтвердіть доступ до репозиторію: Використовуйте repository_context з action="list" або action="info", щоб переглянути репозиторії, доступні для API-ключа
Почніть пошук: Розпочніть з intelligent_search і за потреби переходьте до спеціалізованих інструментів
Комбінуйте інструменти: Поєднуйте кілька інструментів для повного аналізу коду

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