NOUZ MCP Server

Máy chủ MCP ưu tiên cục bộ, biến cơ sở tri thức Obsidian và Markdown thành đồ thị có thể đọc được bởi tác nhân.

Tài liệu

NOUZ — Семантический MCP-сервер для вашей базы знаний

Структура появляется из содержания.

Работает с Obsidian, Logseq и любыми директориями Markdown-файлов.

Зачем нужен Nouz

NOUZ выступает прослойкой между вашей базой заметок и AI-агентом. Он помогает превратить разрозненные Markdown-файлы в граф, с которым удобно работать и вам, и агенту:

Автоматическая классификация (Семантика) Вы задаете "Ядра" — базовые домены вашей базы. Когда вы добавляете новую заметку, NOUZ читает ее текст, сравнивает векторы и предлагает доменный знак или комбинацию доменов.
Поиск связей между заметками Сервер строит направленный структурный граф: hierarchy держится как DAG без циклов, а дополнительные смысловые связи живут рядом:
- Семантические мосты: две заметки из разных доменов указывают на одну и ту же идею.
- Явные теговые связи можно хранить вручную в YAML.
Отслеживание эволюции базы (Дрифт) NOUZ хранит доменный профиль содержательных узлов и может сравнить его с заявленным знаком. Если модуль описан как один домен, а его профиль постепенно тянет в другой, сервер покажет расхождение (core_drift).

В зависимости от ваших задач NOUZ работает в трех режимах: от простого графа (LUCA) до строгой 5-уровневой иерархии (SLOI).

Как это работает

Вы описываете домены в config.yaml — какую область покрывает каждый домен и по каким признакам текста его узнавать.
Сервер превращает описания в векторы-эталоны (локально, через LM Studio или Ollama).
Каждая новая заметка проецируется на эти оси. Знак определяется содержанием, или вами.

Здесь важно разделять два слоя. artifact_signs описывают форму L5-артефактов: лог, источник, гипотеза, спецификация и так далее. Эти знаки не агрегируются в доменный знак L4. Лог остается логом, источник остается источником.

core_mix — не сумма типов артефактов. Это доменный профиль в SQLite-индексе. L4/L3/L2 получают его из собственного текста при recalc_signs, а родительские узлы могут затем получить усредненный профиль дочерних содержательных узлов через recalc_core_mix. core_drift появляется, когда сохраненный доменный профиль и текущий sign указывают на разные ведущие домены.

Семантические мосты находят связи между заметками из разных доменов, когда тексты близки по смыслу. Если для обеих заметок уже есть чанки, мост дополнительно проверяется лучшей парой из них и возвращает конкретный признак. Теги остаются явной пользовательской разметкой.

Быстрый старт

pip install nouz-mcp
OBSIDIAN_ROOT=/path/to/vault nouz-mcp

Без config.yaml сервер стартует в режиме LUCA — граф без семантики, работает сразу.

Чтобы включить семантический режим, создайте локальный конфиг из шаблона:

cp config.template.yaml config.yaml

В Windows PowerShell:

Copy-Item config.template.yaml config.yaml

Или из исходников:

git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -r requirements.txt
cp config.template.yaml config.yaml
OBSIDIAN_ROOT=./vault python server.py

Подключение к Claude Desktop, Cursor, Opencode или любому MCP-клиенту:

{
  "mcpServers": {
    "nouz": {
      "command": "nouz-mcp",
      "env": {
        "OBSIDIAN_ROOT": "/path/to/vault",
        "NOUZ_CONFIG": "/absolute/path/to/config.yaml",
        "EMBED_API_URL": "http://127.0.0.1:1234/v1"
      }
    }
  }
}

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

Инструмент	Зачем
`suggest_metadata`	Знак, уровень, мосты, дрифт-предупреждения
`write_file`	Записать заметку с YAML-разметкой
`update_metadata`	Обновить только YAML, не меняя текст заметки
`read_file`	Прочитать заметку + метаданные
`calibrate_cores`	Обновить векторы-эталоны ядер
`recalc_signs`	Пересчитать знаки всех заметок
`recalc_core_mix`	Пересчитать доменный профиль родителей по дочерним содержательным узлам
`index_all`	Переиндексировать всю базу; в PRIZMA/SLOI с `with_embeddings=true` также обновляет эмбеддинги файлов/чанков
`embed`	Получить вектор для текста в PRIZMA/SLOI
`chunk_text`	Разрезать Markdown-текст на стабильные чанки в PRIZMA/SLOI
`chunk_file`	Разрезать тело одной заметки на стабильные чанки в PRIZMA/SLOI
`search_chunks`	Искать по сохранённым chunk embeddings в PRIZMA/SLOI; по умолчанию снижает анизотропию
`list_files`	Список с фильтрами по уровню, знаку
`get_children`	Пройти вниз по графу
`get_parents`	Пройти вверх по графу
`suggest_parents`	Найти родителей для сироты
`add_entity`	Создать сущность в один шаг (автоматический знак и иерархия, теги только явно)
`process_orphans`	Автозаполнение файлов без разметки

Конфигурация

Минимальный config.yaml:

mode: prizma

