llm-wiki-mcp

English | 中文

An MCP server that gives your AI agents a governed wiki instead of unrestricted filesystem access. It sits between "full power" and "read-only" by requiring human approval before any formal wiki page gets updated.

Design philosophy draws from Karpathy's LLM Wiki methodology: compile knowledge into a reusable wiki during ingest/maintenance, rather than re-synthesizing from raw sources on every query. Astro-Han/karpathy-llm-wiki and multica-ai/andrej-karpathy-skills served as engineering references.

The project started by hand-crafting ~/llm-wiki to validate the workflow, then abstracting it into an MCP server — the tool design comes from real usage, not theory.

Why this exists

When you use an AI agent to build a knowledge base, it can read and write pages. Without constraints:

• It overwrites pages you spent time curating.

• Files end up scattered across directories with no consistent structure.

• It updates index.md without recording what changed.

• There's no audit trail of who changed what and why.

This server forces every write to go through a candidate review cycle. The agent proposes changes, you review and approve them, and only then does the wiki update.

Related MCP server: agent-wiki

What it does

• Candidate-first writes — formal pages, index updates, and public exports are proposals. Nothing gets written until you call apply_candidate.

• Immutable raw sources — raw/ files can only be created, never overwritten. Your source material stays intact.

• Path safety — all operations stay within wiki_root. Parent-traversal attempts are rejected at the path layer.

• Structured linting — run_lint returns parsed results (errors, warnings, suggestions) as data, not a process exit code that breaks the MCP transport.

• Change log — every mutation is logged with action, impact, and verification, with configurable retention.

• Search that tells you what to do next — formal pages and raw sources are ranked separately. Scope-aware search returns a next_action hint (read_page vs read_raw_source).

• Frontmatter validation — unknown fields, empty directory lists, and invalid retention values are caught before they reach your wiki.

Workflow

New / revised source added
        ↓
compile_page or create_update_candidate
        ↓
Review Candidate bundle (page, index, public-draft, log, source-manifest)
        ↓
apply_candidate after explicit approval
        ↓
run_lint

Agents return persisted Candidate bundles first. You (or your agent's human-in-the-loop) review the full change set before anything touches the formal wiki.

Quick Start

git clone https://github.com/jaronlu/llm-wiki-mcp.git
cd llm-wiki-mcp
uv sync --dev
cp config/examples.config.yaml config/config.yaml
uv run llm-wiki-mcp

Edit config/config.yaml for your machine. Keep it local and untracked.

wiki_root: ~/llm-wiki
allow_write_raw: false
allow_write_formal: false
allow_update_index: false
allow_modify_schema: false
log_retention_entries: 120
formal_dirs: [domains, entities]
raw_dirs: [raw]
workshop_dirs: [workshop]
non_formal_dirs: [drafts, reading]

workshop_dirs enables project packages whose root README.md is a formal entity page and whose raw/ subtree contains project evidence:

llm-wiki/
├── workshop/
│   ├── agentic-rag-securities/
│   │   ├── README.md
│   │   └── raw/
│   └── wiki-mcp/
│       ├── README.md
│       └── raw/
├── domains/
├── entities/
└── raw/

MCP tools

Mutation tools are conservative by default. Raw writes require allow_write_raw: true; applying candidates requires allow_write_formal: true.

Configuration

Config loading order:

1. Built-in defaults.

2. Project-local config/config.yaml, when present.

The server intentionally ignores MCP host config path environment variables and root override environment variables, so the runtime source of truth stays in the repository-local config file.

Config validation rejects unknown top-level fields, nested directory names, empty directory lists, and non-positive log_retention_entries values.

Safety boundaries

• All paths must resolve under wiki_root.

• init_wiki creates or completes wiki_root by default when no explicit root argument is provided.

• raw/ writes are create-only and never overwrite existing files.

• Formal page writes require allow_write_formal: true; index.md updates, migrations, and public exports are candidate-first.

• .llm-wiki/source-manifest.json tracks raw source digests without modifying page frontmatter.

• run_lint returns structured lint data instead of treating lint failures as MCP transport failures.

MCP Host Config

[mcp_servers.llm_wiki]
command = "uv"
args = ["--directory", "/path/to/llm-wiki-mcp", "run", "llm-wiki-mcp"]
startup_timeout_sec = 120

The server always reads configuration from <repo>/config/config.yaml; no MCP host environment variable is needed.

Development

uv run ruff check .
uv run pytest

Contributing

See CONTRIBUTING.md for development setup and design rules.

License

MIT — see LICENSE.