Инструменты MCP
Инструменты — это основной интерфейс NOUZ. Через них AI-агент не просто читает папку файлов, а работает с базой как со структурой: видит узлы, связи, уровни, домены, кандидатов на мосты и сигналы дрифта.
Философия простая: каждое действие должно быть явным. Один инструмент читает заметку, другой показывает её место в графе, третий предлагает разметку, четвёртый пересчитывает состав базы. Автоматика предлагает, человек или агент по заданным правилам принимает решение.
NOUZ предоставляет до 15 инструментов через Model Context Protocol. Доступность зависит от режима:
| # | Инструмент | Что делает | LUCA | PRIZMA | SLOI |
|---|---|---|---|---|---|
| 1 | read_file | прочитать заметку вместе с YAML и обновить её в индексе | ✓ | ✓ | ✓ |
| 2 | write_file | записать заметку с проверкой циклов и синхронизацией связей | ✓ | ✓ | ✓ |
| 3 | list_files | увидеть карту файлов без загрузки полного текста | ✓ | ✓ | ✓ |
| 4 | get_children | пройти вниз по графу: что содержит этот узел | ✓ | ✓ | ✓ |
| 5 | get_parents | пройти вверх по графу: куда относится эта заметка | ✓ | ✓ | ✓ |
| 6 | format_entity_compact | получить короткую формулу позиции узла | ✓ | ✓ | ✓ |
| 7 | index_all | собрать локальный индекс файлов, YAML и связей | ✓ | ✓ | ✓ |
| 8 | suggest_metadata | предложить домен, уровень, теги, мосты и предупреждения | — | ✓ | ✓ |
| 9 | suggest_parents | найти возможных родителей по смысловой близости | — | ✓ | ✓ |
| 10 | embed | проверить embedding для текста вручную | — | ✓ | ✓ |
| 11 | calibrate_cores | построить эталонные векторы доменов | — | ✓ | ✓ |
| 12 | recalc_signs | пересчитать автоматическую классификацию базы | — | ✓ | ✓ |
| 13 | recalc_core_mix | поднять доменный состав снизу вверх и увидеть drift | — | ✓ | ✓ |
| 14 | process_orphans | разобрать файлы без разметки и предложить заполнение | — | ✓ | ✓ |
| 15 | add_entity | создать новую сущность с первичной разметкой | — | ✓ | ✓ |
Чтение и запись
read_file
Прочитать Markdown-файл и вернуть YAML-блок вместе с текстом. В YAML используются поля type, level, sign, artifact_sign, parents, tags. При чтении файл переиндексируется в базе, поэтому дальнейшие предложения строятся на свежем состоянии.
write_file
Создать или обновить заметку с YAML-блоком. Перед записью проверяет граф на циклы и синхронизирует обычные родительские ссылки parents с расширенным описанием связей parents_meta. Это инструмент финального действия: сначала лучше прочитать файл и получить предложения, потом записывать.
list_files
Список проиндексированных файлов. Можно отфильтровать по уровню level, знаку sign, подпапке subfolder или показать файлы без YAML через no_metadata.
Навигация по графу
get_children
Все потомки узла из индекса графа: прямые и транзитивные.
get_parents
Родительские связи файла. Возвращает имя сущности entity и тип связи link_type.
format_entity_compact
Компактная формула позиции узла: (дети)[узел]{родители}. В формуле отображаются связи, которые помогают быстро прочитать структуру: hierarchy, semantic и temporary.
Семантика PRIZMA / SLOI
suggest_metadata
Анализирует файл и предлагает доменный знак sign, тип материала artifact_sign, уровень, теги, мосты и ошибки иерархии. Предложения возвращаются с флагом proposed: true: решение остаётся за вами.
suggest_parents
Находит кандидатов в родители для сирот по косинусной близости. Кандидаты ниже порога parent_link_threshold отбрасываются; при равном счёте предпочтение получает кандидат из того же домена.
embed
Сгенерировать embedding для произвольного текста. Нужен для отладки сходства и ручных проверок.
Обслуживание базы PRIZMA / SLOI
index_all
Переиндексировать все Markdown-файлы. С with_embeddings=true также пересчитывает embeddings.
calibrate_cores
Пересчитать эталонные векторы из config.yaml. Возвращает сырые и mean-centered косинусы между эталонами, чтобы проверить разделимость доменов.
recalc_signs
Переклассифицировать файлы по текущим эталонам. Обновляет в базе доменный знак sign, автоматический знак sign_auto, источник знака sign_source и тип материала artifact_sign. YAML не меняет. Используйте dry_run=true для предпросмотра.
recalc_core_mix
Пересчитать core_mix снизу вверх: L4 получает профиль из классификации текста, L3 и L2 агрегируют дочерние узлы. Обновляет только базу данных.
Автоматизация PRIZMA / SLOI
process_orphans
Находит файлы без знака или без родителей и предлагает заполнение: sign, artifact_sign, теги и возможных родителей. Может работать в режиме предпросмотра dry_run или записывать YAML.
add_entity
Создаёт сущность в один шаг: записывает файл, определяет sign и artifact_sign, добавляет теги и при auto_parents=true выбирает лучшего родителя выше порога.