myllmwiki-mcp 0.8.0

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

MyLLMWiki MCP Server

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

当前版本：0.8.0（wiki_paths() → mcp_schema_version: "0.8"）

PyPI 说明页来自本 README（pyproject.toml → readme）。发版前务必更新本文，否则 PyPI 会显示旧版说明。

Skills 不在 PyPI。完整用法（7× /wiki:* 或 $wiki-*、安装、更新）见 wiki-mcp 与 OPERATIONS.md：

git clone https://github.com/makechange/wiki-mcp.git
./integrations/install.sh setup --vault /path/to/vault --tools cursor,codex,mcp,cli

完整版本历史见 CHANGELOG.md。

架构

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

与 Skill 的关系：

层	职责
Skill（slash / $wiki-*）	何时沉淀（显式触发、质量闸门）
MCP	如何读写（Tools + Resources + Prompts）
CAPTURE.md	写什么（SSOT 约定；Resource myllmwiki://spec）

安装

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_list_mcp_catalog	0.6	列出 Resources / Prompts 目录
wiki_read_resource	0.6	按 URI 读 Resource（桥接）
wiki_lint	0.7	巡检 index / 断链 / 孤立 / 重名 / raw 积压
wiki_merge_concept	0.7	合并 concept；重定向 wikilink；stub 来源页
wiki_upsert_transcript	0.8	写入/覆盖 raw/sessions transcript（按 session_id）
wiki_find_transcript	0.8	按 session_id 查 transcript 或列近期索引
wiki_list_codex_sessions	0.8	列出 ~/.codex/sessions rollout（只读）
wiki_export_codex_transcript	0.8	Codex JSONL → chat-clean Markdown + 索引

MCP Resources（v0.6）

只读 URI，客户端可 attach 到上下文（比 tool 更省 token 时适用）：

URI	内容
myllmwiki://spec	CAPTURE.md
myllmwiki://index	wiki/index.md
myllmwiki://log	wiki/log.md
myllmwiki://agents	AGENTS.md
myllmwiki://paths	路径 JSON
myllmwiki://manifest	Resource/Prompt 目录
myllmwiki://template/{name}	session / project / blueprint 模板
myllmwiki://wiki/{category}/{page}	按分类读页（如 concepts/WebSocket实时推送）

无原生 Resources 的客户端：wiki_read_resource("myllmwiki://spec") 或 wiki_list_mcp_catalog()。

MCP Prompts（v0.6+，0.7.1 增 ingest/lint）

Prompt	版本	参数	用途
capture_wiki	0.6	project, topics?, tool?	用户说「沉淀」后注入 capture 工作流（含 raw session 层）
ingest_wiki	0.7.1	source, project?, topics?	处理 raw/ 策展素材 → wiki/（raw 只读）
synthesize_wiki	0.6	project?	用户说「梳理/做蓝图」后注入 synthesize 工作流
query_wiki	0.6	question, project?	答题前先查 wiki
lint_wiki	0.7.1	project?	巡检断链、孤立页、重复概念、index 缺口

在 Cursor / Claude Code 的 MCP Prompt 面板选用；或参照 Prompt 文本手动执行对应 tools。

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。

Lint / Merge（v0.7）

# 巡检（checks 可选: index, links, orphans, duplicates, status）
wiki_lint()

# 合并重复 concept（先 dry_run 预览）
wiki_merge_concept(
    target="WebSocket实时推送",
    sources=["旧概念页标题"],
    rewire_links=True,
    dry_run=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（沉淀）

用户说「沉淀」或 /wiki:capture 后，agent 应：

1. wiki_inbox(...) + 写 raw/sessions/ 原始会话页（Karpathy raw 层）
2. wiki_capture_checklist(topics=[...], project="...")
3. wiki_get_context(...) 或 wiki_search(...) — 避免重复建页
4. wiki_capture_session(...) — 一次完成写页 + index + log（或分步调 wiki_write_page 等）

Ingest（策展素材）

用户说「ingest」或 /wiki:ingest 后：

1. MCP Prompt ingest_wiki（或 wiki_get_spec() 读 CAPTURE ingest 节）
2. 读 raw/ 指定来源（只读，不改 raw）
3. 写 summaries/ + 相关 concepts//projects/，更新 index.md + log.md

Synthesize（梳理）

1. wiki_get_spec() + wiki_lint() + wiki_synthesize_plan(project=...)
2. wiki_graph_links(...) — 断链与孤立页
3. wiki_merge_concept(...) + wiki_set_status(..., merged) + wiki_capture_session(entry_type="synthesize")

MCP 不能替代触发闸门 — 仍需要用户显式 slash 或 $wiki-* 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"
      }
    }
  }
}

Antigravity 配置

方法 A：编辑 mcp_config.json 配置文件（推荐）

在 Antigravity 界面进入 Settings > Customizations > Open MCP Config，或者直接打开本地配置文件 ~/.gemini/antigravity/mcp_config.json，在 mcpServers 字段下添加你的第三方/自定义 MCP Server：

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

保存文件后，在 Antigravity 的 MCP 界面点击 Refresh 刷新即可。

方法 B：使用 Antigravity CLI 命令行添加

如果习惯命令行操作，可以在终端中使用 antigravity mcp add 命令直接安装第三方 MCP 服务：

antigravity mcp add myllmwiki -- uvx myllmwiki-mcp

(提示：该命令会自动将配置合并写入上述的 mcp_config.json 中)

可配置目录

与 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-*

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

版本历史（摘要）

版本	要点
0.8.0	Codex session transcript 导出；wiki-transcript skill；transcript-index
0.7.3	bundled CAPTURE + PyPI README：slash/$wiki-* 触发说明；指向 OPERATIONS
0.7.2	同步 PyPI README（ingest/lint prompts、raw 层流程）
0.7.1	ingest_wiki / lint_wiki prompts；bundled CAPTURE 同步
0.7.0	wiki_lint、wiki_merge_concept
0.6.0	MCP Resources + Prompts + 桥接 tools
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
Resources/Prompts	✅ v0.6+	❌ 仅 tools
Lint / 合并	✅ v0.7+	❌ 手工 grep
需安装	uvx / venv	symlink 即可