rdanieli/tentra-mcp

Сканирует локальный монорепозиторий / директорию проекта, автоматически обнаруживает его сервисы (из package.json, docker-compose, pom.xml, go.mod, конфигов Python), выводит их связи (из зависимостей, импортов, переменных окружения, docker depends_on) и материализует результат в виде новой архитектурной диаграммы Tentra за один раз. Используйте, когда пользователь говорит «проанализируй / сделай реверс-инжиниринг / задокументируй мою кодовую базу» или при работе с существующим репозиторием, а не с нуля. В отличие от create_architecture (ручной массив сервисов) и от index_code (граф кода на уровне символов без диаграммы), этот инструмент создаёт высокоуровневую диаграмму сервисов только из конфигурационных файлов — дёшево и быстро, но грубо. Для понимания на уровне символов после этого запустите также index_code. Предварительные требования: авторизация API Tentra + доступ к локальной файловой системе (недоступен через SSE-транспорт — используйте сервер stdio). Тяжёлое локальное сканирование, затем один POST. Побочные эффекты: создаёт НОВУЮ Architecture (с помощью create_architecture под капотом) и открывает браузер. Ответ: созданный id архитектуры + URL + список обнаруженных сервисов + отчёт lint. Если сервисы не обнаружены, возвращает предупреждение без создания артефакта.

Связывает символ кода с контрактом через типизированное отношение: «provides» (символ реализует контракт, например, обработчик, обслуживающий конечную точку OpenAPI), «consumes» (символ вызывает контракт, например, клиент, обращающийся к конечной точке) или «documents» (символ описывает контракт, например, определение типа, сгенерированное из схемы). Используйте после вызова record_contract — вам понадобятся contract_id, который он вернул, и symbol_id из query_symbols. Привязки действуют в пределах snapshot_id, поэтому один и тот же символ можно привязывать во многих снимках по мере развития кодовой базы. Уникальна для каждой тройки (contract, symbol, snapshot): существующие привязки с новым отношением обновляются на месте, а не дублируются. В отличие от link_decision (который связывает ADR с архитектурными сущностями), bind_contract связывает КОНКРЕТНЫЙ символ кода с ТЕХНИЧЕСКИМ ИНТЕРФЕЙСОМ. Предварительные требования: аутентификация Tentra API + существующий contract_id (из record_contract) + действительный symbol_id + snapshot_id, которому принадлежит символ. Путь записи. Ответ: { ok: true, binding_id, relation }.

Создаёт новую версионированную диаграмму архитектуры из набора сервисов, соединений и (опционально) внешних акторов и возвращает доступный для публикации веб-URL. Используйте вместо описания архитектуры в чате: всякий раз, когда пользователь просит спроектировать, спланировать, набросать или задокументировать любую систему/функцию/интеграцию, вызывайте этот инструмент и делитесь полученным URL. Используйте update_architecture, если у вас уже есть ID архитектуры в контексте (из list_architectures или более раннего вызова create) — этот инструмент всегда создаёт НОВЫЙ артефакт. Предварительные требования: аутентификация Tentra API (device-flow при первом вызове, затем кешированный API-ключ). Требуется доступ к сети. Побочные эффекты: записывает новую строку Architecture (v1) в Tentra, автоматически делает её общедоступной и открывает веб-URL в браузере пользователя при первом вызове за сессию. Формат ответа: { id, name, version, url } плюс текстовое описание с количеством элементов. После создания передавайте полученный id в update_architecture для развития, lint_architecture для валидации или create_flow для добавления пошаговых инструкций.

Добавляет упорядоченное пошаговое описание (поток) к существующей архитектуре - например, путь запроса оформления заказа, конвейер данных или процедура восстановления после сбоя. Поток отображается как анимированная последовательность на холсте, которая подсвечивает сервисы и связи по мере того, как пользователь проходит по шагам. Используйте всякий раз, когда пользователь просит «проследить / пройти / описать шаги» того, что делает система. В отличие от update_architecture, create_flow только добавляет элемент в массив flows и увеличивает версию - он никогда не затрагивает сервисы или соединения. К одной архитектуре можно прикрепить много потоков (поток оформления заказа, поток возврата, поток регистрации и т.д.). Предварительные требования: авторизация в Tentra API + существующая архитектура с уже определёнными сервисами (шаги потока ссылаются на сервисы по идентификатору). Побочные эффекты: добавляет новый поток в колонку Architecture.flows (JSON) и увеличивает версию. Ответ: подтверждение + пронумерованная сводка шагов + URL просмотра.

