myllmwiki-mcp 0.5.0

MCP server for MyLLMWiki (Obsidian) capture across Cursor, Codex, Claude

MyLLMWiki MCP Server

跨 Cursor / Codex / Claude Code 的统一 wiki 能力层。MCP 进程在宿主环境运行，不受 Codex 项目沙箱限制，写入 MyLLMWiki 更可靠。

当前版本：0.5.0（wiki_paths() → mcp_schema_version: "0.5"）

完整版本历史见 CHANGELOG.md。

架构

任意 vibecoding 工具
    │  MCP stdio
    ▼
myllmwiki-mcp (PyPI) / integrations/mcp/
    │  读 config.env + MYLLMWIKI_ROOT
    ▼
MyLLMWiki/wiki/  +  index.md  +  log.md  +  inbox.jsonl
    ▼
Obsidian

与 Skill/Rule 的关系：

层	职责
Skill / Rule	何时沉淀（触发词、质量闸门）
MCP	如何读写（路径、搜索、写页、记 log）
CAPTURE.md	写什么（SSOT 约定）

安装

PyPI（推荐，跨机器）

uvx myllmwiki-mcp
# 或
pip install myllmwiki-mcp

Cursor ~/.cursor/mcp.json：

{
  "mcpServers": {
    "myllmwiki": {
      "command": "uvx",
      "args": ["myllmwiki-mcp"],
      "env": {
        "MYLLMWIKI_ROOT": "/Users/jack/MyLLMWiki"
      }
    }
  }
}

本地开发（可编辑安装）

cd /Users/jack/MyLLMWiki/integrations/mcp
./debug.sh setup

# 或从仓库根：
./integrations/install.sh mcp

工具列表

Tool	版本	用途
wiki_paths	0.1	返回可配置路径 + mcp_schema_version
wiki_get_spec	0.1	读 CAPTURE.md
wiki_read_page	0.1	读任意 wiki 文件
wiki_search	0.3	带过滤器与打分的 wiki 搜索
wiki_get_context	0.3	编码/沉淀前拉取相关页摘要 + 项目页 + 近期 summary
wiki_list_recent	0.1	列出近期 summaries/projects/…
wiki_write_page	0.1	写入/追加页面（仅限受管目录）
wiki_append_log	0.1	追加 log.md 条目
wiki_inbox	0.1	追加会话索引
wiki_capture_checklist	0.1	返回沉淀步骤（用户已触发时）
wiki_update_index	0.2	插入/更新 index.md 分区表格行
wiki_list_by_status	0.2	按 frontmatter status 列页
wiki_set_status	0.2	设置页 frontmatter status
wiki_capture_session	0.4	原子沉淀：多页 + index + log（失败回滚）
wiki_synthesize_plan	0.5	梳理计划：inbox + raw summary + 建议动作
wiki_graph_links	0.5	链接图：wikilink、断链、孤立页、mermaid

wiki_search 过滤器

可组合：project:NAME tag:TAG category:summary status:raw

示例：WebSocket project:珍选 status:raw category:summary

wiki_capture_session 示例

用户说「沉淀」且 agent 已写好内容后，优先一次调用（可先 dry_run=True 预览）：

{
  "project": "珍选管理后台",
  "tool": "cursor",
  "title": "WebSocket 实时推送",
  "pages": [
    {
      "relative_path": "wiki/summaries/2026-05-22-websocket-珍选.md",
      "content": "---\ntype: session\nproject: 珍选管理后台\n---\n# ...",
      "mode": "write"
    },
    {
      "relative_path": "wiki/concepts/WebSocket实时推送.md",
      "content": "...",
      "mode": "append"
    }
  ],
  "index_updates": [
    {
      "section": "summaries",
      "page": "2026-05-22-websocket-珍选",
      "summary": "WebSocket 系统讲解与项目落地",
      "metadata": "capture 2026-05-22"
    },
    {
      "section": "concepts",
      "page": "WebSocket实时推送",
      "summary": "浏览器长连接实时推送模式"
    }
  ],
  "log_bullets": [
    "新建 summary + 更新概念页",
    "项目：珍选管理后台"
  ],
  "dry_run": false
}

