Metadata-Version: 2.4
Name: myllmwiki-mcp
Version: 0.8.1
Summary: MCP server for MyLLMWiki (Obsidian) capture across Cursor, Codex, Claude
Project-URL: Homepage, https://github.com/makechange/wiki-mcp
Project-URL: Documentation, https://github.com/makechange/wiki-mcp/blob/main/integrations/mcp/README.md
Project-URL: Changelog, https://github.com/makechange/wiki-mcp/blob/main/integrations/mcp/CHANGELOG.md
Project-URL: Repository, https://github.com/makechange/wiki-mcp
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2.0

# MyLLMWiki MCP Server

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

**当前版本**：`0.8.1`（`wiki_paths()` → `mcp_schema_version: "0.8"`）

> **PyPI 说明页**来自本 README（`pyproject.toml` → `readme`）。发版前务必更新本文，否则 PyPI 会显示旧版说明。
>
> **Skills 不在 PyPI**。完整用法（7× `/wiki:*` 或 `$wiki-*`、安装、更新）见 [wiki-mcp](https://github.com/makechange/wiki-mcp) 与 **[OPERATIONS.md](https://github.com/makechange/wiki-mcp/blob/main/integrations/OPERATIONS.md)**：
>
> ```bash
> git clone https://github.com/makechange/wiki-mcp.git
> ./integrations/install.sh setup --vault /path/to/vault --tools cursor,codex,mcp,cli
> ```

完整版本历史见 [CHANGELOG.md](./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（推荐，跨机器）

```bash
uvx myllmwiki-mcp
# 或
pip install myllmwiki-mcp
```

Cursor `~/.cursor/mcp.json`：

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

### 本地开发（可编辑安装）

```bash
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` 预览）：

```json
{
  "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）

```python
# 巡检（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 / 合并概念 / 做蓝图」后：

```json
// 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）

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

## Codex 配置

`~/.codex/config.toml`：

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

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

## Claude Code 配置

```json
{
  "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：

```json
{
  "mcpServers": {
    "myllmwiki": {
      "command": "uvx",
      "args": ["myllmwiki-mcp"],
      "env": {
        "MYLLMWIKI_ROOT": "/Users/jack/MyLLMWiki"
      }
    }
  }
}
```
保存文件后，在 Antigravity 的 MCP 界面点击 **Refresh** 刷新即可。

### 方法 B：使用 Antigravity CLI 命令行添加
如果习惯命令行操作，可以在终端中使用 `antigravity mcp add` 命令直接安装第三方 MCP 服务：
```bash
antigravity mcp add myllmwiki -- uvx myllmwiki-mcp
```
*(提示：该命令会自动将配置合并写入上述的 `mcp_config.json` 中)*


## 可配置目录

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

## 本地测试

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

## 发布 PyPI

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

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

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

## 版本历史（摘要）

| 版本 | 要点 |
|------|------|
| **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](./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 即可 |
