mcp-server-llm-wiki

A generic, agent-agnostic MCP (Model Context Protocol) server that turns a directory of Markdown wiki pages into a network-reachable knowledge base — queryable and updatable by any MCP-compatible client (Claude, Hermes, or otherwise), not just a Claude Code session with local filesystem access.

The server carries no embedded domain knowledge. It enforces a small universal contract (frontmatter requirements, an immutable raw/ folder, an append-only log, optimistic-concurrency writes) and leaves every domain-specific detail — category taxonomy, naming conventions, guidance — to a per-instance wiki.schema.yaml file that's bootstrapped once via the init_wiki tool. See PLAN.md for the full design rationale.

This server runs one process per wiki instance — one long-running deployment per wiki you maintain, each bound to its own root directory and its own bearer token. Any number of MCP clients can connect to a given instance concurrently, over HTTP.

Requirements

• Docker (recommended) or Node.js 18+, to run the server itself somewhere reachable over HTTP
• A directory on that host to serve as the wiki root (can be empty — init_wiki will bootstrap it)

Install

Docker Compose (recommended)

Both compose files pull the published image (itlostandfound/mcp-server-llm-wiki) from Docker Hub — no local build, no Node install required. You just need compose.yml (or compose.traefik.yml) and env.example.txt from this repo (cloning it is the easiest way to get them).

Copy env.example.txt to .env, set WIKI_HOST_ROOT (the host directory to serve), WIKI_MCP_TOKEN (generate one with openssl rand -hex 32), then:

docker compose up -d

This exposes the server on 3000:3000 directly. If you're putting it behind a domain with TLS via Traefik, use compose.traefik.yml instead (also set MCP_DOMAIN in .env, and pre-create the external network with docker network create traefik):

docker compose -f compose.traefik.yml up -d

Both files default to the :latest tag. To pin a specific released version instead, edit the image: line to e.g. itlostandfound/mcp-server-llm-wiki:0.1.0.

From source

git clone https://github.com/itlostandfound/mcp-server-llm-wiki.git
cd mcp-server-llm-wiki
npm install
npm run build
WIKI_ROOT=/path/to/a/wiki WIKI_MCP_TOKEN=$(openssl rand -hex 32) npm start

Configuration

Variable	Required	Description
WIKI_ROOT	Yes	Absolute path to this instance's wiki root directory. May be empty; init_wiki bootstraps it.
WIKI_MCP_TOKEN	Yes	Shared secret this instance checks every request against. One per deployment — generate with openssl rand -hex 32.
PORT	No	Port the HTTP server listens on. Defaults to 3000.

The server fails fast at startup with a clear message if WIKI_ROOT or WIKI_MCP_TOKEN is missing.

Every request to /mcp must carry Authorization: Bearer <WIKI_MCP_TOKEN>. A missing or wrong token is rejected with 401 before any tool runs. Unlike a server that proxies to a separate backend, this token is not forwarded anywhere — it's checked directly against this instance's own configured secret.

Using it with an MCP client

The server exposes a single endpoint, POST /mcp (Streamable HTTP, stateless — no server-side sessions), at whatever host/port you deployed it to.

Claude Code

claude mcp add --transport http my-wiki https://your-server-host:3000/mcp --header "Authorization: Bearer <WIKI_MCP_TOKEN>"

Other MCP clients

Any client that supports Streamable HTTP with custom headers works the same way: point it at https://your-server-host:3000/mcp and set Authorization: Bearer <WIKI_MCP_TOKEN>.

Bootstrapping a new wiki

A fresh WIKI_ROOT has no schema yet. Connect an agent and have a conversation about what the wiki should cover — category taxonomy, naming conventions, any domain guidance — then have the agent call init_wiki once with the finalized shape. From then on, get_schema tells any connecting agent (this one or a different vendor entirely) how the instance is structured.

Tools

Tool	Description
init_wiki	Bootstrap a wiki instance's name, description, category taxonomy, and guidance. Fails if already initialized.
get_schema	Read the current instance's schema — call this first in any new session.
get_recent_log	Read the most recent entries from the append-only operation log.
list_pages	List all pages, optionally filtered to one category.
read_page	Read a page's frontmatter, content, and version stamp.
write_page	Create or update a page. Updates require expectedVersion from a prior read_page; a stale value is rejected with a conflict.
append_log	Append an entry to the log after an ingest/query/lint/edit. Never modifies past entries.
add_raw_source	Add UTF-8 text content into raw/. Create-only — raw/ is immutable. Binary files stay out-of-band.
search	Full-text search across page titles, tags, and bodies.

Concurrency model

• Shared files (the log): serialized through an in-process, path-keyed mutex at millisecond scale — invisible to callers, since MCP tool calls are already synchronous request/response.
• Individual pages: optimistic concurrency. Every write to an existing page must include the version stamp from when it was last read; a write against a stale stamp is rejected with the page's current content so the caller can redo its edit and retry. No silent overwrites.

Error handling

• Missing/invalid Authorization header: rejected with 401 before any tool runs.
• Unknown category, bad filename pattern, missing frontmatter fields: rejected with a validation error naming the problem.
• Writing over an existing page without (or with a stale) expectedVersion: rejected with a conflict error, including the page's current content.
• Re-adding an existing raw source filename: rejected — raw/ never overwrites.
• Path traversal attempts (../, absolute paths escaping the wiki root): rejected before any filesystem access.

Development

WIKI_ROOT=./data WIKI_MCP_TOKEN=dev-token npm run dev   # run the HTTP server directly from source with tsx
npm run build         # compile to dist/
npm run typecheck     # type-check without emitting
npm test              # run the automated test suite (temp-dir fixtures, no real wiki content involved)

Tests run exclusively against synthetic example schemas invented for testing — never against any real wiki this project's author maintains, by design (see PLAN.md).

Releasing

Pushing a v* tag triggers .github/workflows/release.yml, which builds and pushes a Docker image to Docker Hub tagged latest, the version from the tag, and the commit SHA, then creates a GitHub Release with auto-generated notes. The workflow fails if the tag doesn't match package.json's version field, so the two can never silently drift apart.

Requires DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets configured on this repository (Settings → Secrets and variables → Actions) — they are not inherited from any other repo.

# 1. Bump the version and commit it
npm version 0.2.0 --no-git-tag-version
git add package.json package-lock.json
git commit -m "Bump version to 0.2.0"

# 2. Tag and push — this is what triggers the release
git tag v0.2.0
git push origin main v0.2.0

License

MIT — see LICENSE.