返回 ok: true 时，pages / index / log 均已写入；失败则 rolled_back: true。

Synthesize 流程（v0.5）

用户说「梳理 wiki / 合并概念 / 做蓝图」后：

// 1. 生成工作计划
wiki_synthesize_plan({ "project": "珍选管理后台", "raw_limit": 30 })

// 2. 查看概念链接图
wiki_graph_links({ "category": "concepts", "limit": 40, "include_mermaid": true })

// 3. 按 suggested_actions 合并 concept，标记 merged
wiki_set_status("wiki/summaries/...", "merged")
wiki_capture_session({ "entry_type": "synthesize", ... })

wiki_synthesize_plan 返回 suggested_actions（如 distill_raw、create_blueprint、fix_broken_links）和 graph_summary.mermaid。

推荐使用流程

Capture（沉淀）

用户说「沉淀」后，agent 应：

1. wiki_capture_checklist(topics=[...], project="...")
2. wiki_get_context(...) 或 wiki_search(...) — 避免重复建页
3. wiki_capture_session(...) — 一次完成写页 + index + log（或分步调 wiki_write_page 等）

Synthesize（梳理）

1. wiki_get_spec() + wiki_synthesize_plan(project=...)
2. wiki_graph_links(...) — 断链与孤立页
3. 合并 concept / 写 blueprint + wiki_set_status(..., merged) + wiki_capture_session(entry_type="synthesize")

MCP 不能替代触发闸门 — 仍需要用户说「沉淀」或 rule/skill 约束。

Cursor 配置（本地 venv）

{
  "mcpServers": {
    "myllmwiki": {
      "command": "/Users/jack/MyLLMWiki/integrations/mcp/.venv/bin/myllmwiki-mcp",
      "args": [],
      "env": {
        "MYLLMWIKI_ROOT": "/Users/jack/MyLLMWiki"
      }
    }
  }
}

Codex 配置

~/.codex/config.toml：

[mcp_servers.myllmwiki]
type = "stdio"
command = "uvx"
args = ["myllmwiki-mcp"]

[mcp_servers.myllmwiki.env]
MYLLMWIKI_ROOT = "/Users/jack/MyLLMWiki"

Claude Code 配置

{
  "mcpServers": {
    "myllmwiki": {
      "command": "uvx",
      "args": ["myllmwiki-mcp"],
      "env": {
        "MYLLMWIKI_ROOT": "/Users/jack/MyLLMWiki"
      }
    }
  }
}

可配置目录

与 CLI 相同：编辑 integrations/config.env，或通过 MYLLMWIKI_CONFIG 指向配置文件。

本地测试

cd integrations/mcp
./debug.sh setup
./debug.sh smoke
./debug.sh inspector   # MCP Inspector

发布 PyPI

每次发版：改版本号 → 更新 CHANGELOG.md → 更新本 README → ./debug.sh smoke → 构建上传。

cd integrations/mcp
./debug.sh publish
twine upload dist/myllmwiki_mcp-0.5.0*

用户侧更新：uvx myllmwiki-mcp 会自动拉最新版（或重启 MCP 连接）。

版本历史（摘要）

版本	要点
0.5.0	wiki_synthesize_plan、wiki_graph_links
0.4.0	wiki_capture_session 原子沉淀
0.3.0	wiki_get_context、增强 wiki_search
0.2.0	wiki_update_index、wiki_list_by_status、wiki_set_status
0.1.0	基线读写 + checklist

详见 CHANGELOG.md。

优劣

	MCP	Skill + 直接写文件
跨工具	✅ 同一 server	❌ 每工具一套
Codex 沙箱	✅ 进程外写入	❌ 常需 escalation
路径校验	✅ server 内统一	❌ 靠 prompt
原子沉淀	✅ v0.4+	❌ 多步易漏
梳理/链接图	✅ v0.5+	❌ 靠人工 grep
需安装	uvx / venv	symlink 即可