Инструменты MCP

Инструменты NOUZ дают агенту доступ к Markdown-базе через понятный контракт: читать файлы, видеть YAML, ходить по графу, предлагать разметку, пересчитывать семантический слой и записывать изменения только явным действием.

На практике с NOUZ можно говорить обычным языком: «покажи родителей заметки», «найди файлы без YAML», «предложи разметку», «пересчитай эталоны». Названия ниже нужны как справочник того, что MCP-клиент вызывает во время работы.

Базовый протокол работы агента

Для существующей заметки безопасный порядок такой:

read_file - прочитать текст и YAML.
get_parents и get_children - понять место в графе.
suggest_metadata - получить предложения и предупреждения.
update_metadata - изменить только YAML, если тело заметки должно остаться нетронутым.
write_file - использовать для новой заметки или полной замены файла.

Если агент работает с незнакомой базой, сначала лучше вызвать list_files, а затем читать отдельные файлы точечно.

Инструменты чтения и навигации

`read_file`

При обычном режиме помимо чтения обновляет запись файла в SQLite-индексе, чтобы следующие вызовы видели свежие данные.

Используйте перед любой правкой существующего файла.

json

{
  "path": "notes/onboarding-log.md"
}

`list_files`

Возвращает легкий список файлов из индекса. Поддерживает фильтры по уровню, знаку, подпапке и отсутствию YAML.

json

{
  "level": 5,
  "sign": "B"
}

Полезно для первичного обзора базы и поиска файлов, которые нужно открыть через read_file.

`get_parents`

Возвращает прямые родительские связи файла из индекса. В ответе есть имя сущности и link_type.

json

{
  "path": "notes/onboarding-thesis.md"
}

Используйте, когда нужно понять, где заметка находится и какие неиерархические связи у нее уже есть.

`get_children`

Проходит вниз по hierarchy и возвращает прямых и транзитивных детей узла.

json

{
  "path": "modules/ТГ-канал.md"
}

Полезно для вопросов вроде: что входит в этот модуль, какие кванты лежат в паттерне, какие артефакты накопились под темой.

Инструменты записи

`update_metadata`

Меняет только YAML frontmatter существующей заметки и сохраняет Markdown-тело как есть.

json

{
  "path": "notes/onboarding-thesis.md",
  "metadata": {
    "type": "quant",
    "level": 4,
    "sign": "nB",
    "artifact_sign": "n",
    "parents_meta": [
      {
        "entity": "ТГ-канал",
        "link_type": "hierarchy"
      },
      {
        "entity": "Лог разговора с пользователем",
        "link_type": "derived_from"
      }
    ]
  }
}

Это основной инструмент для аккуратной разметки. Если нужно изменить только sign, level, tags, parents или parents_meta, выбирайте его.

`write_file`

Создает или полностью заменяет Markdown-файл с YAML frontmatter и телом. Перед записью сервер синхронизирует parents и parents_meta, проверяет циклы для hierarchy и обновляет индекс.

json

{
  "path": "quants/onboarding-next-step.md",
  "content": "Пользователь должен видеть следующий шаг сразу после регистрации.",
  "metadata": {
    "type": "quant",
    "level": 4,
    "sign": "nB",
    "artifact_sign": "n",
    "parents_meta": [
      {
        "entity": "ТГ-канал",
        "link_type": "hierarchy"
      }
    ]
  }
}

Для существующих заметок сначала вызывайте read_file. Если нужно сохранить тело файла и обновить только YAML через write_file, используйте content_lock=true; в обычной работе проще взять update_metadata.

`add_entity`

Создает новую сущность в один шаг: файл, начальную разметку, уровень, знак и возможных родителей. Доступен в PRIZMA и SLOI.

json

{
  "path": "inbox/new-log.md",
  "content": "Лог разговора...",
  "level": 5,
  "type": "artifact",
  "auto_parents": false
}

Если передать parents, сервер использует их явно. Если auto_parents=true, NOUZ может подобрать одного родителя по embedding similarity. Теги записываются только если вы передали их явно.

`process_orphans`

Пакетно ищет файлы без ключевой разметки: пустые знаки, отсутствующие родители у L2-L5, новые заметки без YAML. Может работать в dry_run.

json

{
  "dry_run": true,
  "auto_parents": true,
  "limit": 20
}

Начинайте с dry_run=true. Пакетная запись удобна после импорта, но ее стоит проверять глазами.

Семантические инструменты

`suggest_metadata`

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

json

{
  "path": "inbox/client-dialogue.md",
  "context": {
    "type": "artifact",
    "level": 5
  }
}

Инструмент ничего не пишет. Его удобно вызывать перед update_metadata или write_file.

`suggest_parents`

Предлагает родительские узлы по близости embeddings. Доступен в PRIZMA и SLOI.

json

{
  "path": "inbox/client-dialogue.md",
  "top_n": 3
}

Результат нужно рассматривать как список кандидатов. Выбор родителя остается ручным решением.

`calibrate_cores`