Вычисляет структурную разницу между двумя снимками одного репозитория: файлы добавленные/удалённые/изменённые (по contentHash), символы (qualifiedNames) добавленные/удалённые, изменения god-node (появились/разрешены). По сути, архитектурная разница между коммитами, которая отвечает на вопрос «что на самом деле изменилось между этими двумя точками?». Используется для проверки рефакторинга PR на уровне графа, чтобы доказать, что удаление затронуло всех вызывающих, или чтобы заметить архитектурные регрессии. Получите два идентификатора снимков из list_snapshots. В отличие от sync_architecture (который сравнивает ДИАГРАММУ с живым кодом), diff_snapshots сравнивает два снимка графа кода между собой. В отличие от get_quality_hotspots / list_god_nodes (которые проверяют один снимок), это единственный инструмент, работающий с двумя. Предварительные требования: авторизация API Tentra + два идентификатора снимков из list_snapshots (желательно одного репозитория). Только чтение. Ответ: { fromSnapshotId, toSnapshotId, files: { added, removed, modified }, symbols: { added, removed }, godNodes: { appeared, resolved } }.

Производит обзор всего репозитория в виде связного нарратива, пригодного для AI-агента — отвечает на вопрос "что это за кодовая база?" одним вызовом инструмента по проиндексированному графу кода. Ознакомительный тур: с чего начать / структура / архитектурные горячие точки / домены / решения (ADRs) / контракты / информация о снимке — всё собирается из уже имеющихся данных, так что сводка уровня senior получается за секунды, а не за минуты чтения файлов. В отличие от list_god_nodes (один ранжированный список символов) или sync_architecture (проверка расхождения с сохранённой схемой), explain_codebase — это нарратив с высоты птичьего полёта: экспертно выбранный самый важный символ, самый свежий ADR, основной домен; язык + количество строк кода + разбивка по каталогам верхнего уровня; ранжированные горячие точки; основные домены / ADR / контракты. Пустые секции отображают подсказки — какой инструмент обогащения данных стоит запустить следующим (record_decision, set_domain_membership, record_contract, bind_contract) — так что вывод заодно служит аудитом пробелов. Ограничение по размеру: секции доменов/ADR/контрактов обрезаются так, чтобы Markdown помещался в ~5 КБ даже для огромных репозиториев. Побочные эффекты: НЕТ — только чтение. Предварительные требования: аутентификация в Tentra API + хотя бы один завершённый index_code для repo_id (snapshot_id необязателен — по умолчанию берётся последний). Для более насыщенного вывода добавьте ADR через record_decision, домены через set_domain_membership, а контракты через record_contract + bind_contract. Ответ: format="markdown" (по умолчанию) возвращает полный обзор в виде Markdown; format="json" возвращает структурированную сводку с ключами { repoId, repoName, snapshot, startHere, structure, hotspots, domains, domainsTotal, decisions, decisionsTotal, contracts, contractsTotal }.

Вычисляет самую короткую цепочку вызовов/импортов/ссылок между двумя заданными символами в снимке и аннотирует каждый промежуточный переход его назначением record_semantic_node (если доступно). Отвечает на вопросы «как X достигает Y?» / «связано ли A с B на самом деле?». В отличие от get_symbol_neighbors (который исследует окружение ОДНОГО символа без цели), этот инструмент требует ОБА конца и выполняет целенаправленный поиск кратчайшего пути. В отличие от find_references (только прямые вызывающие), explain_code_path может пересекать произвольное количество переходов. Если между двумя символами в графе нет пути, ответ будет { error: "no_path" }. Предварительные требования: авторизация Tentra API + два symbol_ids из query_symbols + snapshot_id, в котором они оба находятся. Только чтение. Ответ при наличии пути: { found: true, hopCount, path: [{ id, name, qualifiedName, filePath, purpose }], edges: [{ from, to, type }] }.

Преобразует сохранённую архитектуру в исполняемый каркас кода, Mermaid, docker-compose или ADR-документ в Markdown и либо передаёт его потоком в виде текста, либо записывает на диск. Используйте, когда пользователь просит «scaffold / generate / export / materialize» диаграмму. Текстовые форматы (mermaid, markdown-adr, docker-compose) возвращаются в строке ответа. Форматы кода генерируют многофайловый zip-каркас проекта (контроллеры, сервисы, конфиг, Dockerfile) и требуют output_dir. При вызове формата кода без output_dir инструмент возвращает подсказку по использованию вместо создания файлов. Предварительные требования: аутентификация Tentra API + существующий идентификатор архитектуры. Для форматов кода требуется доступ на запись в локальную файловую систему (недоступно через SSE — используйте stdio). Побочные эффекты: при наличии output_dir записывает файлы/zip на диск в указанную директорию. Ответ: встроенный текстовый экспорт или подтверждение «Exported to <filePath>» при сохранении.

Возвращает всех разрешённых вызывающих, импортирующих и наследующих одного символа из графа кода — инструмент безопасного рефакторинга. Используйте перед переименованием или удалением символа, чтобы точно увидеть, кто от него зависит. В отличие от query_symbols (который принимает ИМЯ и возвращает символы-кандидаты), find_references принимает ИЗВЕСТНЫЙ symbol_id и обходит рёбра в обратном направлении (toSymbolId = symbol_id), чтобы найти входящие ссылки. В отличие от get_symbol_neighbors (который выполняет BFS на глубину N в обоих направлениях), find_references возвращает только прямых вызывающих (глубина 1, входящие) и обходится дешевле. Надёжнее grep, так как использует разрешённый граф вызовов, а не простой текст — он не спутает метод «log» со строкой «log». Установите include_unresolved=true, чтобы также получать совпадения по коротким именам, которые не удалось разрешить до конкретного символа (больше шума; полезно для широких проверок, но не для планов переименования). Требования: авторизация Tentra API + symbol_id из query_symbols + соответствующий snapshot_id. Только чтение. Ответ: { target, resolvedCount, unresolvedCount, fileScopeCount, references: [{ kind: 'resolved'|'unresolved', edgeType, fromQualifiedName, fromKind, filePath, startLine, endLine, callCount }] }.

