Metadata-Version: 2.4
Name: myllmwiki-mcp
Version: 0.1.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 更可靠。

## 架构

```
任意 vibecoding 工具
    │  MCP stdio
    ▼
integrations/mcp/server.py
    │  读 config.env
    ▼
MyLLMWiki/wiki/  +  index.md  +  log.md  +  inbox.jsonl
    ▼
Obsidian
```

**与 Skill/Rule 的关系**：

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

## 安装

```bash
cd /Users/jack/MyLLMWiki/integrations/mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

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

## 工具列表

| Tool | 用途 |
|------|------|
| `wiki_paths` | 返回可配置路径（同 `myllmwiki paths`） |
| `wiki_get_spec` | 读 `CAPTURE.md` |
| `wiki_read_page` | 读任意 wiki 文件 |
| `wiki_search` | 在 `wiki/` 内搜索 |
| `wiki_list_recent` | 列出近期 summaries/projects/… |
| `wiki_write_page` | 写入/追加页面（仅限受管目录） |
| `wiki_append_log` | 追加 `log.md` 条目 |
| `wiki_inbox` | 追加会话索引 |
| `wiki_capture_checklist` | 返回沉淀步骤（用户已触发时） |

## Cursor 配置

`~/.cursor/mcp.json` 或项目 `.cursor/mcp.json`：

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

## Codex 配置

`~/.codex/config.toml`：

```toml
[mcp_servers.myllmwiki]
type = "stdio"
command = "/Users/jack/MyLLMWiki/integrations/mcp/.venv/bin/python"
args = ["/Users/jack/MyLLMWiki/integrations/mcp/server.py"]

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

重启 Codex 后在工具列表中应出现 `myllmwiki` MCP。

## Claude Code 配置

`~/.claude/settings.json` 或项目 `.mcp.json`（视版本而定）：

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

## 推荐使用方式

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

1. `wiki_capture_checklist(topics=[...], project="...")`
2. `wiki_get_spec()` + `wiki_search(...)` 避免重复建页
3. `wiki_write_page(...)` 写 summary / concept / project
4. `wiki_append_log(...)` + 更新 `wiki/index.md`

**MCP 不能替代触发闸门** — 仍需要用户说「沉淀」或 rule/skill 约束，避免自动写 wiki。

## 可配置目录

与 CLI 相同：编辑 `integrations/config.env`，MCP 启动时自动加载。

## 本地测试

```bash
source integrations/mcp/.venv/bin/activate
python integrations/mcp/server.py   # stdio，需 MCP 客户端连接

# 或快速测 paths 模块：
python -c "from paths import load_paths; print(load_paths())"
```

## 优劣

| | MCP | Skill + 直接写文件 |
|---|-----|-------------------|
| 跨工具 | ✅ 同一 server | ❌ 每工具一套 |
| Codex 沙箱 | ✅ 进程外写入 | ❌ 常需 escalation |
| 路径校验 | ✅ server 内统一 | ❌ 靠 prompt |
| 实现成本 | 中 | 低 |
| 需安装 | venv + 各工具注册 | symlink 即可 |
