obsidian-zk-cn — Chinese-first Obsidian Zettelkasten MCP Server

面向 Obsidian 的 AI 辅助卡片盒 MCP 服务器。它支持卢曼编号、类型化连接、SQLite 元数据索引，以及 Claude Code slash commands 工作流。

它通过 Model Context Protocol 暴露工具和提示词，可在 Claude Code 中直接使用。

功能

• 笔记 CRUD：创建 fleeting、literature、permanent、MOC、project 笔记，并写入规范 frontmatter
• 卢曼编号：自动生成 zk_id，支持数字/字母交替层级，例如 1 -> 1a -> 1a1 -> 1a1a
• 连接评分：根据共享标签、关键词、卢曼距离、共同 MOC 发现相关笔记
• 反向链接：跟踪 incoming/outgoing links，并按路径解析
• Vault 分析：发现待处理笔记、孤立笔记、过期提醒和主题聚类
• 质量流程：将 fleeting/literature 提炼成 permanent，并通过质量检查 finalize
• MCP skills：提供 /zk:capture、/zk:promote、/zk:moc 等引导式工作流
• SQLite 索引：增量索引笔记，避免每次全量扫描 vault

不使用 embeddings；语义相关性由 Claude 在上下文中直接判断。

语言支持

项目现在支持三种笔记语言：

| 代码 | 语言 | 说明 | | ---- | ---- | ---- | | zh | 中文 | 默认语言。生成笔记、章节标题、连接类型、领域标签和 Claude skills 输出默认使用中文 | | uk | 乌克兰语 | 保留兼容原项目的乌克兰语 vault | | en | 英语 | 可用于英文 vault |

初始化时会询问：

Language (zh/uk/en) [zh]:

直接回车会使用 zh。也可以输入 中文、cn、zh-CN 等别名，都会归一化为 zh。

中文默认生成内容包括：

• fleeting note：想法、背景、可能的关联、下一步
• literature note：摘要、阅读笔记、关键想法、引文与高亮、关联
• permanent note：主张、展开、证据与支持、反例与限制、关联
• MOC：核心笔记、支撑文献、开放问题
• project note：目标、任务、相关笔记、进展日志

中文连接类型默认为：

• 支持 (Supports)
• 反驳 (Contradicts)
• 扩展 (Extends)
• 相关 (Related)

快速开始

1. 安装并初始化

npx obsidian-zk-cn init

交互式向导会：

• 检测或询问 Obsidian vault 路径
• 选择笔记语言，默认 zh
• 创建目录结构：1-Fleeting/、2-Literature/、3-Permanent/、4-MOC/、5-Projects/
• 复制中文默认笔记模板、skills 和 agents 到 .claude/
• 生成 CLAUDE.md 项目指令
• 在 .zk/ 中创建 SQLite 数据库
• 在 .mcp.json 中配置 MCP server

2. 使用

在 Claude Code 中打开 vault：

cd your-vault
claude

MCP server 会自动启动。常用命令如下：

| Command | 作用 | | ------- | ---- | | /zk:capture | 从一个想法快速创建 fleeting note | | /zk:literature | 从粘贴的来源材料创建 literature note | | /zk:permanent | 创建带卢曼编号的原子化 permanent note | | /zk:promote | 将 fleeting/literature 转换或提炼成 permanent | | /zk:manage | 按卢曼编号查找、编辑、归档或删除笔记 | | /zk:moc | 创建 Map of Content，并按标签自动拉取相关笔记 | | /zk:project | 创建带任务、截止日期和相关笔记的项目笔记 | | /zk:finalize | 质量检查并 finalize permanent note | | /zk:tree | 可视化卢曼知识树 | | /zk:review | 输出 vault 健康报告 | | /zk:daily | 晨间 briefing，列出待处理和过期笔记 | | /zk:connect | 为某条笔记寻找并创建连接 | | /zk:reflect | 对 vault 主题进行深度反思 |

3. 更新

升级包后执行：

npx obsidian-zk-cn update

它会同步模板、skills、agents，并运行数据库迁移。同步时会读取 .zk/config.json 中的语言配置；如果没有配置，默认使用中文。

工作方式

Claude Code <-> MCP Server (obsidian-zk-cn serve) <-> SQLite DB + Vault files
                   |
                   +-- Tools  (zk_capture, zk_permanent, zk_moc, zk_backlinks, ...)
                   +-- Skills (/zk:capture, /zk:promote, /zk:finalize, ...)

架构

| Component | Choice | | --------- | ------ | | MCP SDK | @modelcontextprotocol/sdk，stdio transport | | Database | better-sqlite3，单个 .zk/zettelkasten.db 文件 | | Semantic search | Claude 直接在上下文中判断，不依赖 embeddings | | Vault I/O | Node.js fs，直接读写 Markdown 文件 |

MCP Tools

CRUD

• zk_capture：创建 fleeting note
• zk_literature：从来源材料创建 literature note
• zk_permanent：创建带卢曼编号的 permanent note
• zk_manage：编辑 frontmatter 和正文 section，或按 ID 归档/删除
• zk_promote：将 fleeting/literature 标记为已处理，并提取关键想法
• zk_moc：创建 MOC，并按标签自动拉取相关笔记
• zk_project：创建项目笔记

