Nix

Сервер MCP, который предоставляет хранилище Obsidian агентам разработки (Cursor, Claude Code, Copilot). Гибридный поиск, чтение и запись заметок — с локальными и бесплатными эмбеддингами и векторной базой данных. Рассуждения остаются на стороне клиента; Nix только предоставляет инструменты.

Транспорт: MCP stdio. Без подкоманды, nix запускает сервер.

Зачем использовать

• Агент редактора находит идеи, а не только слова: семантический + лексический поиск в хранилище.

• Создает и обновляет заметки в формате Obsidian, не выходя из Cursor.

• Всё работает на вашей машине. Ни один фрагмент хранилища не отправляется в API эмбеддингов.

• Вы контролируете, когда меняется индекс: нет фонового наблюдателя.

Related MCP server: Obsidian MCP Server

Требования

• Python 3.11+ в PATH

• Хранилище Obsidian (заметки .md)

• ~2,3 ГБ свободного места при первой синхронизации (загрузка модели BAAI/bge-m3)

Установка

Есть два пути. Оба создают .venv, устанавливают пакет и запускают nix init (спрашивает путь к хранилищу или принимает --vault).

В вашем проекте (пользователь)

1. Скачайте последний релиз (nix-x.y.z.zip).

2. Распакуйте в корень рабочей области и переименуйте папку в nix (zip поставляется как nix-1.0.0/).

3. Запустите установщик внутри этой папки:

cd nix
setup.bat
:: ou, se já souber o vault:
setup.bat --vault "C:/Obsidian/MeuVault"

cd nix
.\setup.ps1
# ou: .\setup.ps1 --vault "C:/Obsidian/MeuVault"

cd nix
bash setup.sh
# ou: bash setup.sh --vault "$HOME/Vault"

В Windows используйте косую черту / в пути к хранилищу (C:/Obsidian/MeuVault). Обратная косая черта ломает TOML.

Затем зарегистрируйте сервер в редакторе — см. Регистрация в MCP-клиенте. Установщик записывает NIX_HOME и добавляет nix в PATH; по завершении сообщает, что настройка завершена. Откройте новый терминал и выполните nix doctor / nix sync. Если автоматическая регистрация не удалась, см. INSTALL.md (раздел Регистрация NIX_HOME и PATH вручную). Если менеджер Nix (NixOS) уже есть в PATH, установщик предупреждает: этот nix получает приоритет.

Из репозитория (разработчик)

Клонируйте репозиторий и запустите тот же установщик в корне:

setup.bat
:: ou: setup.bat --vault "C:/Obsidian/MeuVault"

bash setup.sh
# ou: bash setup.sh --vault "$HOME/Vault"

.\setup.ps1
# ou: .\setup.ps1 --vault "C:/Obsidian/MeuVault"

Ручная установка (эквивалент установщика, с зависимостями для разработки):

python -m venv .venv
# Windows (Git Bash): source .venv/Scripts/activate
# Linux/macOS:        source .venv/bin/activate

pip install -r requirements-dev.txt
pip install -e .
python -m nix init                # ou: python -m nix init --vault "C:/Obsidian/MeuVault"

nix и python -m nix эквивалентны после установщика (в новом терминале) или после активации venv. Cursor не наследует PATH из терминала — в MCP всегда используйте Python из .venv.

Удаление

В папке Nix: uninstall.bat, .\uninstall.ps1 или bash uninstall.sh. Подтвердите с помощью s или передайте --yes. Это удаляет PATH, .venv, индекс (.nix/) и nix.toml. Хранилище не удаляется. --keep-data сохраняет конфигурацию и индекс. Подробности: INSTALL.md.

Регистрация в MCP-клиенте

Клиент запускает процесс. Перезагрузите MCP-серверы после сохранения.

command должен указывать на обёртку внутри папки установки (NIX_HOME), а не на имя nix в PATH. Редактор, открытый через Dock или меню, не наследует PATH терминала (spawn nix ENOENT). Путь отображается в nix doctor, в строке comando nix:.

Cursor — .cursor/mcp.json в рабочей области:

Windows

{
  "mcpServers": {
    "nix": {
      "command": "${env:NIX_HOME}/bin/nix.cmd"
    }
  }
}

В Windows IDE читает переменную пользователя NIX_HOME. Также подойдёт абсолютный путь, например C:/Users/voce/nix/bin/nix.cmd.

macOS / Linux

{
  "mcpServers": {
    "nix": {
      "command": "/Users/voce/nix/bin/nix"
    }
  }
}

Замените /Users/voce/nix на папку установки. "command": "nix" не работает в IDE. bin/nix.cmd закрывает соединение с EACCES. ${env:NIX_HOME} обычно не раскрывается: приложение не читает .zshrc / .bashrc.

Тот же шаблон применим к Claude Code и Copilot. stdout принадлежит протоколу MCP: логи только в .nix/logs/nix.log в папке Nix.

Первые шаги

После init (установщик уже запускает это), откройте новый терминал и выполните:

nix doctor
nix sync
nix status

Если nix не найден, в терминале всё ещё старый PATH: закройте его и откройте новый.

Регистрация NIX_HOME и PATH вручную

Если установщик не записал переменные, пошаговая инструкция есть только в INSTALL.md (в zip релиза есть этот файл). Запишите недостающее и откройте новый терминал.

Первый sync (или любая операция, которая создаёт эмбеддинги) загружает модель BAAI/bge-m3 (~2,3 ГБ) с Hugging Face. При последующих обрабатывается только то, что изменилось.

Новые заметки без папки в пути попадают в vault.default_new_note_folder (по умолчанию Inbox).

Индексация

Это центральное правило:

Изменения, сделанные вне Nix (Obsidian, редактор), не индексируются автоматически. Изменения, сделанные инструментами MCP, обновляют индекс в той же операции.

После редактирования в Obsidian выполните nix sync или попросите агента sync_index. Если векторизация записи не удалась, файл остаётся в хранилище (источник истины), и nix sync исправляет индекс.

CLI

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

Двенадцать инструментов, определённых в src/nix/core/tools/registry.py. Заметки также доступны как ресурс nix://note/{+rel_path}.

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

Файл (первый найденный): $NIX_CONFIG (если задан, только он) → nix.toml в папке Nix ($NIX_HOME или checkout) → nix.toml в текущей рабочей директории и родительских (последний вариант). Относительные пути разрешаются относительно каталога TOML. Переменные NIX_SECAO__CAMPO переопределяют файл (например, NIX_VAULT__PATH). nix init записывает в этот же путь.

Полезные пункты TOML, созданного init:

Публикация версии

Релиз на GitHub создаётся автоматически, когда тег vX.Y.Z попадает в удалённый репозиторий. Workflow .github/workflows/release.yml проверяет версию, запускает ruff и mypy, собирает nix-x.y.z.zip и публикует в Releases.

1. Обновите [project].version в pyproject.toml (например, 1.0.2). Тег должен совпадать с этим значением — иначе job завершится ошибкой.

2. Сделайте коммит и пуш в основную ветку.

3. Создайте и отправьте тег (префикс v обязателен):

git tag v1.1.3
git push origin v1.1.3

4. Следите за workflow Release в Actions. В случае успеха релиз Nix v1.0.2 появится с zip и контрольной суммой .sha256.

Чтобы переопубликовать артефакты уже существующего тега, запустите workflow вручную: Actions → Release → Run workflow и укажите тег (например, v1.0.2).

Документация

• PRD.md — продукт, требования и бизнес-правила

• ARCHITECTURE.md — компоненты, индексация, поиск и MCP stdio