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 分