etalons:
  - sign: S
    name: Systems Analysis
    text: >
      Methodology for analysing complex objects: feedback loops,
      emergent properties, self-regulation, bifurcation points.
      Cybernetics, synergetics, dissipative structures, catastrophe
      theory, autopoiesis — tools for understanding how the whole
      exceeds the sum of its parts. Not data and not code — a way
      of thinking about how parts form a whole and why systems
      behave non-linearly.
  - sign: D
    name: Data & Science
    text: >
      Physics and cosmology: from subatomic particles to the large-scale
      structure of the Universe. Lagrangians, curvature tensors, scattering
      cross-sections, quarks, bosons, fermions, plasma, vacuum fluctuations,
      cosmic microwave background, cosmological constant, decoherence.
      Pure science about the nature of matter, energy and spacetime.
  - sign: E
    name: Engineering
    text: >
      Software engineering, machine learning and infrastructure: writing
      and debugging code, deployment, containerisation, neural networks,
      inference, tokenisation, data serialisation, microservices, CI/CD,
      automated testing, refactoring, Git, Docker, Kubernetes, APIs.
      The practical discipline of building computational systems from
      architecture to production.

thresholds:
  sign_spread: 0.05
  confident_spread: 60.0
  pattern_second_sign_threshold: 30.0
  semantic_bridge_threshold: 0.55
  parent_link_threshold: 0.55

artifact_signs:
  - sign: n
    name: Note
    text: Short note, observation, fragment.
  - sign: c
    name: Concept
    text: Definition, concept, entity description.
  - sign: r
    name: Reference
    text: External source, documentation, link, citation.
  - sign: l
    name: Log
    text: Session log, chronology, dialogue record.
  - sign: u
    name: Update
    text: Update, release note, changelog entry.
  - sign: h
    name: Hypothesis
    text: Hypothesis, assumption, speculative idea.
  - sign: s
    name: Specification
    text: Technical specification, instruction, requirements.

После настройки запустите calibrate_cores — сервер создаст эталонные векторы. Проверьте попарные косинусы: mean-centered между разными доменами должен быть заметно ниже исходного. Если все пары примерно одинаковые — усильте различия в текстах. Отдельную проверку эталонов можно запустить из установленного пакета: nouz-calc-etalons --config config.yaml.

etalons — это смысловые домены, которые сравниваются через эмбеддинги. artifact_signs — тип материала для артефактов L5: заметка, концепт, ссылка, лог, обновление, гипотеза или спецификация. Это эвристическая метка. Домены обычно обозначаются заглавными буквами (S/D/E), а типы материала — строчными (n/c/r/l/u/h/s); их можно заменить в конфиге на любые другие значения. При необходимости для любого типа можно добавить keywords: тогда сервер будет использовать ваши слова для эвристики вместо встроенного RU/EN набора.

Реальный пример расчёта

Вот фактические результаты для эталонов S/D/E с моделью text-embedding-granite-embedding-278m-multilingual:

=== Pairwise Cosine (raw) ===
S↔D: 0.5894    S↔E: 0.5862    D↔E: 0.6022

=== Pairwise Cosine (mean-centered) ===
S↔D: -0.5059   S↔E: -0.5117   D↔E: -0.4822

Отрицательные mean-centered значения здесь хороший результат: после вычитания среднего вектора домены хорошо расходятся. Smoke test эталонов текущим nouz-calc-etalons: S→99.6%, D→98.5%, E→98.1%. Это не оценка всей базы, а быстрая проверка, что каждый эталон после того же центрирования уверенно возвращается к своему знаку.

Переменная	По умолчанию	Описание
`OBSIDIAN_ROOT`	`./obsidian`	Путь к хранилищу
`NOUZ_CONFIG`	(пусто)	Абсолютный путь к `config.yaml`; если не задан, сервер ищет конфиг в текущей директории
`NOUZ_DATABASE_NAME`	`obsidian_kb.db`	Имя файла SQLite-кэша внутри `OBSIDIAN_ROOT`; удобно для изолированных проверок, например `obsidian_kb.public.db`
`NOUZ_DATABASE_PATH`	(пусто)	Полный путь к SQLite-кэшу; имеет приоритет над `NOUZ_DATABASE_NAME`
`EMBED_PROVIDER`	`openai`	`openai`, `lmstudio`, `ollama`
`EMBED_API_URL`	`http://127.0.0.1:1234/v1`	Эндпоинт для эмбеддингов
`EMBED_API_KEY`	(пусто)	API-ключ, если нужен
`EMBED_MODEL`	(пусто)	Имя модели

Приватность

Компонент	Локально?
Эмбеддинги (LM Studio / Ollama)	✅ Да
Ваши заметки	✅ Да
Сервер NOUZ	✅ Да
Контекст AI-агента (Claude, ChatGPT)	❌ Уходит в облако

Всё критичное остаётся на вашей машине.

Разработка

git clone https://github.com/Semiotronika/NOUZ-MCP
cd NOUZ-MCP
pip install -e .
python -m compileall -q nouz_mcp pytest_smoke.py scripts
python -m pytest -q
python test_server.py

Ссылки

🌐 semiotronika.ru
📦 PyPI
🗂️ Glama Registry
🐙 GitHub

Косинусы считаются. Синтаксис меняется. Семантика остаётся.