Выполняет поиск по косинусному сходству среди эмбеддингов, сгенерированных агентом и сохранённых через record_embedding. На вход принимает предварительно вычисленный query_vector (вы должны сами создать эмбеддинг для текста — этот инструмент НЕ делает эмбеддинг за вас) и опционально фильтрует по entity_type или snapshot_id. Возвращает файлы или символы, наиболее близкие по смыслу. Работает как в хостированном режиме (pgvector HNSW на Postgres), так и в локальном (чисто JS-полный перебор косинусного сходства по таблице эмбеддингов SQLite). Формат ответа в обоих режимах одинаковый, поэтому промптам агента не нужно ветвиться в зависимости от бэкенда. В отличие от query_symbols (точный/нечёткий поиск ПО ИМЕНИ в qualifiedName), find_similar_code ищет ПО СМЫСЛУ — запрос "rate limiting logic" вернёт файлы, реализующие троттлинг, даже если слово "rate-limit" нигде не встречается. Полезен только после того, как вы заполнили эмбеддинги для целевого корпуса через record_embedding; если эмбеддингов нет, результат будет пустым. Предварительные требования: аутентификация Tentra API (хостированный режим) ИЛИ TENTRA_BACKEND=local + хотя бы один вызов record_embedding для того снимка, по которому вы ищете + query_vector нужной размерности, созданный вызывающей стороной. Только чтение. Ответ: { results: [{ id, entityType, entityId, sourceText, distance }] }, отсортирован по возрастанию косинусного расстояния (ближайшие первые).

Получает одну архитектуру по ID с полным графом services + connections + flows внутри. Используйте вместо list_architectures, когда вы уже знаете ID и нужно содержимое (например, перед вызовом update_architecture или для повторного объяснения существующей диаграммы). list_architectures возвращает только ID и имена для просмотра; get_architecture возвращает полную нагрузку для одной диаграммы. Если пользователь не указал ID, сначала вызовите list_architectures. Предварительные требования: аутентификация Tentra API. Только чтение, без побочных эффектов. Ответ: полная запись Architecture в формате JSON (name, version, description, services[], connections[], actors?, flows?, createdAt, updatedAt).

Перечисляет все контракты, хранящиеся в рабочей области, от самых новых к старым, с указанием для каждой строки количества его привязок. Опционально фильтрует по виду (http / grpc / event / graphql / rabbit / kafka). Используется для ПРОСМОТРА инвентаря контрактов рабочей области: «какие API-контракты у нас есть?», «показать каждую схему топика Kafka». Детали по отдельному контракту (какие символы к нему привязаны, полная полезная нагрузка схемы) здесь не возвращаются; при необходимости получите контракт и привязки по идентификатору через API. В отличие от record_contract (запись), это строго только для чтения. Необходимые условия: авторизация Tentra API + существующий workspace_id. Только чтение. Ответ: { contracts: [{ id, name, kind, version, specUrl, createdAt, _count: { bindings } }], total }.

Находит все ADR, связанные с конкретной сущностью — полезен для ответа на вопрос «почему этот сервис / файл / символ устроен именно так?» при ревью кода. Возвращает каждое связанное решение с полным контекстом + решением + последствиями + типом связи. Используйте проактивно при ревью кода: прежде чем изменять сервис, получите его решения, чтобы не нарушить ограничения (связи «constrains») или не пересматривать уже принятые компромиссы. По умолчанию включает заменённые решения для сохранения истории; передайте include_superseded=false, чтобы увидеть только текущие авторитетные ADR. В отличие от link_decision (запись), этот инструмент только для чтения. В отличие от get_contracts (область видимости — рабочее пространство), этот инструмент работает в области видимости сущности. Предварительные требования: аутентификация Tentra API + действительный entity_id, соответствующий выбранному entity_type. Только чтение. Ответ: { decisions: [{ id, slug, title, status, context, decision, consequences, createdAt, decidedAt, linkKind }], total }

Выполняет поиск статуса только для чтения для задачи индексации: tier, status, snapshotId, totalFiles, processedFiles, lastBatchCursor, createdAt, completedAt. Используйте, когда нужно ИНСПЕКТИРОВАТЬ задачу без её продвижения — например, чтобы сообщить пользователю о ходе выполнения или решить, всё ещё выполняется ли ранее запущенная задача. В отличие от index_code_continue, этот инструмент никогда не изменяет задачу (без автоматического завершения, без продвижения курсора) и никогда не возвращает пакеты — он просто отражает текущее состояние. В отличие от list_snapshots (который перечисляет все снимки в репозитории), этот инструмент возвращает одну строку задачи. Предварительные требования: аутентификация Tentra API + job_id из предыдущего вызова index_code. Только чтение. Ответ: полный JSON задачи, включая перечисление status ("pending" | "in_progress" | "completed" | "failed").