Пересчитывает reference vectors для эталонов из config.yaml и показывает попарные косинусы. Запускайте после создания конфига, смены модели или изменения текстов ядер.

Если домены слишком похожи, классификация будет слабой. Подробная расшифровка raw cosine, mean-centered cosine, smoke test эталонов и spread вынесена в отдельную страницу: Проверка качества эталонов.

`recalc_signs`

Пересчитывает автоматические знаки по текущим эталонам и embedding-модели. Не меняет Markdown YAML; пишет вычисляемые поля в SQLite.

json

{
  "dry_run": true
}

Сначала используйте dry_run=true, особенно после смены модели или эталонов.

`recalc_core_mix`

Пересчитывает доменный профиль родительских узлов по дочерним содержательным узлам. Помогает увидеть дрейф модулей и паттернов.

Обычно запускается после index_all с embeddings и recalc_signs.

Индекс и retrieval

`index_all`

Сканирует всю Markdown-базу и обновляет SQLite-индекс файлов, YAML и графовых связей.

json

{
  "with_embeddings": false
}

С with_embeddings=true сервер также обновляет embeddings файлов и чанков. Этот режим доступен в PRIZMA и SLOI; в LUCA index_all работает только как графовый индекс без embeddings.

`chunk_text`

Делит переданный Markdown-текст на стабильные чанки. Ничего не пишет, не индексирует и не вызывает embedding endpoint. Доступен в PRIZMA и SLOI как часть retrieval-слоя.

json

{
  "text": "# Заголовок\n\nТекст заметки...",
  "source_id": "preview.md",
  "max_chars": 1200,
  "overlap_chars": 120
}

Полезно для проверки того, как NOUZ разобьет материал перед embedding-поиском.

`chunk_file`

Читает одну заметку и возвращает чанки ее тела. Не пишет индекс и не создает embeddings. Доступен в PRIZMA и SLOI.

json

{
  "path": "notes/long-reference.md"
}

`search_chunks`

Ищет по сохраненным chunk embeddings. Доступен в PRIZMA и SLOI; перед поиском нужно выполнить index_all с with_embeddings=true.

json

{
  "query": "почему пользователь теряется после регистрации",
  "top_k": 8,
  "score_mode": "auto"
}

score_mode=auto использует centered scoring для больших неограниченных поисков и raw cosine для поиска внутри одного файла. Это помогает снизить общий embedding-фон.

`embed`

Возвращает embedding для короткого текста. Это диагностический инструмент PRIZMA/SLOI: он не индексирует заметки и не пишет файлы.

json

{
  "text": "Пользователь теряется на первом экране после регистрации."
}

Используйте для проверки embedding endpoint или ручных сравнений.

Доступность по режимам

Инструмент	LUCA	PRIZMA	SLOI
`read_file`	да	да	да
`write_file`	да	да	да
`update_metadata`	да	да	да
`list_files`	да	да	да
`get_children`	да	да	да
`get_parents`	да	да	да
`suggest_metadata`	ограниченно	да	да
`embed`	нет	да	да
`chunk_text`	нет	да	да
`chunk_file`	нет	да	да
`search_chunks`	нет	да	да
`index_all`	да, без `with_embeddings=true`	да	да
`suggest_parents`	нет	да	да
`calibrate_cores`	нет	да	да
`recalc_signs`	нет	да	да
`recalc_core_mix`	нет	да	да
`process_orphans`	нет	да	да
`add_entity`	нет	да	да

В NOUZ_READ_ONLY=true инструменты записи и пересчета скрываются и блокируются. Для публичных демо, внешних агентов и осторожного аудита это хороший режим по умолчанию.

lab

Семантическая лаборатория

Если хочется увидеть, как устроены эмбеддинги, откройте лабораторию: там можно покрутить облако слов, сравнить соседей до и после центрирования и увидеть SVD-спектр как форму пространства.

Открыть лабораторию

Инструменты MCP ​

Базовый протокол работы агента ​

Инструменты чтения и навигации ​

read_file ​

list_files ​

get_parents ​

get_children ​

Инструменты записи ​

update_metadata ​

write_file ​

add_entity ​

process_orphans ​

Семантические инструменты ​

suggest_metadata ​

suggest_parents ​

calibrate_cores ​

recalc_signs ​

recalc_core_mix ​

Индекс и retrieval ​

index_all ​

chunk_text ​

chunk_file ​

search_chunks ​

embed ​

Доступность по режимам ​

Семантическая лаборатория

Инструменты MCP

Базовый протокол работы агента

Инструменты чтения и навигации

`read_file`

`list_files`

`get_parents`

`get_children`

Инструменты записи

`update_metadata`

`write_file`

`add_entity`

`process_orphans`

Семантические инструменты

`suggest_metadata`

`suggest_parents`

`calibrate_cores`

`recalc_signs`

`recalc_core_mix`

Индекс и retrieval

`index_all`

`chunk_text`

`chunk_file`

`search_chunks`

`embed`

Доступность по режимам