Аналитика кодовой базы через MCP: что умеет query_artifact_metadata

У CodeAlive есть инструмент query_artifact_metadata: через него агент запрашивает метрики и структуру индексированного кода. Например, находит функции с высокой когнитивной сложностью, которые вызываются из многих других функций, или считает среднюю сложность по namespace.

Для таких вопросов нужны рассчитанные метрики и граф вызовов. В CodeAlive они доступны через тот же MCP-сервер, которым агент пользуется для поиска и чтения исходников. Запрос задаётся на ArtifactQuery v1, небольшом SQL-подобном языке только для чтения.

Как это использует QA-агент

Один из наших клиентов сделал внутренний AI-инструмент для QA: он читает код через CodeAlive и пишет тест-кейсы к задаче. В диффе встречаются имена интерфейсов и DTO. Агент находит их объявления, читает поля и использует эти сведения при подготовке тест-кейсов.

Вот пример на основе этого сценария:

SELECT identifier, path, namespace, containing_typeFROM symbolsWHERE name = 'IParcelRouteWindowService'  AND symbol_kind IN ('class', 'record', 'interface', 'struct', 'enum')LIMIT 50

Известное имя найдётся и через grep. Здесь клиент использует запрос к символам, чтобы сразу получить объявления с путями и идентификаторами для следующего вызова fetch_artifacts. Если имя встречается в нескольких модулях, выбрать нужный помогают path и namespace.

С DTO вроде ParcelRouteWindowRequestDto порядок тот же: найти объявление, загрузить исходник, прочитать поля. Запрос к метаданным сам поля DTO не возвращает.

Вместе со statement агент передаёт data_sources: имена репозиториев или workspace из get_data_sources. Дальше во всех примерах используются эти же аргументы; пути нужно подставить из своего проекта.

Какие функции читать перед рефакторингом

В большой кодовой базе список самых длинных функций быстро становится малополезным. Для первого прохода можно задать более узкий критерий: высокая сложность и много прямых связей вызова одновременно.

SELECT identifier, path, name, complexity, incoming_calls_countFROM functionsWHERE path_under('src/')  AND has_body = true  AND is_test = false  AND complexity >= 15  AND incoming_calls_count >= 10ORDER BY complexity DESCLIMIT 20

Запрос выбирает до двадцати функций с реализацией, которые не отмечены как тесты, и сортирует их по сложности. Пороги 15 и 10 здесь для примера.

Такой список помогает начать разбор с функций, которые трудно читать и у которых много прямых вызывающих. Агент открывает их через fetch_artifacts, получает вызывающие функции через get_artifact_relationships и проверяет, какие сценарии нужно сохранить при рефакторинге.

Обычный поиск по имени функции этого списка не даст: сначала пришлось бы отдельно вычислить сложность, разрешить вызовы и сопоставить результаты. Инструмент использует уже собранные данные.

complexity в CodeAlive — оценка когнитивной нагрузки, а не цикломатическая сложность. incoming_calls_count считает прямые связи в индексе. По нему нельзя судить о частоте выполнения в продакшене или полном эффекте изменения.

Где сосредоточены зависимости модуля

Допустим, предстоит менять публичные методы платёжного модуля. Перед правкой можно посмотреть распределение их входящих связей по каталогам:

SELECT directory,       COUNT(*) AS public_functions_with_counts,       SUM(incoming_calls_count) AS direct_relationshipsFROM functionsWHERE path_under('src/Payments/')  AND is_public = true  AND has_body = true  AND is_test = false  AND incoming_calls_count >= 0GROUP BY directoryORDER BY direct_relationships DESCLIMIT 30

Эта сводка подсказывает, где сначала читать потребителей API. Для конкретных функций агент раскрывает связи и проверяет, затрагивает ли изменение соседние части системы. Затем можно определить границы PR.

Сумма связей не равна числу уникальных потребителей: одна функция может вызывать несколько методов выбранного модуля. А принадлежность к разным каталогам ещё не означает, что изменения независимы.

Другой срез того же кода — сложность по пространствам имён:

SELECT namespace,       COUNT(*) AS measured_functions,       AVG(complexity) AS avg_complexityFROM functionsWHERE path_under('src/')  AND has_body = true  AND is_test = false  AND complexity >= 0GROUP BY namespaceORDER BY avg_complexity DESCLIMIT 20

По нему можно выбрать модуль для следующего прохода ревью, а затем запросить отдельные функции в этом namespace. Число функций рядом со средним показывает размер выборки; конкретных кандидатов для правки выбирают после чтения кода.

Условие complexity >= 0 оставляет только функции с рассчитанной оценкой, включая нулевую. Без него COUNT(*) и AVG(complexity) могли бы описывать разные выборки. Функции без оценки можно проверить отдельно через complexity IS NULL.

Что ещё доступно в запросах

ArtifactQuery работает с files, symbols, functions и containers. В зависимости от сущности доступны размеры файлов и число строк, языки, типы и видимость символов, признаки теста и рекурсии, возвращаемые типы, счётчики ссылок и потомков. Поддерживаются фильтры, сортировка, группировки и агрегаты COUNT(*), AVG, MIN, MAX, SUM.

Не каждое поле допускает любую операцию. Инструмент get_artifact_query_schema возвращает актуальную схему и примеры, поэтому агенту не нужно угадывать названия полей и допустимые группировки.

Результат описывает выбранную область индекса: важны его свежесть, исключённые пути и поддержка языка. В каждом запросе обязателен LIMIT от 1 до 100. Он ограничивает строки или группы ответа; агрегаты считаются по всем совпадениям в выбранной области. Широкий запрос может не уложиться в бюджет выполнения, тогда нужно сузить каталог или условия.

Запросы к содержимому и переходы по графу выполняются отдельными инструментами. Их описание и способы подключения есть в документации CodeAlive MCP.