NOUZ MCP Server

Servidor MCP local

Documentação

NOUZ — Servidor MCP semântico para sua base de conhecimento

A estrutura emerge do conteúdo.

Funciona com Obsidian, Logseq e qualquer diretório de arquivos Markdown.

Por que usar o Nouz

O NOUZ atua como uma camada intermediária entre sua base de notas e o agente de IA. Ele ajuda a transformar arquivos Markdown dispersos em um grafo com o qual é fácil trabalhar tanto para você quanto para o agente:

Classificação automática (Semântica) Você define os "Núcleos" — os domínios básicos da sua base. Quando você adiciona uma nova nota, o NOUZ lê o texto dela, compara os vetores e sugere um sinal de domínio ou uma combinação de domínios.
Busca de conexões entre notas O servidor constrói um grafo estrutural direcionado: hierarchy é mantido como um DAG sem ciclos, e as conexões semânticas adicionais vivem ao lado:
- Pontes semânticas: duas notas de domínios diferentes apontam para a mesma ideia.
- Conexões explícitas por tags podem ser armazenadas manualmente em YAML.
Monitoramento da evolução da base (Drift) O NOUZ armazena o perfil de domínio dos nós de conteúdo e pode compará-lo com o sinal declarado. Se um módulo é descrito como um domínio, mas seu perfil gradualmente puxa para outro, o servidor mostrará a divergência (core_drift).

Dependendo das suas necessidades, o NOUZ opera em três modos: de um grafo simples (LUCA) a uma hierarquia estrita de 5 níveis (SLOI).

Como funciona

Você descreve os domínios em config.yaml — qual área cada domínio cobre e por quais características do texto reconhecê-lo.
O servidor transforma as descrições em vetores de referência (localmente, via LM Studio ou Ollama).
Cada nova nota é projetada nesses eixos. O sinal é determinado pelo conteúdo, ou por você.

Aqui é importante separar duas camadas. artifact_signs descrevem a forma dos artefatos L5: log, fonte, hipótese, especificação e assim por diante. Esses sinais não são agregados ao sinal de domínio L4. Um log continua sendo um log, uma fonte continua sendo uma fonte.

core_mix — não é a soma dos tipos de artefatos. É o perfil de domínio no índice SQLite. L4/L3/L2 o obtêm do próprio texto durante recalc_signs, e os nós pais podem então obter um perfil médio dos nós de conteúdo filhos via recalc_core_mix. core_drift aparece quando o perfil de domínio salvo e o sign atual apontam para domínios principais diferentes.

Pontes semânticas encontram conexões entre notas de domínios diferentes quando os textos são próximos em significado. Se ambas as notas já possuem chunks, a ponte é adicionalmente verificada pelo melhor par deles e retorna uma característica específica. As tags permanecem como marcação explícita do usuário.

Início rápido

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

Sem config.yaml, o servidor inicia no modo LUCA — grafo sem semântica, funciona imediatamente.

Para ativar o modo semântico, crie um config local a partir do template:

cp config.template.yaml config.yaml

No Windows PowerShell:

Copy-Item config.template.yaml config.yaml

Ou a partir do código-fonte:

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

Conexão ao Claude Desktop, Cursor, Opencode ou qualquer cliente 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"
      }
    }
  }
}

Ferramentas MCP

Ferramenta	Para quê
`suggest_metadata`	Sinal, nível, pontes, avisos de drift
`write_file`	Gravar uma nota com marcação YAML
`update_metadata`	Atualizar apenas o YAML, sem alterar o texto da nota
`read_file`	Ler nota + metadados
`calibrate_cores`	Atualizar os vetores de referência dos núcleos
`recalc_signs`	Recalcular os sinais de todas as notas
`recalc_core_mix`	Recalcular o perfil de domínio dos pais a partir dos nós de conteúdo filhos
`index_all`	Reindexar toda a base; no PRIZMA/SLOI com `with_embeddings=true` também atualiza os embeddings de arquivos/chunks
`embed`	Obter vetor para texto no PRIZMA/SLOI
`chunk_text`	Dividir texto Markdown em chunks estáveis no PRIZMA/SLOI
`chunk_file`	Dividir o corpo de uma única nota em chunks estáveis no PRIZMA/SLOI
`search_chunks`	Buscar por chunk embeddings salvos no PRIZMA/SLOI; por padrão reduz a anisotropia
`list_files`	Lista com filtros por nível, sinal
`get_children`	Descer pelo grafo
`get_parents`	Subir pelo grafo
`suggest_parents`	Encontrar pais para um órfão
`add_entity`	Criar entidade em uma única etapa (sinal e hierarquia automáticos, tags apenas explícitas)
`process_orphans`	Preenchimento automático de arquivos sem marcação

Configuração

config.yaml mínimo:

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.

Após a configuração, execute calibrate_cores — o servidor criará os vetores de referência. Verifique os cossenos aos pares: o mean-centered entre domínios diferentes deve ser visivelmente menor que o original. Se todos os pares forem aproximadamente iguais — reforce as diferenças nos textos. Uma verificação separada das referências pode ser executada a partir do pacote instalado: nouz-calc-etalons --config config.yaml.

etalons — são os domínios semânticos que são comparados por meio de embeddings. artifact_signs — o tipo de material para artefatos L5: nota, conceito, referência, log, atualização, hipótese ou especificação. É um rótulo heurístico. Os domínios geralmente são indicados em letras maiúsculas (S/D/E), e os tipos de material em minúsculas (n/c/r/l/u/h/s); eles podem ser substituídos no config por quaisquer outros valores. Se necessário, para qualquer tipo, você pode adicionar keywords: então o servidor usará suas palavras para a heurística em vez do conjunto RU/EN embutido.

Exemplo real de cálculo

Aqui estão os resultados reais para as referências S/D/E com o modelo 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

Valores mean-centered negativos aqui são um bom resultado: após subtrair o vetor médio, os domínios divergem bem. Smoke test das referências com o nouz-calc-etalons atual: S→99.6%, D→98.5%, E→98.1%. Isso não é uma avaliação de toda a base, mas uma verificação rápida de que cada referência, após o mesmo centramento, retorna com confiança ao seu sinal.

Variável	Padrão	Descrição
`OBSIDIAN_ROOT`	`./obsidian`	Caminho para o armazenamento
`NOUZ_CONFIG`	(vazio)	Caminho absoluto para `config.yaml`; se não definido, o servidor procura o config no diretório atual
`NOUZ_DATABASE_NAME`	`obsidian_kb.db`	Nome do arquivo de cache SQLite dentro de `OBSIDIAN_ROOT`; útil para verificações isoladas, por exemplo `obsidian_kb.public.db`
`NOUZ_DATABASE_PATH`	(vazio)	Caminho completo para o cache SQLite; tem prioridade sobre `NOUZ_DATABASE_NAME`
`EMBED_PROVIDER`	`openai`	`openai`, `lmstudio`, `ollama`
`EMBED_API_URL`	`http://127.0.0.1:1234/v1`	Endpoint para embeddings
`EMBED_API_KEY`	(vazio)	Chave de API, se necessário
`EMBED_MODEL`	(vazio)	Nome do modelo

Privacidade

Componente	Local?
Embeddings (LM Studio / Ollama)	✅ Sim
Suas notas	✅ Sim
Servidor NOUZ	✅ Sim
Contexto do agente de IA (Claude, ChatGPT)	❌ Vai para a nuvem

Tudo o que é crítico permanece na sua máquina.

Desenvolvimento

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