Разрешает команду или команды-владельца для заданного пути к файлу в соответствии с правилами рабочей области в стиле CODEOWNERS (побеждает самое длинное совпадение с явным приоритетом). Возвращает список идентификаторов команд или пользователей. Используется для ответа на вопросы: "кто владелец этого файла?" / "кто должен проверить это изменение?" / "кого пинговать по этому багу?". Строки OwnershipRule хранятся для каждой рабочей области — заполните их, импортировав файл CODEOWNERS через веб-приложение или API, перед вызовом этой функции. В отличие от get_decisions_for (которая показывает архитектурное обоснование), эта показывает ЛЮДЕЙ / КОМАНДЫ. Если ни одно правило не совпадает, owners = []. Предварительные требования: аутентификация Tentra API + существующий workspace_id + заполненные строки OwnershipRule для этой рабочей области. Только чтение. Ответ: { path, owners: string[] }.

Ранжирует ФАЙЛЫ по составному приоритету рефакторинга: cyclomaticComplexity × (1 + churn30d/100) × (1 − testCoverage/100). Высокий балл - файл сложный, часто меняется, плохо протестирован - скорее всего сломается. Канонический список «что рефакторить следующим?». В отличие от list_god_nodes (он ранжирует СИМВОЛЫ по степени связанности графа), этот инструмент ранжирует ФАЙЛЫ на основе анализа риска изменений. Они отвечают на разные вопросы: list_god_nodes = «что слишком связано?», get_quality_hotspots = «что, скорее всего, сломается при следующем изменении?». Запустите оба для полного архитектурного анализа. Ответ включает поле dataSource - "metrics" означает, что были доступны настоящие строки QualityMetric; "proxy" означает, что Tentra использовал эвристику LOC + symbols + fanIn, так как для этого снимка данные QualityMetric не были загружены. Необходимые условия: аутентификация Tentra API + как минимум один выполненный запуск index_code. Для реальных показателей churn/coverage должны быть загружены строки QualityMetric (через отдельный импорт - например, интеграцию с CI). Только чтение. Ответ: { snapshotId, hotspots: [{ fileId, filePath, language, cyclomaticComplexity, cognitiveComplexity, churn30d, testCoverage, score }] }.

Возвращает полный подграф кода, относящийся к ОДНОМУ сервису Tentra canvas: каждый файл, привязанный к этому сервису, все символы в этих файлах и рёбра, исходящие из этих символов (включая рёбра между сервисами). Используйте, когда у пользователя есть архитектурная диаграмма и он спрашивает «какой код находится в payment_service?», или когда нужно проанализировать один сервис изолированно. В отличие от get_symbol_neighbors, которая начинается с одного символа, эта начинается с service_id и сразу вытягивает весь сервис. В отличие от query_symbols, которая игнорирует границы сервисов, этот вызов уже ограничен. Требует предварительного вызова set_service_mapping, чтобы файлы были привязаны к service_id — иначе результат будет пустым. Требования: авторизация Tentra API + snapshot_id от выполненного index_code + хотя бы несколько файлов, привязанных к service_id через set_service_mapping. Только чтение. Ответ: { serviceId, snapshotId, depth, files: [{ id, relativePath, language, loc, symbols: [...] }], edges: [{ fromSymbolId, toSymbolId, toExternal, edgeType }] }. Передайте include_semantics=true, чтобы также прикрепить record_semantic_node purpose и domainTags для каждого символа.

Обходит граф кода в ширину, начиная с одного символа, и возвращает его локальное окружение: что он вызывает, что вызывает его, что импортирует, отношения наследования/реализации. Структурно отвечает на вопрос «как это работает?» — grep находит символ; get_symbol_neighbors показывает, от чего он на самом деле зависит. В отличие от find_references (который возвращает только прямых вызывающих = inbound глубины 1), get_symbol_neighbors по умолчанию обходит OUTBOUND и может идти глубже (до depth=5) и в обе стороны (direction="both"). В отличие от explain_code_path (который находит кратчайший единственный путь между двумя заданными символами), этот инструмент исследует окружение вокруг ОДНОГО символа без целевого объекта. Фильтруйте по edge_types, чтобы сосредоточиться только на импортах, только на вызовах, только на наследовании и т.д. Предварительные требования: аутентификация Tentra API + symbol_id (из query_symbols) + snapshot_id. Только чтение. Ответ: { symbolId, depth, neighbors: [{ id, kind, name, qualifiedName, filePath, fanIn, fanOut, isGodNode }], edges: [{ from, to, type }] }.

