Metadata-Version: 2.4
Name: myllmwiki-mcp
Version: 0.4.0
Summary: MCP server for MyLLMWiki (Obsidian) capture across Cursor, Codex, Claude
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.4.0`（`wiki_paths()` → `mcp_schema_version: "0.4"`）

完整版本历史见 [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/Rule 的关系**：

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

## 安装

### 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_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`。

## 推荐使用流程

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

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

**MCP 不能替代触发闸门** — 仍需要用户说「沉淀」或 rule/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"
      }
    }
  }
}
```

## 可配置目录

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

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

## 版本历史（摘要）

| 版本 | 要点 |
|------|------|
| **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+ | ❌ 多步易漏 |
| 需安装 | uvx / venv | symlink 即可 |
