Nix

Servidor MCP que expõe um vault do Obsidian a agentes de desenvolvimento (Cursor, Claude Code, Copilot). Busca híbrida, leitura e escrita nas notas — com embeddings e banco vetorial locais e gratuitos. O raciocínio fica no cliente; o Nix só entrega ferramentas.

Transporte: MCP stdio. Sem subcomando, nix inicia o servidor.

Por que usar

• O agente do editor encontra ideias, não só palavras: busca semântica + léxica no vault.

• Cria e atualiza notas no formato do Obsidian, sem sair do Cursor.

• Tudo roda na sua máquina. Nenhum trecho do vault vai para API de embedding.

• Você controla quando o índice muda: não há watcher em segundo plano.

Requisitos

• Python 3.11+ no PATH

• Um vault do Obsidian (notas .md)

• ~2,3 GB livres na primeira sincronização (download do modelo BAAI/bge-m3)

Instalação

Há dois caminhos. Os dois criam .venv, instalam o pacote e disparam nix init (pergunta o caminho do vault, ou aceite --vault).

No seu projeto (usuário)

1. Baixe a última release (nix-x.y.z.zip).

2. Extraia na raiz do workspace e renomeie a pasta para nix (o zip vem como nix-1.0.0/).

3. Rode o instalador dentro dessa pasta:

cd nix
setup.bat
:: ou, se já souber o vault:
setup.bat --vault "C:/Users/voce/Vault"

cd nix
chmod +x setup.sh
./setup.sh
# ou: ./setup.sh --vault "$HOME/Vault"

No Windows use barras / no caminho do vault (C:/Users/voce/Vault). Barra invertida quebra o TOML.

Depois registre o servidor no editor — veja Registro no cliente MCP.

A partir do repositório (desenvolvedor)

Clone o repositório e rode o mesmo instalador na raiz:

setup.bat
:: ou: setup.bat --vault "C:/Users/voce/Vault"

chmod +x setup.sh
./setup.sh
# ou: ./setup.sh --vault "$HOME/Vault"

Instalação manual (equivale ao instalador, com dependências de desenvolvimento):

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:/Users/voce/Vault"

nix e python -m nix são equivalentes depois de ativar o venv. O Cursor não herda o PATH do terminal — no MCP use sempre o Python do .venv.

Registro no cliente MCP

O cliente inicia o processo. A IDE não herda o PATH do terminal: o comando nix do venv não é encontrado e a conexão fecha ('nix' não é reconhecido).

Aponte para o Python do ambiente virtual. Recarregue os servidores MCP depois de salvar.

Cursor — .cursor/mcp.json no workspace:

{
  "mcpServers": {
    "nix": {
      "command": "${workspaceFolder}/nix/.venv/Scripts/python.exe",
      "args": ["-m", "nix"]
    }
  }
}

Ajuste command conforme o caso:

O mesmo padrão (caminho/do/python + ["-m", "nix"]) vale para Claude Code e Copilot. stdout é do protocolo MCP: logs só em ~/.nix/logs/nix.log.

Primeiros passos

Depois do init (o instalador já dispara isso):

# Windows
.venv\Scripts\python.exe -m nix doctor
.venv\Scripts\python.exe -m nix sync
.venv\Scripts\python.exe -m nix status

# Linux / macOS
.venv/bin/python -m nix doctor
.venv/bin/python -m nix sync
.venv/bin/python -m nix status

O primeiro sync (ou qualquer operação que embede) baixa o modelo BAAI/bge-m3 (~2,3 GB) do Hugging Face. Nas seguintes, só o que mudou é reprocessado.

Notas novas sem pasta no caminho vão para vault.default_new_note_folder (padrão Inbox).

Indexação

Esta é a regra central:

Alterações feitas fora do Nix (Obsidian, editor) não são indexadas sozinhas. Alterações feitas pelas ferramentas MCP atualizam o índice na mesma operação.

Depois de editar no Obsidian, rode nix sync ou peça sync_index ao agente. Se a vetorização de uma escrita falhar, o arquivo permanece no vault (fonte da verdade) e um nix sync corrige o índice.

CLI

Ferramentas MCP

Doze ferramentas, definidas em src/nix/core/tools/registry.py. Notas também aparecem como recurso nix://note/{+rel_path}.

Configuração

Arquivo (primeiro encontrado): $NIX_CONFIG → ./nix.toml → ~/.nix/config.toml. Variáveis NIX_SECAO__CAMPO sobrescrevem o arquivo (ex.: NIX_VAULT__PATH).

Pontos úteis do TOML gerado pelo init:

Documentação

• PRD.md — produto, requisitos e regras de negócio

• ARCHITECTURE.md — componentes, indexação, recuperação e MCP stdio