Перевод английского нормативного контракта, сверенный с оригиналом в ревизии 61e75e9aa9a8719dfb480bf1f5226553b3a21d70. Перевод не является новой редакцией спецификации.
search_concepts и get_neighbors — инструменты чтения одного загруженного снимка набора документов. Их JSON Schema в internal/mcpserver/contracts/, включённые в репозиторий, задают контракт обмена данными. Каждый вызов использует те же правила закрепления корневого каталога, обработки ошибок разбора, проверки входных данных, оформления ошибок и ограничения размера ответа, что и ранее существовавшие MCP-инструменты.
Обязательные входные поля: bundle_path и query, содержащий хотя бы один непробельный символ. Значение limit по умолчанию — 20; допустимый диапазон — 1–100. Совпадение определяется буквальным вхождением подстроки после приведения регистра Unicode и нормализации NFC. Это не поиск по отдельным словам, неточным совпадениям, смыслу или векторам. Понятие подходит, если запрос встречается в его каноническом идентификаторе, заголовке, описании, тегах или Markdown-тексте. Поле match определяется совпавшим полем с наивысшим приоритетом: идентификатор, заголовок, описание, теги, текст. Результаты сортируются по этому приоритету, затем по каноническому идентификатору понятия. total содержит число всех совпадений; hits — не более limit результатов; truncated сообщает о пропущенных результатах.
Обязательные входные поля: bundle_path и канонический concept_id. Значение direction по умолчанию — both; kinds — navigation, relation и source; limit — 20, допустимый диапазон — 1–100. navigation обозначает разрешённые Markdown-ссылки на понятия, включая относительные пути и пути от корня набора. relation обозначает разрешённые типизированные рёбра расширения relations; поля from/to сохраняют экранированные идентификаторы понятий и фрагментов, определённые парсером, а relation_type содержит объявленный тип. Неработающие ссылки и неразрешённые отношения исключаются. source обозначает записи происхождения sources[].resource; они возвращаются в sources, а не как рёбра между понятиями. Псевдоссылки внутри кода исключаются Markdown-парсером.
total считает выбранные рёбра между понятиями до применения ограничения; edges содержит не более limit рёбер; truncated сообщает о пропущенных рёбрах. Рёбра сортируются по виду, идентификатору исходной вершины, идентификатору целевой вершины, затем по типу отношения. Источники происхождения имеют исходящее направление и появляются только при out или both; они сортируются по идентификатору, ресурсу и заголовку. Более 100 источников происхождения приводит к resource_limit, а не к их молчаливому отбрасыванию. Запрос отклоняет окрестность с более чем 100 000 потенциальных рёбер. В v1 нет курсора или постраничной выдачи: вызывающая сторона может сузить направление и виды связей либо использовать существующий инструмент графа для полного обхода.
Начните с search_concepts, используя характерную буквальную подстроку из вопроса. Если truncated равен true, посмотрите total, при необходимости увеличьте limit до 100 или задайте более точный буквальный запрос по идентификатору, заголовку, тегу или фразе. Запрос — одна подстрока, а не выражение AND. Прочитайте только выбранные идентификаторы через read_concept, затем запросите их соседей через get_neighbors с ограниченной выдачей. Понятие за пределами первых результатов широкого запроса остаётся доступным по каноническому идентификатору и может быть найдено характерным запросом. Если слова для поиска неизвестны, list_concepts позволяет получить идентификаторы, но возвращает весь список, который может быть большим; это не страница и не курсор. Не утверждайте, что пропущенный результат был просмотрен.
Если список соседей усечён, отфильтруйте direction и kinds, увеличьте limit до 100 или используйте get_semantic_graph, если задача требует полного обхода и его результат укладывается в ограничение размера. total/truncated относятся к рёбрам между понятиями; источники происхождения sources — отдельная группа со своим жёстким пределом в 100 записей. Если набор результатов невозможно сузить, а весь граф превышает ограничение размера ответа, v1 не позволяет перечислить пропущенные результаты. Сообщите об ограничении вместо утверждения о полноте. Курсор или чтение диапазона потребовали бы отдельного контракта, сначала описанного схемой и охватывающего порядок, привязку к снимку, корневой каталог, срок действия и отмену.
Текущие ограничения сервера: загрузка не более 10 000 файлов и 10 000 понятий; суммарно 64 МиБ данных набора; 64 МиБ на структурированный JSON-ответ или совместимый текстовый ответ; 16 МиБ на содержимое чтения понятия и на каждый способ отображения графа; 1 МиБ на метаданные понятия; для поиска и соседей — 20 результатов по умолчанию и максимум 100; 100 источников происхождения на выбранное понятие; 100 000 потенциальных рёбер соседей. resource_limit означает неуспешный вызов, а не частичную страницу. Если набор превышает предел файлов или понятий, его необходимо уменьшить: уточнение запроса не позволяет обойти загрузку. Отмена контекста также завершает вызов ошибкой без частичного успеха. Совместимый текстовый вариант сохраняется вместе со структурированным содержимым и в зависимости от инструмента может быть меньше или больше него.
Значение temporal_profile по умолчанию — date-3fcbb9f. Его as_of должно быть датой YYYY-MM-DD. Явно выбранный instant-0b87c52 требует дату и время RFC3339 с известным смещением UTC. Ответ повторяет профиль и опорное время. Каждая карточка понятия независимо сообщает статус, состояние статуса, доверие, срок устаревания и признак устаревания. Без as_of значение stale равно null. Если срок устаревания отсутствует или не разбирается, результат также null, а не выдуманное утверждение об актуальности.
Загрузка набора ограничена 10 000 понятиями и существующими ограничениями MCP на объём данных. Ответы поиска и соседей проверяются по схеме и ограничиваются общим бюджетом размера MCP-ответа. Отмена контекста возвращает ошибку, а не частичный успех. Имена и контракты существующих девяти инструментов сохраняются; сервер также содержит пару предварительного просмотра и применения обновления временного профиля и дополнительный инструмент search_sections — всего четырнадцать инструментов.