NOUZ — Obsidian 的 MCP 服务器

用于 Obsidian 中语义知识管理的统一 MCP 服务器。支持本地嵌入模型 — 无需云端。

MIT License Python 3.10+ MCP

快速开始

git clone https://github.com/KVANTRA-dev/NOUZ-MCP
cd NOUZ-MCP
pip install -r requirements.txt

export OBSIDIAN_ROOT=./vault
export EMBED_API_URL=http://127.0.0.1:1234/v1  # LM Studio or Ollama

python server.py

通过任何兼容 MCP 的客户端（如 Claude Desktop 等）使用 stdio 传输进行连接。

Related MCP server: Semantic Mesh Memory (SEM) MCP Server

模式

NOUZ 有三种运行模式。可通过 MODE 环境变量或 config.yaml 进行设置。

模式	描述	是否需要嵌入
luca	纯图模式 — YAML + 链接，无语义分类	否
prizma	图 + 语义 — 符号分类、core_mix、语义桥接	是
sloi	严格的 5 级层级 — 循环检测、违规警告	是

如果您只需要图导航，请从 LUCA 开始。 当您准备好定义语义核心时，再添加 PRIZMA/SLOI。

笔记格式

每篇笔记都使用 YAML 前置元数据：

---
type: module
level: 3
sign: T
status: active
tags:
  - research
parents:
  - Parent Note Name
parents_meta:
  - entity: Parent Note Name
    link_type: hierarchy
---

Your note content here.

五个层级

层级	类型	描述
1	core	顶级领域（例如“数学”）
2	pattern	领域内的知识区域
3	module	领域内的分组
4	quant	具体的原子笔记
5	artifact	叶子笔记、参考资料、日志

parents 字段是笔记名称列表（供 Obsidian/ExcaliBrain 用于维基链接）。parents_meta 字段携带用于 NOUZ 图逻辑的结构化链接元数据。请保持它们同步 — NOUZ 在写入时会自动处理此操作。

语义标准 (Prizma / Sloi)

标准（Etalons）定义了您语义空间的“轴” — 代表每个知识领域的参考文本。NOUZ 通过这些向量的余弦相似度对笔记进行分类。

将 config.template.yaml 复制到 config.yaml：

mode: prizma

etalons:
  - sign: T
    name: Technology
    text: "programming software architecture infrastructure machine learning neural networks algorithms"
  - sign: S
    name: Science
    text: "physics chemistry biology mathematics formal logic theorems cosmology quantum mechanics"
  - sign: H
    name: Humanities
    text: "philosophy psychology sociology history literature art culture ethics cognitive science"

最佳实践：

使用 3–5 个领域 — 领域过多会使分类产生噪声
每个标准应该是密集的关键词列表，而不是句子
更改标准后运行 calibrate_cores，然后检查两两余弦相似度
目标是使任意两个标准之间的相似度 < 0.55，以实现清晰的分离

工具

所有模式

工具	描述
`read_file(path)`	读取带有已解析 YAML 元数据的笔记
`write_file(path, content, metadata)`	写入带有 YAML 前置元数据的笔记
`list_files(level, sign, tags)`	过滤并列出库中的笔记
`index_all(with_embeddings)`	将库索引到 SQLite 数据库
`embed(text)`	从配置的提供程序获取嵌入向量
`get_parents(path)`	获取父节点（链接到此文件的文件）
`get_children(path)`	获取子节点（此文件链接到的文件）
`format_entity_compact(path)`	返回实体公式：`(children)[entity]{parents}`

仅限 Prizma / Sloi

工具	描述
`calibrate_cores()`	从配置重新计算标准嵌入
`recalc_signs()`	自动为所有已索引的笔记分配符号
`recalc_core_mix()`	通过 DAG 自下而上聚合 core_mix
`suggest_metadata(path)`	为笔记建议符号、层级、core_mix
`suggest_parents(path)`	通过向量相似度建议父链接

环境变量

变量	默认值	描述
`OBSIDIAN_ROOT`	`./obsidian`	您的 Obsidian 库路径
`MODE`	`luca`	`luca` / `prizma` / `sloi` — 由 config.yaml 覆盖
`EMBED_PROVIDER`	`openai`	`openai` / `gigachat` / `ollama`
`EMBED_API_URL`	`http://127.0.0.1:1234/v1`	嵌入 API 端点
`EMBED_MODEL`	—	模型名称（可选，使用提供程序默认值）
`EMBED_API_KEY`	—	API 密钥（本地模型留空）
`EMBED_ENABLED`	`true`	设置为 `false` 以完全禁用嵌入

工作流示例

# 1. Start server
python server.py

# 2. Index your vault
index_all(with_embeddings=true)

# 3. Calibrate etalons (Prizma/Sloi)
calibrate_cores()

# 4. Classify all notes
recalc_signs()

# 5. Query
suggest_parents("path/to/note.md")
list_files(sign="T", level=4)

NOUZ MCP Server

NOUZ — Obsidian 的 MCP 服务器

快速开始

模式

笔记格式

五个层级

语义标准 (Prizma / Sloi)

工具

所有模式

仅限 Prizma / Sloi

环境变量

工作流示例

链接

更新日志

v2.1.1

v2.1.0

Resources

Tools

Latest Blog Posts

MCP directory API