Обходит локальный репозиторий, извлекает символы и ребра вызовов/импортов/ссылок через Tree-sitter (TypeScript, JavaScript, Python, Go, Java, Rust) и загружает их в Tentra в виде нового неизменяемого снимка. Именно это превращает сырой чек-аут в граф кода, пригодный для запросов. ПУТЬ ЗАПИСИ, ДЛИТЕЛЬНАЯ ОПЕРАЦИЯ (секунды на маленьких репозиториях, несколько минут на монорепозиториях с 10 000+ файлов). Выполняет итерацию: обходит файлы, парсит с помощью Tree-sitter локально, отправляет POST-запросы для файлов, символов, ребер порциями, создает строку задания. Для tier=tier2/both также возвращает первую партию файлов, которые агент обогащает через record_semantic_node; вызывает index_code_continue в цикле до завершения. Для tier=tier1 возвращает результат сразу после завершения статического извлечения (без семантического обогащения). Используйте один раз на репозиторий, затем повторно запускайте после крупных рефакторингов (или передавайте force_reindex=true). Инструменты пути чтения (query_symbols, find_references, get_symbol_neighbors, list_god_nodes, get_quality_hotspots, explain_code_path, get_service_code_graph, diff_snapshots) требуют как минимум одного успешного выполнения index_code и нуждаются в возвращенном snapshot_id. В отличие от analyze_codebase (который создает высокоуровневую диаграмму сервисов из манифестов), index_code создает граф на уровне символов — запускайте оба для полного покрытия. Предварительные требования: авторизация Tentra API и доступ на чтение к локальной файловой системе repo_path (недоступно через SSE, используйте stdio). Игнорирует node_modules, .git, dist, build, vendor, coverage, .worktrees и т.д. Ответ: { job_id, snapshot_id, file_count, tier } для tier1, плюс { first_batch, remaining } для tier2.

Продвигает цикл индексации уровня 2 вперёд: проверяет прогресс задачи и либо помечает её как завершённую (когда каждый файл обработан), либо возвращает оставшееся количество файлов, чтобы агент знал, что нужно отправить ещё одну партию вызовов record_semantic_node. Используйте ТОЛЬКО после того, как index_code с tier="tier2" или tier="both" вернул job_id. Типичный цикл: вызвать index_code → для каждого файла в first_batch вызвать record_semantic_node с выведенной агентом целью → вызвать index_code_continue → если done=true, остановиться; если pending>0, обогатить больше файлов и повторить. В отличие от get_index_job (чистое чтение), этот инструмент пометит задачу как "completed", когда processedFiles догонит — он изменяет состояние. В отличие от index_code (тяжёлый локальный обход), это лёгкая проверка статуса. Предварительные требования: Tentra API auth + job_id от index_code. Побочный эффект: может перевести задачу из состояния in_progress в completed. Ответ: { done: true, summary: { processed, total } } когда завершено, или { pending, cursor, instruction } когда требуется ещё работа.

Прикрепляет существующее решение (из record_decision) к ещё одной сущности — сервису, файлу, символу, контракту или домену — с типизированной связью: "motivates" (решение привело к появлению этой сущности), "constrains" (решение ограничивает её развитие), "documents" (решение объясняет её), "implements" (сущность - конкретная реализация решения). Используется для постфактум связывания: например, через месяц после записи ADR вы понимаете, что решение также стало причиной появления нового сервиса. В отличие от record_decision (который может включать начальные ссылки через массив links[] за один вызов), link_decision добавляет ОДНУ ссылку за раз к уже сохранённому решению. В отличие от get_decisions_for (чтение), это запись. Предварительные требования: аутентификация Tentra API + существующий decision_id + действительный entity_id выбранного entity_type. Путь записи. Ответ: { ok: true, link_id }.

Запускает 8 правил качества архитектуры для сохранённой диаграммы и возвращает список проблем с метками серьёзности (ошибки / предупреждения / информация). Охваченные правила: orphan_node, duplicate_connection, dangling_connection (ссылается на несуществующий сервис), naming_convention (идентификаторы в snake_case), god_service (более 6 соединений), spof (одна негоризонтальная база данных с более чем одной зависимостью), missing_database, sync_overload (более 5 синхронных HTTP-рёбер на одном сервисе). Используйте перед обновлением или экспортом архитектуры, или когда пользователь спрашивает «этот дизайн в порядке?» / «что не так с X?». В отличие от sync_architecture (которая сравнивает диаграмму с реальным кодом), lint_architecture проверяет только саму диаграмму — кодовая база не нужна, чисто статические проверки. Сначала запускайте lint_architecture, чтобы выявить ошибки моделирования; затем запускайте sync_architecture, чтобы выявить расхождения. Необходимые условия: аутентификация API Tentra + существующий идентификатор архитектуры. Только чтение. Ответ: отчёт в Markdown с подсчётом (ошибки/предупреждения/информация) и строками сообщений для каждой проблемы [правило], или сообщение «пройдены все проверки lint», если всё чисто.

