llm-wiki-mcp

llm-wiki-mcp

KarpathyのLLM wiki gistを基にした、AIエージェント向けの永続的なMarkdown wikiです。4つのMCPツール（wiki_read、wiki_write_page、wiki_log_append、wiki_inventory）と、4つのClaude Codeスキル（wiki-init、wiki-ingest、wiki-query、wiki-lint）を備えています。stdioトランスポート、ローカルファイルシステムを使用します。

サーバーは、LLMが繰り返し誤りがちな面倒な処理を担います。アトミックな書き込み、etagの競合チェック、追記専用ログの整合性、パスの包含チェックです。スキルはエージェントが従うワークフローを提供します。wikiのスキーマは独自のwiki/CLAUDE.mdに置かれ、ドメインに合わせて拡張できます。サーバーにはレイヤー3のスキーマ検証はありません。

ステータス：アルファ版（v0.1.1）。ローカルバックエンドのみ。MITライセンス。

クイックスタート

Python 3.11+とuvが必要です。

wikiフォルダーの絶対パスを指定します。初回起動時に、存在しない場合はサーバーがそのフォルダー内に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"]
    }
  }
}

クライアントを再起動します。4つのツール（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から有効なスキーマを読み込むため、再インストールせずにスキーマを変更できます。エージェントには、次のような依頼ができます：

スキル	依頼内容	MCPサーバーが必要か
wiki-init	「AI安全性研究用のLLM wikiを~/wikis/ai-safetyに作成してください。」	いいえ
wiki-ingest	「https://arxiv.org/abs/2310.12345をwikiに取り込んでください。」	はい
wiki-query	「ステアリングベクトルについて、wikiには何と書かれていますか？」	はい
wiki-lint	「wikiのヘルスチェックを実行してください。」	はい

wiki-initは一度だけ実行するスキャフォルダーです。他の3つはKarpathyの3つの操作に対応します。

他のMCPクライアント（Claude Desktop、Cursor）では4つのツールを利用できますが、スキルは利用できません。エージェントはツールの説明だけを基にワークフローを導き出す必要があります。単発の読み書きには対応できますが、スキルで明示される記録作業（ログエントリー、バックリンク監査など）が省略されがちです。

4つのツール

ツール	アノテーション	目的
wiki_read	読み取り専用、べき等	1つのページを読み取ります。本文、解析済みフロントマター、外部リンク、etagを返します。
wiki_write_page	破壊的、べき等	etag CASを使用してアトミックに作成または更新します。作成時はetag=null、更新時は読み取り時のetagを渡します。
wiki_log_append	べき等ではない	Karpathyの## [YYYY-MM-DD] op | Title形式で、1つのエントリーをlog.mdに追記します。
wiki_inventory	読み取り専用、べき等	ページ、フロントマター、リンクエッジ、ログエントリーに加え、バックリンク監査用の任意のプレーンテキスト言及スキャンを含む、グラフ全体のスナップショットを作成します。

index.mdとraw/は、意図的にツールとして公開されていません。インデックスはLLMが編集・管理するコンテンツで、ホストのRead／Writeを使って編集します。サーバーからはrawレイヤーを変更できません。

Wikiの構成

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には、親プロジェクトフォルダー（raw/を含む）ではなく、キュレーション済みのwiki/フォルダーを指定します。初回のセットアップで間違えやすい点です。表示されるエラーについては、以下のトラブルシューティングのセクションで説明します。

設計上の境界

サーバーが強制するのは仕組みであり、コンテンツの形式ではありません。

• アトミックな書き込み。 ページには tmp-file + fsync + rename を使用します。ログエントリには O_APPEND による単一書き込みを使用します。
• 楽観的並行性制御。 各ページには etag（sha256(body) || mtime_ns）があります。更新時には読み取った etag を指定します。不一致の場合は WikiConflictError が発生し、エージェントが再読み込み、マージして再試行します。
• パスの包含チェック。 スラッグは正規表現で検証されます。解決されたパスはルートの実際のパスと照合され、CVE-2025-53109 のシンボリックリンクによるパス逸脱の類を防ぎます。
• 形式を固定したログ行。 ## [YYYY-MM-DD] operation | Title。操作名は任意の文字列ですが、行の形式を崩す文字は拒否されます。

サーバーは、フロントマターの形式、ページのカテゴリ、リンク先を検証しません。この層は wiki/CLAUDE.md のスキーマドキュメントにあり、LLM とともに発展します。Karpathy の gist はコンテンツ形式について意図的に触れていません。サーバーにスキーマを組み込むと、その趣旨に反します。

Python API

MCP サーバーを独自のストレージバックエンド（SQLite、Notion、GDrive、テスト用フェイク）でラップする場合は、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 以外のエージェントに組み込む場合は importlib.resources 経由で読み込めます。型付きドメインエラー（WikiConflictError、WikiNotFoundError、WikiPermissionError、WikiPathError、WikiSchemaViolationError）は、独自の境界で捕捉できるようパッケージのルートからインポートできます。

トラブルシューティング

uv tool install の後に llm-wiki-mcp: command not found と表示される。 uv はバイナリを ~/.local/bin（Windows では %USERPROFILE%\.local\bin）に配置します。ここを PATH に追加するか、永続的な shim を使わずに呼び出すには uvx llm-wiki-mcp ... を使用してください。

クライアント設定を編集した後も 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 skills セクションのマーケットプレイスコマンドを再実行してください。

開発

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 を参照してください。