Llm Wiki Mcp

io.github.flsteven87由 GitHub 账号 flsteven87 发布v0.1.1更新于 Oct 24, 2026

MCP server for Karpathy-style LLM wikis: persistent markdown your agent grows over time.

概览

AI 生成的概览

本地 stdio MCP 服务器,为助手提供一个可长期读写的 Markdown 维基,支持读取、写入、记录日志与盘点。

可以做什么
  • 读取单个维基页面,返回正文、解析后的 frontmatter、出链与 etag
  • 以原子写入和 etag 冲突校验创建或更新页面
  • 向只追加的会话日志写入带日期的条目
  • 生成整站快照:页面、frontmatter、链接边、日志条目,并可扫描纯文本提及以审计反向链接
  • 可选搭配随附的 Claude Code 技能,完成初始化、摄取、查询与检查流程
适用场景
适合希望助手跨会话积累可读笔记、而不是丢失上下文的场景,例如根据论文和文章构建研究或主题维基。最适合使用 Claude Code 并希望获得引导式摄取、查询、检查流程的用户;其他客户端只能使用四个工具。
运行要求
通过 uvx 从 PyPI 包 llm-wiki-mcp 以 stdio 在本地运行。需要 Python 3.11+ 与 uv,并通过 --wiki-root 传入指向维基目录的绝对路径。未声明任何账号、API 密钥或环境变量。配置后需重启客户端。
安装前请注意
写入工具标注为破坏性操作,会覆盖页面内容;日志追加非幂等,重复调用会产生重复条目。服务器只保证路径约束与原子写入,不校验 frontmatter、分类或链接目标。目前为 alpha 版本且仅支持本地后端,--wiki-root 指向错误目录会报路径错误。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Llm Wiki Mcp,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

llm-wiki-mcp

Persistent markdown wiki for your AI agent, built on Karpathy's LLM wiki gist. Four MCP tools (wiki_read, wiki_write_page, wiki_log_append, wiki_inventory) plus four Claude Code skills (wiki-init, wiki-ingest, wiki-query, wiki-lint). stdio transport, local filesystem.

The server handles the boring layer LLMs keep getting wrong: atomic writes, etag conflict checks, append-only log integrity, path containment. The skills give the agent a workflow to follow. The wiki schema lives in your own wiki/CLAUDE.md and grows with your domain. There is no Layer 3 schema validation in the server.

Status: alpha (v0.1.1). Local backend only. MIT licensed.

Quick start

Requires Python 3.11+ and uv.

Pick an absolute path for the wiki folder. The server creates pages/ and log.md under it on first run if they don't exist:

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

Wire it into your MCP client.

Claude Code:

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

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) or Cursor (~/.cursor/mcp.json):

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

Restart the client. Four tools should appear: wiki_read, wiki_write_page, wiki_log_append, wiki_inventory.

Claude Code skills

Claude Code users can install the bundled workflow skills as a plugin:

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

Each skill reads wiki/CLAUDE.md for the active schema on every run, so you can evolve the schema without re-installing anything. Ask the agent things like:

SkillWhat to askNeeds MCP server?
wiki-init"Create an LLM wiki for AI safety research at ~/wikis/ai-safety."No
wiki-ingest"Ingest https://arxiv.org/abs/2310.12345 into the wiki."Yes
wiki-query"What does the wiki say about steering vectors?"Yes
wiki-lint"Run a wiki health check."Yes

wiki-init is a one-shot scaffolder; the other three are Karpathy's three operations.

Other MCP clients (Claude Desktop, Cursor) get the four tools but not the skills. The agent has to derive the workflow from tool descriptions alone, which works for one-off reads and writes but tends to skip the bookkeeping (log entries, backlink audits) the skills make explicit.

The four tools

ToolAnnotationsPurpose
wiki_readread-only, idempotentRead one page. Returns body, parsed frontmatter, outgoing links, etag.
wiki_write_pagedestructive, idempotentAtomic create or update with etag CAS. Pass etag=null to create, the read etag to update.
wiki_log_appendnot idempotentAppend one entry to log.md in Karpathy's ## [YYYY-MM-DD] op | Title format.
wiki_inventoryread-only, idempotentSnapshot the whole graph: pages, frontmatter, link edges, log entries, plus an optional plain-text mention scan for backlink audits.

index.md and raw/ are intentionally not exposed as tools. The index is LLM-curated content edited via the host's Read/Write. The raw layer is immutable from the server's perspective.

Wiki layout

wiki-init scaffolds a project that looks like this:

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 points at the curated wiki/ folder, not the parent project folder containing raw/. Easy to get wrong on first install; the troubleshooting section below covers the error you'll see.

Design boundary

The server enforces mechanics, not content shape:

  • Atomic writes. tmp-file + fsync + rename for pages. O_APPEND single-write for log entries.
  • Optimistic concurrency. Every page has an etag (sha256(body) || mtime_ns). Updates supply the etag they read; a mismatch raises WikiConflictError, and the agent re-reads, merges, and retries.
  • Path containment. Slugs are regex-validated. Resolved paths are checked against the realpath of the root, blocking the CVE-2025-53109 symlink-escape class.
  • Format-locked log line. ## [YYYY-MM-DD] operation | Title. Operation names are free strings; only characters that would break the line shape are rejected.

The server does not validate frontmatter shape, page categories, or link targets. That layer lives in your wiki/CLAUDE.md schema doc and grows with the LLM. Karpathy's gist is deliberately silent on content shape; baking a schema into the server would defeat the point.

Python API

If you want to wrap the MCP server with your own storage backend (SQLite, Notion, GDrive, a test fake), implement the WikiStorage Protocol and pass an instance to build_server:

python
from llm_wiki_mcp import WikiStorage, PageRead, LogEntryfrom 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 is the composition root. The CLI main() is a thin caller that constructs LocalFilesystemStorage from --wiki-root and hands it in.

The bundled Claude Code skills ship as package data under llm_wiki_mcp/skills/ and load via importlib.resources if you want to wire them into a non-Claude-Code agent. Typed domain errors (WikiConflictError, WikiNotFoundError, WikiPermissionError, WikiPathError, WikiSchemaViolationError) are importable from the package root for catching at your own boundary.

Troubleshooting

llm-wiki-mcp: command not found after uv tool install. uv puts the binary in ~/.local/bin (or %USERPROFILE%\.local\bin on Windows). Add it to PATH, or use uvx llm-wiki-mcp ... to invoke without a persistent shim.

wiki_* tools don't appear after editing the client config. Restart the MCP client. Claude Desktop, Claude Code, and Cursor only re-read mcpServers at startup.

WikiPathError: path escapes wiki root. You pointed --wiki-root at the project folder containing raw/ instead of the curated wiki/ folder inside it. /Users/me/wikis/ai-safety/wiki is correct; /Users/me/wikis/ai-safety is not.

Skills not loading in Claude Code. Run claude plugin list. If llm-wiki-skills is missing, rerun the marketplace commands in the Claude Code skills section.

Development

bash
git clone https://github.com/flsteven87/llm-wiki-mcpcd llm-wiki-mcpuv sync --extra devuv run pytestuv run ruff check .uv run pyright src/llm_wiki_mcp

License

MIT. See LICENSE.

来源:README.md,提交 16463f0

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

1
  1. v0.1.1最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分