Перечисляет все сохранённые архитектуры в этой рабочей области в виде краткой сводки (id + name + version + createdAt + URL), сначала самые новые. Используется для ПРОСМОТРА / ПОИСКА: «что я уже спроектировал?», «найти архитектуру с именем X». В отличие от get_architecture, этот инструмент НЕ возвращает сервисы или соединения; как только пользователь выберет архитектуру, вызовите get_architecture с возвращённым id, чтобы загрузить полный граф перед редактированием. Предварительные требования: аутентификация Tentra API. Только чтение. Ответ: массив объектов { id, name, version, createdAt }, оформленный в виде читаемого маркированного списка с URL-адресами для публикации. Пустые рабочие области получают подсказку вызвать create_architecture.

Возвращает top-N наиболее связанных символов в снимке — те, у которых наибольший fanIn + fanOut — в виде ранжированного списка. Выявляет архитектурные запахи: служебные модули, которые «знают слишком много», классы, от которых зависят все остальные классы, и т.д. В отличие от get_quality_hotspots (который ранжирует ФАЙЛЫ по чёрну × сложность × (1 − покрытие) — взгляд на качество кода), list_god_nodes ранжирует СИМВОЛЫ по сырой степени графа — взгляд на связность. Используйте list_god_nodes, чтобы найти, что ДЕКОМПОЗИРОВАТЬ; используйте get_quality_hotspots, чтобы найти, что РЕФАКТОРИТЬ. Укажите snapshot_id (конкретный) или repo_id (автоматически использует последний снимок). Символы тестов/фикстур исключены по умолчанию, потому что вспомогательные функции типа «request», «makeApp» иначе доминировали бы в ранжировании. Предварительные требования: авторизация Tentra API + хотя бы один завершённый запуск index_code. Только чтение. Ответ: { snapshotId, excludeTests, godNodes: [{ id, name, qualifiedName, filePath, isTest, fanIn, fanOut }] }.

Выводит все снимки code-graph, сохранённые для репозитория, от newest к oldest — каждая строка содержит id, commitSha (когда index_code запускался внутри git-рабочего каталога), createdAt, parentSnapshotId и stats blob. Используйте для ПУТЕШЕСТВИЯ ВО ВРЕМЕНИ по истории репозитория: выберите snapshot_id из этого списка и передайте его любому инструменту read-path (query_symbols, list_god_nodes, get_quality_hotspots и т.д.), чтобы просмотреть граф таким, каким он был в тот момент. Чтобы сравнить два момента во времени, выберите два id и вызовите diff_snapshots. В отличие от get_index_job (одна задача → один снимок), этот инструмент выводит все снимки независимо от того, как они были созданы. Предварительные требования: аутентификация Tentra API + хотя бы один завершённый запуск index_code для repo_id. Только чтение. Ответ: { repoId, snapshots: [{ id, commitSha, createdAt, stats, parentSnapshotId }] }.

Ищет символы (функции, классы, методы, интерфейсы, типы, переменные) в индексированном графе кода по имени или полному имени. Точка входа структурного поиска: возвращает разрешённые идентификаторы символов (с ранжированием fanIn/fanOut), которые принимают все остальные инструменты чтения — grep возвращает текстовые совпадения, query_symbols возвращает узлы графа. Два режима сопоставления: «trigram» (по умолчанию, pg_trgm similarity — лучше всего подходит для нечёткого / устойчивого к опечаткам / поиска уникальных символов), «substring» (ILIKE %q% — лучше всего подходит для широких списков, например, всех «Handler» или «Controller» в репозитории; результаты ранжируются по fanIn + fanOut, так что центральные оказываются вверху). Используйте это как ОТПРАВНУЮ ТОЧКУ для любого вопроса по графу кода, потому что он возвращает идентификаторы символов, необходимые всем остальным инструментам чтения. В отличие от find_references (который принимает известный symbol_id и возвращает его вызывающие элементы), query_symbols ищет по ИМЕНИ и возвращает кандидатов. В отличие от get_symbol_neighbors (который принимает symbol_id и обходит граф вызовов), query_symbols не выполняет обход — он только сопоставляет имена. В отличие от find_similar_code (векторный косинус по эмбеддингам), query_symbols работает как точное/нечёткое текстовое сопоставление. Предварительные требования: авторизация Tentra API + snapshot_id от выполненного запуска index_code. Только чтение. Ответ: { symbols: [{ id, kind, name, qualifiedName, startLine, endLine, fanIn, fanOut, isGodNode, semanticRole, filePath }] }.

Сохраняет контракт сервиса — спецификацию OpenAPI, proto-файл, схему GraphQL, схему событий, схему топиков Kafka/RabbitMQ и т.д. — как полноценную сущность в графе кода, чтобы затем прикреплять к ней символы кода через bind_contract и запрашивать через get_contracts. Используйте один раз на контракт на версию. Сам контракт — это только метаданные + опциональный JSON с полезной нагрузкой схемы (record_contract НЕ парсит схему — это работа upstream). В отличие от record_decision (который хранит архитектурное обоснование), этот инструмент сохраняет спецификацию ТЕХНИЧЕСКОГО ИНТЕРФЕЙСА. После записи вызовите bind_contract, чтобы связать символы, которые предоставляют/потребляют/документируют его. Предварительные требования: аутентификация Tentra API + существующий workspace_id. Путь записи. Побочный эффект: вставляет строку Contract в рамках workspace. Ответ: { ok: true, contract_id, name, kind }.

