MCP SERVER · OFFICIAL PROJECTTurns a folder of Markdown notes into a navigable graph — parents, children, tags and a domain sign per note — for Obsidian, Logseq or any vault.
LABSCO SUMMARY
Two choices keep it safe to point at real notes. Metadata edits are a separate tool from body edits, so classifying a note carries no risk of rewriting it, and classification arrives as a suggestion you approve rather than a write. Start in LUCA mode with no config at all — describing your domains and wiring up a local embedding endpoint only pays off once the vault is large enough to get lost in.
A layer between a Markdown knowledge base and an agent. It keeps a SQLite index of files, YAML metadata and graph links, and can classify a note against domains you define.
Python 3.10+, installed with pip install nouz-mcp and run over stdio. OBSIDIAN_ROOT points at the vault (default ./obsidian) and the SQLite index lives inside it as obsidian_kb.db unless NOUZ_DATABASE_NAME or NOUZ_DATABASE_PATH says otherwise. With no config.yaml it starts in LUCA mode — the graph without semantic classification — and needs nothing else. The semantic modes need embeddings: EMBED_PROVIDER selects an OpenAI-compatible endpoint or Ollama, EMBED_API_URL points at it (default http://127.0.0.1:1234/v1) and EMBED_MODEL names the model; NOUZ_CONFIG locates config.yaml when it is not in the working directory.
One command — pip install nouz-mcp
USE CASES
Ask for a classification proposal, then write only the frontmatter you agree with.
Walk downward from the note and collect every direct and transitive child.
Read its parent links and their types, alongside the note itself.
List files with the no-metadata filter to surface everything missing YAML.
Rebuild the index and read the report of parent links that no longer resolve.
Read the current state first, then write the new body while the metadata is locked.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
get_childrenTraverse the hierarchy downward from one note. Returns all direct and transitive child note paths from the local graph index. Use this to answer 'what does this topic/module contain?' It is read-only and does not recompute semantic classification. Use get_parents for the opposite direction.
get_parentsReturn the parent links of one note from the graph index. Each result includes the parent entity name and link_type, such as hierarchy, derived_from, semantic, temporary, tag, analogy, or error. Use this to understand where a note belongs before editing links. It is read-only. Use suggest_parents when a note has no parents and you want candidate links.
index_allScan the whole Markdown vault and rebuild the local SQLite index of files, metadata, and graph links. Use this after adding, moving, or reorganizing notes outside NOUZ. It is safe to run repeatedly and reports missing parent links. In PRIZMA/SLOI, with_embeddings=true also updates file and chunk embeddings for retrieval and semantic classification, which is slower and requires an embedding provider. This tool indexes data; it is not a search tool.
list_filesList notes already known to the local index. Returns lightweight records with path, type, level, and sign, without loading full note bodies. Use this for inventory, filtering, and finding files to inspect next. Set no_metadata=true to find Markdown files without YAML metadata. Use get_children or get_parents when you need graph traversal from a specific note.
read_fileRead one Markdown note from the local knowledge base. Returns the note body, YAML frontmatter, hierarchy metadata, parent links, explicit tags, and warnings as JSON. Use this before write_file when you need to preserve existing content or inspect current metadata. Side effect: refreshes this file in the local SQLite index so later classification and parent suggestions use current data. It never changes the file.
suggest_metadataAnalyze one note and propose knowledge-graph metadata for review. Returns suggested domain sign, material type, hierarchy level, explicit tags, tag quality, tag candidates with chunk evidence, bridge candidates, and hierarchy warnings. Use this before write_file when you want classification help, or to audit an existing note. It is read-only and never edits YAML. Semantic fields require embeddings and are available in PRIZMA/SLOI modes. The optional context object lets an agent test metadata overrides without changing the note.
update_metadataUpdate only YAML frontmatter for an existing note and preserve the Markdown body exactly. Use this for safe changes to type, level, sign, artifact_sign, tags, parents, and parents_meta when the note content must not be touched.
write_fileCreate or replace one Markdown note with YAML metadata. Use it when an agent has an explicit final content body and metadata to save. This is a destructive write: it replaces the complete file, unless content_lock=true is used to preserve the existing body and update only metadata. Before writing, the server validates that parent links do not create graph cycles, syncs parents and parents_meta, and then refreshes the local index. Use read_file first for existing notes and suggest_metadata first when you want classification hints.
BEFORE YOU INSTALL
8 tools when we connected; the project documents 18. Without config.yaml the server starts in LUCA mode with only the plain-graph tools; semantic tools such as calibrate_cores need a configuration, and embed, chunk_text, chunk_file and search_chunks need PRIZMA or SLOI mode.
Both documented clients run the server on your machine.
INSTALLATION
pip install nouz-mcp{
"mcpServers": {
"nouz": {
"command": "nouz-mcp",
"env": {
"OBSIDIAN_ROOT": "<YOUR_OBSIDIAN_ROOT>",
"NOUZ_CONFIG": "<YOUR_NOUZ_CONFIG>",
"EMBED_API_URL": "http://127.0.0.1:1234/v1"
}
}
}
}MCP servers
lethain
Epistates
Scottnine
flowing-abyss