NOUZ MCP Server

Servidor MCP local-first que convierte bases de conocimiento de Obsidian y Markdown en un grafo legible por agentes.

Documentación

NOUZ — Servidor MCP semántico para tu base de conocimiento

La estructura surge del contenido.

Funciona con Obsidian, Logseq y cualquier directorio de archivos Markdown.

Para qué sirve Nouz

NOUZ actúa como una capa intermedia entre tu base de notas y el agente de IA. Ayuda a convertir archivos Markdown dispersos en un grafo con el que sea cómodo trabajar tanto para ti como para el agente:

Clasificación automática (Semántica) Tú defines los "Núcleos": dominios base de tu base de conocimiento. Cuando agregas una nueva nota, NOUZ lee su texto, compara vectores y sugiere una marca de dominio o una combinación de dominios.
Búsqueda de relaciones entre notas El servidor construye un grafo estructural dirigido: hierarchy se mantiene como un DAG sin ciclos, y las conexiones semánticas adicionales viven al lado:
- Puentes semánticos: dos notas de dominios distintos apuntan a la misma idea.
- Las conexiones explícitas por etiquetas se pueden almacenar manualmente en YAML.
Seguimiento de la evolución de la base (Deriva) NOUZ almacena el perfil de dominio de los nodos de contenido y puede compararlo con la marca declarada. Si un módulo está descrito como un dominio, pero su perfil se inclina gradualmente hacia otro, el servidor mostrará la discrepancia (core_drift).

Según tus tareas, NOUZ funciona en tres modos: desde un grafo simple (LUCA) hasta una jerarquía estricta de 5 niveles (SLOI).

Cómo funciona

Describes los dominios en config.yaml: qué área cubre cada dominio y por qué características del texto se puede reconocer.
El servidor convierte las descripciones en vectores de referencia (localmente, mediante LM Studio u Ollama).
Cada nota nueva se proyecta sobre esos ejes. La marca se determina por el contenido, o por ti.

Aquí es importante distinguir dos capas. artifact_signs describen la forma de los artefactos L5: log, fuente, hipótesis, especificación, etc. Estas marcas no se agregan a la marca de dominio L4. Un log sigue siendo un log, una fuente sigue siendo una fuente.

core_mix no es la suma de los tipos de artefactos. Es un perfil de dominio en el índice SQLite. L4/L3/L2 lo obtienen de su propio texto durante recalc_signs, y los nodos padre pueden luego obtener un perfil promedio de los nodos de contenido hijos mediante recalc_core_mix. core_drift aparece cuando el perfil de dominio guardado y el sign actual apuntan a dominios principales diferentes.

Puentes semánticos encuentran conexiones entre notas de dominios distintos cuando los textos son cercanos en significado. Si ambas notas ya tienen chunks, el puente se verifica adicionalmente con el mejor par de ellos y devuelve una característica concreta. Las etiquetas siguen siendo una marcación explícita del usuario.

Inicio rápido

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

Sin config.yaml, el servidor arranca en modo LUCA: un grafo sin semántica, que funciona de inmediato.

Para activar el modo semántico, crea una configuración local a partir de la plantilla:

cp config.template.yaml config.yaml

En Windows PowerShell:

Copy-Item config.template.yaml config.yaml

O desde el código fuente:

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

Conexión a Claude Desktop, Cursor, Opencode o cualquier 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"
      }
    }
  }
}

Herramientas MCP

Herramienta	Para qué
`suggest_metadata`	Marca, nivel, puentes, advertencias de deriva
`write_file`	Escribir una nota con marcación YAML
`update_metadata`	Actualizar solo el YAML, sin cambiar el texto de la nota
`read_file`	Leer nota + metadatos
`calibrate_cores`	Actualizar los vectores de referencia de los núcleos
`recalc_signs`	Recalcular las marcas de todas las notas
`recalc_core_mix`	Recalcular el perfil de dominio de los padres según los nodos de contenido hijos
`index_all`	Reindexar toda la base; en PRIZMA/SLOI con `with_embeddings=true` también actualiza los embeddings de archivos/chunks
`embed`	Obtener el vector de un texto en PRIZMA/SLOI
`chunk_text`	Dividir texto Markdown en chunks estables en PRIZMA/SLOI
`chunk_file`	Dividir el cuerpo de una nota en chunks estables en PRIZMA/SLOI
`search_chunks`	Buscar en los chunk embeddings guardados en PRIZMA/SLOI; por defecto reduce la anisotropía
`list_files`	Lista con filtros por nivel, marca
`get_children`	Descender por el grafo
`get_parents`	Ascender por el grafo
`suggest_parents`	Encontrar padres para un nodo huérfano
`add_entity`	Crear una entidad en un solo paso (marca e jerarquía automáticas, etiquetas solo explícitas)
`process_orphans`	Autocompletar archivos sin marcación

Configuración

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.

Después de la configuración, ejecuta calibrate_cores: el servidor creará los vectores de referencia. Verifica los cosenos por pares: el mean-centered entre dominios distintos debe ser notablemente menor que el original. Si todos los pares son aproximadamente iguales, refuerza las diferencias en los textos. Una verificación separada de las referencias se puede ejecutar desde el paquete instalado: nouz-calc-etalons --config config.yaml.

etalons son los dominios semánticos que se comparan mediante embeddings. artifact_signs es el tipo de material para los artefactos L5: nota, concepto, referencia, log, actualización, hipótesis o especificación. Es una etiqueta heurística. Los dominios suelen indicarse en mayúsculas (S/D/E) y los tipos de material en minúsculas (n/c/r/l/u/h/s); se pueden reemplazar en la configuración por cualquier otro valor. Si es necesario, para cualquier tipo se puede agregar keywords: entonces el servidor usará tus palabras para la heurística en lugar del conjunto RU/EN integrado.

Ejemplo real de cálculo

Estos son los resultados reales para las referencias S/D/E con el 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

Los valores mean-centered negativos aquí son un buen resultado: después de restar el vector promedio, los dominios se separan bien. Prueba de humo de las referencias con el nouz-calc-etalons actual: S→99.6%, D→98.5%, E→98.1%. Esto no es una evaluación de toda la base, sino una verificación rápida de que cada referencia, tras el mismo centrado, vuelve con confianza a su marca.

Variable	Por defecto	Descripción
`OBSIDIAN_ROOT`	`./obsidian`	Ruta al almacenamiento
`NOUZ_CONFIG`	(vacío)	Ruta absoluta a `config.yaml`; si no se define, el servidor busca la configuración en el directorio actual
`NOUZ_DATABASE_NAME`	`obsidian_kb.db`	Nombre del archivo de caché SQLite dentro de `OBSIDIAN_ROOT`; útil para verificaciones aisladas, por ejemplo `obsidian_kb.public.db`
`NOUZ_DATABASE_PATH`	(vacío)	Ruta completa al caché SQLite; tiene prioridad 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`	(vacío)	Clave API, si se necesita
`EMBED_MODEL`	(vacío)	Nombre del modelo

Privacidad

Componente	¿Local?
Embeddings (LM Studio / Ollama)	✅ Sí
Tus notas	✅ Sí
Servidor NOUZ	✅ Sí
Contexto del agente de IA (Claude, ChatGPT)	❌ Va a la nube

Todo lo crítico permanece en tu máquina.

Desarrollo

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

Enlaces

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

Los cosenos se calculan. La sintaxis cambia. La semántica permanece.