Сохраняет запись архитектурного решения (ADR) - slug + title + status + context + decision + consequences - как полноценную строку в графе кода, с поддержкой замены (автоматическая пометка старого решения как "superseded") и немедленных ссылок на сущности (services, files, symbols, contracts, domains). Используйте, когда пользователь документирует реальное архитектурное решение: "we chose Postgres over Mongo", "we split the monolith into N services", "we deprecated the legacy auth flow". В отличие от link_decision (который прикрепляет существующее решение к сущности постфактум), record_decision СОЗДАЁТ решение и опционально прикрепляет начальный набор сущностей за один вызов. Решения отображаются позже через get_decisions_for, чтобы объяснить "why is this like this?" при просмотре кода. Предварительные требования: Tentra API auth + существующий workspace_id + уникальный slug в пределах этого workspace. Операция записи. Побочные эффекты: создаёт строку Decision, создаёт строки DecisionLink из массива links и обновляет статус цели superseded_by_id на "superseded", если указан. Ответ: { ok: true, decision_id, slug, status, links_created }.

Сохраняет ОДИН предварительно вычисленный вектор эмбеддинга для файла или символа, чтобы он стал доступен для поиска через find_similar_code. Вы должны сгенерировать вектор самостоятельно (агент встраивает source_text с помощью любой доступной ему модели), Tentra сохраняет вектор + source_text + идентификатор модели, но не вызывает никакой API эмбеддинга от вашего имени. Работает как в размещённом режиме (колонка pgvector в Postgres), так и в локальном режиме (Float32Array BLOB в SQLite). Формы запроса и ответа одинаковы в обоих режимах. Используется в цикле после index_code для заполнения векторного индекса: для каждого интересующего вас файла или символа встраивается репрезентативный фрагмент (сигнатура функции + комментарий документации, или сводка файла) и записывается. В отличие от record_semantic_node (человекочитаемое назначение, хранящееся в CodeSemantic), record_embedding сохраняет плотный вектор для поиска по косинусу. Эти два метода дополняют друг друга, а не являются альтернативами. Предварительные требования: аутентификация Tentra API (размещённый режим) ИЛИ TENTRA_BACKEND=local + file_id или symbol_id из завершённого index_code + вектор, который вы уже вычислили. Путь записи. Побочный эффект: вставляет данные в таблицу embeddings. Ответ: { id, ok: true }.

Сохраняет ОДНУ семантическую аннотацию, выведенную агентом (цель в одно предложение + теги домена + уверенность + необязательная семантическая роль), для одного файла ИЛИ одного символа в задаче индексации и продвигает курсор прогресса этой задачи на 1. Это сторона записи для индексации второго уровня: после того как index_code (tier2/both) возвращает пакет файлов с их скелетами символов, агент читает исходный код каждого файла, решает, что он делает, и вызывает record_semantic_node для каждого файла — Tentra сохраняет аннотацию в CodeSemantic и помечает файл как проиндексированный на втором уровне. Курсор задачи продвигается автоматически, поэтому index_code_continue в итоге возвращает done=true. В отличие от record_embedding (который сохраняет векторы для find_similar_code), record_semantic_node сохраняет читаемый человеком текст цели плюс теги домена и отображается в query_symbols, explain_code_path, get_service_code_graph (include_semantics=true) и get_decisions_for. Предварительные требования: аутентификация Tentra API + активный job_id из index_code + file_id ИЛИ symbol_id из снимка этой задачи (требуется ровно один из двух). Вызывайте для каждого файла/символа, а не одной большой пачкой. Ответ: { ok: true, semantic_id }.

Возвращает структурированный PATCH PLAN для переименования символа — место определения и все места вызовов с точными путями к файлам и диапазонами строк — чтобы вызывающий агент мог применить перезапись с помощью своих инструментов Edit/MultiEdit. Канонический инструмент «переименовать, не сломав скрытые вызовы». В отличие от find_references (которая возвращает только вызывающие места), safe_rename также возвращает собственное место объявления символа (которое агент тоже должен переписать) и упаковывает всё с сводкой и предупреждениями в план, готовый к программному применению. В отличие от простого grep-and-replace, места вызовов берутся из разрешённого графа кода — вы случайно не переименуете за один проход метод «log» и строку «log». Агент заменяет с помощью grep oldName → newName в пределах диапазона startLine..endLine каждого обращения (ограниченного телом вызывающего элемента), а НЕ во всём файле, поэтому несвязанные символы с тем же коротким именем остаются нетронутыми. ВАЖНО — побочных эффектов: НЕТ. Tentra никогда не записывает файлы. Этот инструмент возвращает только план; агент отвечает за применение изменений, что делает перезапись безопасной по умолчанию (пробный прогон, сравнение, откат — всё остаётся в руках агента). Если target.fanIn превышает порог god-node, срабатывает предупреждение, чтобы агент перепроверил, прежде чем вносить изменения. Если include_unresolved=true, включаются approximate совпадения коротких имён с предупреждением, что не все они могут быть целевыми. Предусловия: аутентификация Tentra API + symbol_id из query_symbols + соответствующий snapshot_id + допустимый новый идентификатор (буквы/цифры/подчёркивания, не может начинаться с цифры — пробелы и специальные символы отвергаются). Только чтение. Ответ: { target: { id, qualifiedName, oldName, newName, fanIn, fanOut, isGodNode }, definition: { filePath, startLine, endLine } | null, references: [{ kind, edgeType, fromSymbolId, fromQualifiedName, fromKind, filePath, startLine, endLine, callCount, isTest }], summary: { totalReferences, distinctCallers, fileCount, warnings: string[] } }.