搜索与连接

• zk_find_connections：按标签、关键词、卢曼距离、MOC overlap 查找连接候选
• zk_backlinks：按路径、标题或 ID 查询 incoming/outgoing links
• zk_cluster_detect：发现还没有 MOC 的新主题聚类

分析

• zk_list：按 type/status/folder 过滤笔记
• zk_unprocessed：列出待处理笔记和年龄
• zk_orphans：找出没有 incoming links 的孤立笔记
• zk_finalize：检查 permanent note 是否有连接、主张、证据、置信度
• zk_next_id：生成下一个卢曼 ID
• zk_find_by_id：将卢曼 ID 解析为路径
• zk_tree：展示完整树、子树或某条笔记的上下文
• zk_review：完整 vault 健康报告

索引

• zk_reindex：全量重新扫描 vault
• zk_status：查看数据库统计和最近索引时间

数据库与索引

Vault 本质上是 Markdown 文件集合。没有数据库时，查找连接、列出待处理笔记、发现孤立笔记都需要扫描所有 .md 文件。SQLite 数据库是 vault 的只读优化索引。

核心表结构：

CREATE TABLE notes (
  path TEXT PRIMARY KEY,
  title TEXT, zk_id TEXT, type TEXT, status TEXT,
  folder TEXT, tags TEXT, summary TEXT, flags TEXT,
  created TEXT, modified TEXT, content_hash TEXT
);

CREATE TABLE links (
  source TEXT, target TEXT, link_type TEXT,
  PRIMARY KEY (source, target)
);

CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT);

增量索引流程：

1. scanVault() 扫描所有 .md 文件
2. 计算内容 MD5
3. 与数据库中的 content_hash 对比
4. 只重新解析发生变化的文件

只读工具会调用 ensureFresh()，根据文件 mtime 和 last_index 判断是否需要增量重建索引。

卡片盒方法

笔记类型

| Folder | Type | Atomic? | Lifecycle | | ------ | ---- | ------- | --------- | | 1-Fleeting/ | 临时想法 | No | unprocessed -> processed | | 2-Literature/ | 来源笔记 | Partial | unprocessed -> processed | | 3-Permanent/ | 一条笔记一个想法 | Yes | draft -> finalized | | 4-MOC/ | 主题索引 | No | draft -> active | | 5-Projects/ | 活跃目标 | No | active -> completed |

卢曼编号

1, 2, 3        独立主题线索
1a, 1b         从 1 分支
1a1, 1a2       从 1a 继续分支

连接评分

连接候选会根据多种信号评分：

• 共享标签：每个标签 +2
• 关键词重合：普通词 +1，长词 +2
• 中文关键词：支持中文连续文本的 2 字片段匹配
• 卢曼距离：父子 +7，兄弟 +5，近亲 +2
• 共享 MOC：+2
• 阈值：score >= 2 才会出现在候选中

工作流

想法   -> /zk:capture    -> Fleeting note
来源   -> /zk:literature -> Literature note
                 |
          /zk:promote
                 |
          Permanent note (auto zk_id) <-> connections
                 |
          /zk:finalize
                 |
          MOC (当 3+ 条相关笔记聚成主题时)

开发

git clone https://github.com/user/obsidian-zk-cn.git
cd obsidian-zk-cn
npm install
npm run build          # 编译 TypeScript
npm run dev            # watch mode
npm test               # 运行测试
npm run test:coverage  # 覆盖率

本地测试 MCP server：

# 针对测试 vault 启动 server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | node dist/cli/index.js serve --vault /path/to/vault

# 或在 Claude Code 中配置
claude mcp add obsidian-zk-cn -- node /path/to/obsidian-zk-cn/dist/cli/index.js serve --vault .

项目结构

src/
├── cli/index.ts          # CLI: init, update, serve
├── init/
│   ├── wizard.ts         # 交互式初始化
│   ├── scaffold.ts       # 创建目录、复制模板
│   └── updater.ts        # 同步模板、运行迁移
├── server/
│   ├── index.ts          # Stdio transport 入口
│   └── server.ts         # Tool + prompt 注册
├── vault/
│   ├── parser.ts         # Frontmatter, wikilinks, body
│   ├── scanner.ts        # 文件发现
│   └── writer.ts         # 笔记创建和编辑
├── db/
│   ├── schema.ts         # SQLite schema + migrations
│   └── index.ts          # DB 连接、索引、连接评分
├── tools/                # MCP tool 实现
│   ├── capture.ts
│   ├── literature.ts
│   ├── permanent.ts
│   ├── manage.ts
│   ├── moc.ts
│   ├── project.ts
│   ├── backlinks.ts
│   ├── search.ts
│   ├── analysis.ts
│   └── index-mgmt.ts
└── luhmann.ts            # ID 生成和排序

templates/
├── claude/skills/        # Claude Code slash-command skills
├── claude/agents/        # zk-analyzer agent
├── vault-folders/        # 默认 vault 目录和中文笔记模板
└── CLAUDE.md.template    # vault 项目指令模板

要求

• Node.js >= 18
• Claude Code
• Obsidian

License

MIT