llm-wiki-mcp

llm-wiki-mcp

为 AI Agent 打造的持久化 Markdown 知识库，基于 Karpathy 的 LLM wiki gist。包含四个 MCP 工具（wiki_read、wiki_write_page、wiki_log_append、wiki_inventory）和四个 Claude Code 技能（wiki-init、wiki-ingest、wiki-query、wiki-lint）。采用 stdio 传输，使用本地文件系统。

该服务负责处理大模型总是容易出错的繁琐底层工作：原子写入、etag 冲突检查、只追加日志的完整性、路径包含性检查。技能为 Agent 提供可遵循的工作流。知识库架构存放在你自己的 wiki/CLAUDE.md 中，并随你的领域不断扩展。服务中没有 Layer 3 架构验证。

状态：alpha（v0.1.1）。仅支持本地后端。采用 MIT 许可证。

快速开始

需要 Python 3.11+ 和 uv。

为知识库文件夹选择一个绝对路径。如果 pages/ 和 log.md 不存在，服务会在首次运行时创建它们：

uvx llm-wiki-mcp --wiki-root /absolute/path/to/wiki

将其接入你的 MCP 客户端。

Claude Code：

claude mcp add llm-wiki -- uvx llm-wiki-mcp --wiki-root /absolute/path/to/wiki

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）或 Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "llm-wiki": {
      "command": "uvx",
      "args": ["llm-wiki-mcp", "--wiki-root", "/absolute/path/to/wiki"]
    }
  }
}

重启客户端。此时应显示四个工具：wiki_read、wiki_write_page、wiki_log_append、wiki_inventory。

Claude Code 技能

Claude Code 用户可以将内置工作流技能安装为插件：

claude plugin marketplace add https://github.com/flsteven87/llm-wiki-mcp
claude plugin install llm-wiki-skills@llm-wiki-mcp

每次运行时，各技能都会读取 wiki/CLAUDE.md，获取当前架构，因此你可以演进架构，无需重新安装。可以向 Agent 提出以下问题：

技能	可以询问什么	是否需要 MCP 服务？
wiki-init	“为 AI 安全研究在 ~/wikis/ai-safety 创建一个 LLM 知识库。”	否
wiki-ingest	“将 https://arxiv.org/abs/2310.12345 导入知识库。”	是
wiki-query	“知识库对 steering vectors 有什么说法？”	是
wiki-lint	“运行知识库健康检查。”	是

wiki-init 是一次性脚手架工具；另外三个是 Karpathy 的三种操作。

其他 MCP 客户端（Claude Desktop、Cursor）可以使用这四个工具，但没有这些技能。Agent 只能根据工具描述自行推导工作流；对于一次性的读取和写入，这样做没问题，但往往会跳过技能明确要求的记录工作（日志条目、反向链接审计）。

四个工具

工具	注解	用途
wiki_read	只读、幂等	读取单个页面。返回正文、解析后的 frontmatter、出站链接和 etag。
wiki_write_page	有破坏性、幂等	以原子方式创建或更新页面，并使用 etag CAS。创建时传入 etag=null，更新时传入读取到的 etag。
wiki_log_append	非幂等	按照 Karpathy 的 ## [YYYY-MM-DD] op | Title 格式向 log.md 追加一条记录。
wiki_inventory	只读、幂等	快照整个图谱：页面、frontmatter、链接边、日志条目，以及用于反向链接审计的可选纯文本提及扫描。

index.md 和 raw/ 不会作为工具开放，这是有意为之。索引是由大模型整理的内容，通过宿主的 Read/Write 编辑。就服务而言，原始层不可变。

知识库布局

wiki-init 会搭建如下结构的项目：

your-project/
├── raw/                    Immutable source files (papers, articles, transcripts)
│   └── ...
└── wiki/                   ← --wiki-root points here
    ├── pages/              Markdown pages, one per topic
    ├── log.md              Append-only session log
    ├── index.md            LLM-curated browse page
    └── CLAUDE.md           Schema doc the LLM reads on every operation

--wiki-root 指向经过整理的 wiki/ 文件夹，而不是包含 raw/ 的父项目文件夹。首次安装时很容易弄错；下方的故障排除章节介绍了你会看到的错误。

设计边界

服务强制执行机制，而不限制内容格式：

• 原子写入。 页面使用 tmp-file + fsync + rename。日志条目使用 O_APPEND 单次写入。
• 乐观并发控制。 每个页面都有一个 etag（sha256(body) || mtime_ns）。更新时需提供读取到的 etag；如果不匹配，则会引发 WikiConflictError，Agent 会重新读取、合并并重试。
• 路径限制。 Slug 会通过正则表达式验证。解析后的路径会与根目录的 realpath 核对，从而阻止 CVE-2025-53109 类型的符号链接逃逸问题。
• 格式固定的日志行。 ## [YYYY-MM-DD] operation | Title。操作名称可以是任意字符串；只会拒绝那些会破坏行格式的字符。

服务不会验证 frontmatter 格式、页面分类或链接目标。这一层由 wiki/CLAUDE.md 架构文档负责，并随大模型的发展而扩展。Karpathy 的 gist 刻意不规定内容格式；在服务中内置架构会违背初衷。

Python API

如果你想用自己的存储后端（SQLite、Notion、GDrive、测试替身）封装 MCP 服务，请实现 WikiStorage Protocol，并将实例传给 build_server：

from llm_wiki_mcp import WikiStorage, PageRead, LogEntry
from llm_wiki_mcp.server import build_server

class MyStorage:  # satisfies the WikiStorage Protocol
    async def read_page(self, slug: str) -> PageRead: ...
    async def write_page(self, slug, body, expected_etag=None) -> str: ...
    async def list_pages(self) -> list[str]: ...
    async def append_log(self, entry: LogEntry) -> None: ...
    async def read_log(self) -> str: ...
    async def write_raw_file(self, name, data) -> None: ...  # usually raises

server = build_server(storage=MyStorage())
server.run()

build_server 是组合根。CLI main() 是一个轻量调用方，它根据 --wiki-root 构造 LocalFilesystemStorage 并将其传入。

随附的 Claude Code 技能以包数据的形式存放在 llm_wiki_mcp/skills/ 下；如果你想将它们接入非 Claude Code Agent，可通过 importlib.resources 加载。类型化领域错误（WikiConflictError、WikiNotFoundError、WikiPermissionError、WikiPathError、WikiSchemaViolationError）可从包根导入，以便在自己的边界处捕获。

故障排除

运行 uv tool install 后出现 llm-wiki-mcp: command not found。 uv 会将二进制文件放在 ~/.local/bin（Windows 上为 %USERPROFILE%\.local\bin）。将其添加到 PATH，或使用 uvx llm-wiki-mcp ... 调用，无需持久化 shim。

编辑客户端配置后未显示 wiki_* 工具。 重启 MCP 客户端。Claude Desktop、Claude Code 和 Cursor 只会在启动时重新读取 mcpServers。

出现 WikiPathError: path escapes wiki root。 你将 --wiki-root 指向了包含 raw/ 的项目文件夹，而不是其中经过整理的 wiki/ 文件夹。/Users/me/wikis/ai-safety/wiki 是正确的；/Users/me/wikis/ai-safety 则不正确。

Claude Code 未加载技能。 运行 claude plugin list。如果列表中没有 llm-wiki-skills，请重新运行 Claude Code 技能部分中的 marketplace 命令。

开发

git clone https://github.com/flsteven87/llm-wiki-mcp
cd llm-wiki-mcp
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run pyright src/llm_wiki_mcp

许可证

MIT。请参阅 LICENSE。