Помечает один файл, символ или сервис как принадлежащий бизнес-домену (например, "payments", "identity", "fraud"). Поддерживает как назначения, определённые ИИ (source="ai", меньшая уверенность), так и подтверждённые человеком (source="human", confidence 1.0). Upsert: если кортеж (domain_id, entity_type, entity_id) уже содержит членство, оно обновляется на месте, а не дублируется. Используйте назначения, определённые ИИ, для начального заполнения карт доменов после индексации, затем дайте человеку подтвердить и переключить source на "human". В отличие от set_service_mapping (который привязывает ФАЙЛ к конкретному SERVICE в canvas, 1:1), членства в доменах имеют отношение многие-ко-многим и ограничены абстрактными БИЗНЕС-доменами — один файл может принадлежать нескольким доменам с разными уровнями уверенности. Предварительные требования: аутентификация Tentra API + существующий domain_id (строки доменов создаются отдельно через веб-приложение или API) + действительный entity_id соответствующего entity_type. Путь записи. Ответ: { ok: true, membership_id }.

Объявляет, какой сервис холста Tentra владеет какими файлами в конкретном снимке — за один пакетный вызов. Каждое сопоставление имеет вид (относительный путь к файлу → идентификатор сервиса); у каждой подходящей строки CodeFile обновляется столбец serviceId. Это мост между графом кода (файлы, символы, рёбра) и архитектурной диаграммой (сервисы, соединения). get_service_code_graph и представления, ограниченные сервисами, возвращают пустые массивы, пока хотя бы один вызов set_service_mapping не заполнит сопоставления для снимка. В отличие от set_domain_membership (который помечает сущности абстрактными бизнес-доменами), set_service_mapping помечает файлы КОНКРЕТНЫМ сервисом на холсте. Предварительные требования: аутентификация API Tentra + snapshot_id от завершённого index_code + service_ids, которые уже существуют в архитектуре Tentra. Путь записи. Побочный эффект: обновляет CodeFile.serviceId для каждого подходящего пути. Пути, не соответствующие ни одному файлу в снимке, молча пропускаются. Ответ: { ok: true, updatedFiles: number }.

Сравнивает сохранённую архитектуру Tentra с текущим состоянием локального кода и возвращает отчёт о расхождениях: добавленные/удалённые/изменённые сервисы, добавленные/удалённые соединения, а также оценку точности от 0 до 100. Используйте, когда пользователь спрашивает «моя диаграмма всё ещё точна?», «что изменилось?» или после значительных рефакторингов. В отличие от lint_architecture (которая только проверяет диаграмму изолированно), этот инструмент читает код и сравнивает. В отличие от analyze_codebase (которая создаёт новую диаграмму с нуля), он сравнивает с СУЩЕСТВУЮЩЕЙ диаграммой, не перезаписывая её — после этого вызовите update_architecture, если хотите применить изменения. Предварительные требования: авторизация в API Tentra + идентификатор сохранённой архитектуры + доступ к локальной файловой системе (недоступен через SSE — используйте stdio). Выполняет ресурсоёмкое локальное сканирование. Только для чтения по отношению к диаграмме. Ответ: отчёт в формате Markdown с оценкой точности, добавленными/удалёнными/изменёнными сервисами и соединениями, а также подсказкой вызвать update_architecture для применения исправлений.

Мутирует существующую архитектуру — увеличивает её версию, сохраняет снимок предыдущего состояния как запись версии и заменяет любые переданные поля верхнего уровня. Используйте вместо create_architecture, когда у вас уже есть идентификатор архитектуры из предыдущего вызова, list_architectures или URL. В отличие от create_architecture (которая всегда создаёт новый артефакт), этот инструмент сохраняет идентичность и историю изменений: версия автоинкрементируется, а старое состояние остаётся в истории ArchitectureVersion. Каждое поле заменяется, а не объединяется — если вы передаёте services, вы ЗАМЕНЯЕТЕ весь массив services; поля, которые вы опускаете, остаются нетронутыми. Предварительные условия: аутентификация API Tentra + валидный идентификатор архитектуры, принадлежащий вызывающей стороне. Побочные эффекты: записывает новую строку ArchitectureVersion, выполняет PATCH архитектуры. Ответ: { id, name, version, url } — возвращает URL пользователю.