llm-wiki-mcp
This MCP server lets you govern an LLM wiki by proposing, reviewing, and applying wiki changes through a human approval gate.
Initialize and inspect wiki structures.
Search formal pages and raw sources with scope-aware results.
Read formal pages and immutable raw source files.
Create new raw sources without overwriting existing files.
Append structured change-log entries with retention trimming.
Compile raw sources into persisted formal-page candidates.
Create candidate updates for existing pages, including sources, sections, and wikilinks.
Apply approved candidate bundles atomically.
Run structured lint checks and knowledge-health reviews.
Create public-facing draft candidates and validate them for sensitive content.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@llm-wiki-mcp search wiki for 'neural networks'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
llm-wiki-mcp
One line: an MCP(Model Context Protocol) server that lets an agent propose wiki changes but requires human approval before any formal page is updated.
Run in 30 seconds
python3 -m compileall -q srcZero-dependency syntax smoke check; verified locally.
Verifiable: git rev-list --count HEAD -> 26 commits; find src -name '*.py' | wc -l -> 17 source files / 3,980 lines; grep -rho 'def test_' tests --include='*.py' | wc -l -> 87 test definitions. Static counts from the local HEAD.
What this is not: no unrestricted filesystem write access for agents, no auto-approval. Known issue: pyproject.toml allows mcp>=1.0.0 while the code imports mcp.server.fastmcp, renamed in mcp 2.x; uv run pytest currently fails at collection. Pin mcp<2 before running the full suite.
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.mdwithout 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: cortex-brain
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_lintreturns 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_actionhint (read_pagevsread_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_lintAgents 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-mcpEdit 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
Tool | What it does |
| Creates or completes a wiki root with scaffolding |
| Checks if a directory is a valid wiki and reports status |
| Scope-aware search across formal pages and raw sources |
| Reads a formal page with parsed frontmatter and link analysis |
| Reads raw source files (immutable view) |
| Creates a new raw source (create-only, no overwrite) |
| Appends a structured change-log entry |
| Builds a candidate formal page from raw sources |
| Builds a candidate index update |
| Applies a previously-reviewed candidate bundle |
| Runs structured lint checks and returns parsed results |
| Reviews wiki health (coverage, orphans, stale pages) |
| Creates a public-facing draft (candidate-first) |
| Checks that public exports don't leak sensitive content |
Mutation tools are conservative by default. Raw writes require allow_write_raw: true; applying candidates requires allow_write_formal: true.
Configuration
Config loading order:
Built-in defaults.
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_wikicreates or completeswiki_rootby default when no explicitrootargument is provided.raw/writes are create-only and never overwrite existing files.Formal page writes require
allow_write_formal: true;index.mdupdates, migrations, and public exports are candidate-first..llm-wiki/source-manifest.jsontracks raw source digests without modifying page frontmatter.run_lintreturns 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 = 120The server always reads configuration from <repo>/config/config.yaml; no MCP host environment variable is needed.
Development
uv run ruff check .
uv run pytestContributing
See CONTRIBUTING.md for development setup and design rules.
License
MIT — see LICENSE.
Available Tools
14 toolsappend_logB
Append a structured entry to log.md and trim old entries to retention.
Inputs: action (required), impact (required), reason (required), changes (required), +4 more. Returns: object
apply_candidateC
Apply an approved Candidate bundle atomically.
Inputs: approved (required), candidate_id (required), ops, bundle_id, +3 more. Returns: object
compile_pageC
Compile a raw source into a persisted formal page Candidate.
Inputs: source (required), tags, topic, domain, +3 more. Returns: object
create_raw_sourceA
Create a new raw source under raw/. Existing files are never overwritten.
Inputs: path (required), content (required), request_id. Returns: object
create_update_candidateC
Generate a persisted update Candidate for an existing formal page.
Inputs: page (required), title (required), source, request_id, +5 more. Returns: object
init_wikiC
Initialize a minimal Karpathy-style LLM Wiki structure without overwriting by default.
Inputs: root, profile, language, request_id. Returns: object
inspect_wikiC
Inspect whether a directory has the minimal llm-wiki structure.
Inputs: root, request_id. Returns: object
knowledge_health_reviewC
Summarize wiki health across lint, sources, duplicates, stale pages, and confidence.
Inputs: request_id. Returns: object
read_pageC
Read a formal llm-wiki page and return wiki metadata.
Inputs: page (required), limit, offset, request_id. Returns: object
read_raw_sourceC
Read an evidence-preserving raw source under raw/.
Inputs: path (required), limit, offset, request_id. Returns: object
run_lintC
Run wiki lint and return structured lint results.
Inputs: mode, request_id, timeout_seconds. Returns: object
search_wikiC
Search llm-wiki formal pages and/or raw sources with wiki metadata.
Inputs: query (required), mode, type, limit, +3 more. Returns: object
validate_public_safetyC
Validate public-site candidate content for sensitive material.
Inputs: page, content, request_id. Returns: object
write_public_draftC
Render a public-site markdown draft candidate without publishing it.
Inputs: page (required), title, redact, request_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool targets a distinct action in the wiki lifecycle (init, inspect, read, write, compile, apply, lint, search, log, health review, validate, draft). There is no overlap or ambiguity between tool purposes.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_raw_source, apply_candidate, knowledge_health_review). No mixing of conventions or vague verbs.
14 tools is well-scoped for a wiki management server. The number covers all necessary operations without being excessive or insufficient.
The tool set covers the full lifecycle from initialization to inspection, raw source management, candidate compilation and application, linting, health review, search, logging, and public draft writing. No obvious gaps for the intended domain.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Shared project wiki for AI agents: read and write pages, next actions, and activity logs over MCP.
Hosted markdown project wikis your team's AI assistants read, search, and update over MCP.
Human-in-the-loop for AI agents over MCP: durable approvals with a hosted review page & audit trail
Related MCP Servers
- AlicenseAqualityCmaintenanceAn MCP server that enables AI agents to compile, refine, and interlink knowledge into a persistent wiki, replacing RAG with structured, curated knowledge.1527 npm6MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to search, read, and contribute to a structured markdown knowledge base with citations, freshness tracking, and a safe write path, providing a shared, auditable company memory.2 npmMIT
- AlicenseBqualityAmaintenanceMCP governance server that lets AI agents build and maintain a persistent, versioned wiki of interlinked Markdown files through validated tools, enforcing invariants like linking, immutability, and one git commit per write.4567Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server that gives AI coding agents a git-backed markdown wiki to read and update, enabling search, read, write, verify, ingest, promote, and lint operations on versioned knowledge documents with schema validation, staleness tracking, and contradiction detection.4MIT