MyLLMWiki MCP Server
跨 Cursor / Codex / Claude Code 的统一 wiki 能力层。MCP 进程在宿主环境运行,不受 Codex 项目沙箱限制,写入 MyLLMWiki 更可靠。
当前版本:0.8.2(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 + 索引 |
wiki_list_cursor_sessions |
0.8.2 | 列出 Cursor agent-transcripts(只读) |
wiki_export_cursor_transcript |
0.8.2 | Cursor 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 应:
wiki_inbox(...)+ 写raw/sessions/原始会话页(Karpathy raw 层)wiki_capture_checklist(topics=[...], project="...")wiki_get_context(...)或wiki_search(...)— 避免重复建页wiki_capture_session(...)— 一次完成写页 + index + log(或分步调wiki_write_page等)
Ingest(策展素材)
用户说「ingest」或 /wiki:ingest 后:
- MCP Prompt
ingest_wiki(或wiki_get_spec()读 CAPTURE ingest 节) - 读
raw/指定来源(只读,不改 raw) - 写
summaries/+ 相关concepts//projects/,更新index.md+log.md
Synthesize(梳理)
wiki_get_spec()+wiki_lint()+wiki_synthesize_plan(project=...)wiki_graph_links(...)— 断链与孤立页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.2 | Cursor transcript:agent-transcripts JSONL → User/Agent;--cwd 映射 project slug |
| 0.8.1 | Codex transcript:解析 TRANSCRIPT START、跳过 guardian/tool/审批 JSON;latest 排除 subagent |
| 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 即可 |
Metadata
Release files for myllmwiki-mcp 0.8.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| myllmwiki_mcp-0.8.2.tar.gz | 46.0 kB | Without provenance | Details for myllmwiki_mcp-0.8.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| myllmwiki_mcp-0.8.2-py3-none-any.whl | Python 3 | none | any | Details for myllmwiki_mcp-0.8.2-py3-none-any.whl |
Total release size: 98.5 kB
Release files / myllmwiki_mcp-0.8.2.tar.gz
| Download URL | myllmwiki_mcp-0.8.2.tar.gz |
|---|---|
| Size | 46.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
06b1eef3d60d050a28e05bb8499fbc8b719dbaf135528afca01c4a66b028bee3
|
|
BLAKE2b-256 checksum How to use checksums |
f53f3574c9d466c2839c5e37a89c5450b327b130f0ebbe3d44a7a146e39a3330
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.7
|
Release files / myllmwiki_mcp-0.8.2-py3-none-any.whl
| Download URL | myllmwiki_mcp-0.8.2-py3-none-any.whl |
|---|---|
| Size | 52.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6fd71b570936be57be4a73521955a805467d07cb0cb92dd561ade5e24ca9ab37
|
|
BLAKE2b-256 checksum How to use checksums |
b198b615551a2249f159c1cf6a4ea30dbccb2b08500c15dd405a674bd7448e9c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.7
|
Security for myllmwiki-mcp 0.8.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.