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)

Related MCP server: md-graph

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

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

The URL your MCP client actually connects to is https://<MCP_DOMAIN>/mcp — the /mcp path is required. MCP_DOMAIN itself must stay a bare hostname (no scheme, no path): it's used both to build the Traefik router rule and, verbatim, as the value checked against the request's Host header.

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

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.

Control Mechanism

A local LLM Wiki (one accessed via direct filesystem reads on the agent's own machine, like the TMSH LLM Wiki) embeds its operating instructions in a project-level file — typically CLAUDE.md — that sits alongside the wiki content in the repository root. When Claude Code opens a session in that directory, it reads the file automatically and follows its rules. The instructions travel with the content: same folder, same access, same lifecycle. But this means the instructions only activate when the agent is in that specific project directory — ask a question from anywhere else and the wiki is invisible.

This generic MCP server is different. It has no local filesystem and no project directory. It doesn't — and shouldn't — carry domain-specific instructions inside its codebase. Instead, the operating rules that tell an agent how to use a given wiki instance properly must be delivered through the agent platform's own configuration system:

• Hermes Agent — instructions go into a Skill (a SKILL.md file under ~/.hermes/skills/), loaded by name in the profile's skill list or on demand via skill_view. Skills are global to the profile — they're available in every session, not tied to a project directory. The skill file contains the domain rules, session protocol, page conventions, routing logic, and hard prohibitions that would otherwise live in a CLAUDE.md.

• Claude Code (project-scoped) — instructions go into a .claude/CLAUDE.md at the project root. When Claude opens that directory, it reads the instructions automatically. This is the same pattern as a local filesystem wiki — instructions travel with the project.

• Claude Code (global) — instructions go into ~/.claude/CLAUDE.md, which Claude reads in every session regardless of directory. This is the direct equivalent of a Hermes Skill: always available, routing triggers activate the wiki when the topic matches. This is the preferred pattern for domain wikis you want available everywhere, not just in one project folder.

In both cases, the guidance field stored inside the wiki's own wiki.schema.yaml (set during init_wiki) provides a compact summary of the domain rules that the server itself knows — but this is a summary, not the full operating manual. The full manual (what pages to read at session start, how to route between sibling wikis, what never to do, de-identification rules, etc.) belongs in the Skill or CLAUDE.md, where the agent actually consumes it. The schema guidance and the external skill reinforce each other: the schema tells any connecting agent the domain vocabulary, and the skill tells the configured agent the operational playbook.

Worked Example: Creating the F5 BIG-IP Administrator Skill

The BIG-IP Administrator LLM Wiki was the first real deployment of this server. Here is the exact process used to create the control mechanism for agents connecting to it.

1. Define the wiki instance

Deploy the server with a dedicated WIKI_ROOT, bearer token, and domain name. In this case:

• Endpoint: https://mcp-bigipadmin.work.itlostandfound.xyz/mcp

• WIKI_ROOT: a directory on the host containing the BIG-IP Administrator wiki content

• Bearer token: generated with openssl rand -hex 32

Configure the MCP server in the agent platform so the wiki tools appear with a recognizable prefix. In Hermes, this means adding the server to the profile's config.yaml:

mcp_servers:
  bigipadmin:
    url: "https://mcp-bigipadmin.work.itlostandfound.xyz/mcp"
    headers:
      Authorization: "Bearer <TOKEN>"

This makes the wiki's 9 tools available as mcp_bigipadmin_init_wiki, mcp_bigipadmin_get_schema, mcp_bigipadmin_read_page, etc.

2. Bootstrap the wiki schema

Connect an agent and call init_wiki with the domain taxonomy, naming patterns, and guidance text. The guidance field in the schema is a compact version of the operating rules — enough for an unconfigured agent to avoid the worst mistakes, but not a substitute for the full skill.

3. Write the Skill (or CLAUDE.md)

The skill contains everything the agent needs to operate correctly: identity, routing rules, page conventions, hard prohibitions, session start protocol, and the MCP tool reference with pitfalls. This is where the CLAUDE.md content goes when there is no project directory.

Hermes Agent Section

For Hermes, the control mechanism is a Skill — a SKILL.md file in the skill directory, loaded by the agent when the topic matches. The F5 BIG-IP Administrator Wiki skill (f5-bigip-wiki) was created with the following approach:

1. Identify what the CLAUDE.md did — read the existing TMSH CLAUDE.md and extract every operational rule: identity, repository layout, routing, page conventions, domain rules, logging format, session start protocol, and prohibitions.

2. Adapt for MCP access — replace filesystem references (read_file, search_files) with MCP tool calls (mcp_bigipadmin_get_schema, mcp_bigipadmin_list_pages, mcp_bigipadmin_search, mcp_bigipadmin_read_page). The agent never touches files directly — everything goes through the server's tools.

3. Add the tool reference and pitfalls — document all 9 MCP tools with their constraints (e.g., write_page requires expectedVersion, init_wiki is one-shot, append_log replaces manual log editing).

4. Add routing and de-identification rules — this wiki cross-links to the TMSH wiki and must never reference the QKView wiki. Client-identifying data (hostnames, IPs, case IDs) must be de-identified on ingest.

The resulting skill is loaded with skill_view(name='f5-bigip-wiki') and contains the full operating manual for any Hermes agent connecting to this wiki instance.

Example prompt to Hermes Agent that activates the skill:

Load the f5-bigip-wiki skill, then connect to the BIG-IP Administrator wiki.
Run the session start protocol: call get_schema, list_pages, and get_recent_log.
Report current page count, date of last update, and one-line status.

When this prompt arrives, Hermes:

1. Loads the f5-bigip-wiki skill (which contains identity, routing rules, tool reference, pitfalls, and the full operating manual).

2. Calls mcp_bigipadmin_get_schema to learn the wiki's structure and categories.

3. Calls mcp_bigipadmin_list_pages to see what pages exist.

4. Calls mcp_bigipadmin_get_recent_log to see recent activity.

5. Reports back with the wiki status — and from that point on, every query, ingest, or edit follows the skill's rules for routing, page conventions, de-identification, and logging.

Claude Code Section

Claude Code has two levels where instructions can live, and they serve different purposes:

• Global ~/.claude/CLAUDE.md — read by Claude in every session, regardless of which directory you're in. This is the direct equivalent of a Hermes Skill: always available, always loaded. This is where wiki routing triggers and domain-awareness rules belong.

• Project .claude/CLAUDE.md (or CLAUDE.md in the repo root) — read only when Claude opens a session in that specific directory. This is the local-filesystem pattern the TMSH wiki uses.

For an MCP-served wiki, the project-scoped approach requires you to cd into a specific directory every time you want wiki access. That works, but it limits the wiki to sessions that happen to start in that folder. The more powerful pattern is global scope — putting the routing logic in ~/.claude/CLAUDE.md so that Claude knows the wiki exists no matter what project you're working in.

Building the Skill: Global Routing + Full Operating Rules

The process mirrors the Hermes skill creation, but the output goes into Claude's global instruction file instead of a Hermes skill directory:

1. Identify what the CLAUDE.md did — same as the Hermes process: extract every operational rule from the TMSH CLAUDE.md (identity, routing, page conventions, domain rules, logging format, session start protocol, prohibitions).

2. Adapt for MCP access — same as the Hermes process: replace filesystem references with MCP tool calls. Claude Code uses the same MCP tools with the same names; the only difference is the prefix (which depends on how you named the server in claude mcp add).

3. Add the tool reference and pitfalls — same content, same constraints (write_page requires expectedVersion, init_wiki is one-shot, append_log replaces manual log editing).

4. Add routing and de-identification rules — same as Hermes: this wiki cross-links to the TMSH wiki and must never reference the QKView wiki. Client-identifying data must be de-identified.

5. Add routing triggers at the global level — this is the step unique to Claude Code. In ~/.claude/CLAUDE.md, add a directive that tells Claude when to activate this knowledge:

## Wiki Routing

When the user asks about F5 BIG-IP administration, LTM, GTM/DNS, APM, ASM/AWAF, AFM,
or BIG-IP troubleshooting, connect to the BIG-IP Administrator wiki (MCP server: bigipadmin).
Run the session start protocol: get_schema, list_pages, get_recent_log. Then follow the
BIG-IP Administrator Wiki operating rules below for all subsequent queries and edits.

When the user asks about TMSH syntax or shell commands, connect to the TMSH wiki
(MCP server: tmsh). Follow the TMSH Wiki operating rules for syntax queries only —
never copy TMSH syntax into Administrator wiki pages.

This global routing trigger means Claude doesn't need to be told "use the wiki" — it recognizes the domain from the question and activates the right wiki automatically, exactly like a Hermes Skill that's loaded on topic match.

Configuring the MCP server in Claude Code

claude mcp add --transport http bigipadmin https://mcp-bigipadmin.work.itlostandfound.xyz/mcp \
  --header "Authorization: Bearer ***"

This makes the wiki's 9 tools available as get_schema, list_pages, read_page, etc. (Claude Code strips the server prefix from tool names, unlike Hermes which keeps it.)

Two scoping strategies compared

Project-scoped — .claude/CLAUDE.md in the project root

• Scope: That project only

• When it loads: When Claude opens that directory

• Best for: Wikis tied to a specific codebase or project

Global — ~/.claude/CLAUDE.md

• Scope: All sessions

• When it loads: Every session, always

• Best for: Domain wikis you want available everywhere

For a knowledge base like BIG-IP Administrator, global scoping is almost always the right choice. You want Claude to know the wiki exists whether you're in /projects/networking/, /tmp/, or your home directory. The routing trigger ensures it only activates when the topic is relevant — it doesn't pollute unrelated conversations.

Example prompt to Claude Code with global routing (no project scoping needed):

What's the difference between an LTM virtual server's source-address-translation
and SNAT pool?

Claude sees the domain trigger in its global CLAUDE.md, recognizes this as a BIG-IP question, and:

1. Connects to the bigipadmin MCP server (already configured).

2. Calls get_schema, list_pages, and get_recent_log as the session start protocol.

3. Searches for and reads relevant pages about virtual servers and SNAT.

4. Answers with citations from the wiki, following the operating rules for routing, page conventions, de-identification, and logging.

No explicit "use the wiki" instruction needed — the global routing trigger handles it.

Example prompt to Claude Code with project scoping (explicit activation):

If you prefer project scoping instead, the prompt would need to be explicit:

I need you to work with the BIG-IP Administrator wiki. Read the CLAUDE.md in this
project directory, then run the session start protocol: call get_schema, list_pages,
and get_recent_log. Report current page count, date of last update, and one-line status.

This works, but requires starting in the right directory and telling Claude to use the wiki. The global approach is simpler for domain wikis you want available on demand.

Summary: Where the Instructions Live

Local filesystem wiki — CLAUDE.md in the project repo root

• Scope: That project only

• Delivery: Read automatically by Claude Code at session start

Hermes Agent (remote MCP) — SKILL.md at ~/.hermes/skills/<category>/<name>/SKILL.md

• Scope: Global — all sessions for that profile

• Delivery: Loaded by name via the skill system, on demand or in profile config

Claude Code (remote MCP, project-scoped) — .claude/CLAUDE.md in the project directory root

• Scope: That project only

• Delivery: Read automatically at session start

Claude Code (remote MCP, global) — ~/.claude/CLAUDE.md

• Scope: All sessions, always

• Delivery: Read automatically in every session; routing triggers activate the wiki on topic match

The generic MCP server provides the transport and enforcement (tools, auth, optimistic concurrency, structural validation). The Skill or CLAUDE.md provides the domain operating rules (what to write, how to route, what never to do). The guidance field in wiki.schema.yaml provides a compact summary that any connecting agent can read — but it is not a replacement for the full control mechanism. Together, these three layers ensure that every agent connecting to a wiki instance operates correctly, regardless of which agent platform it runs on.

The key insight: both Hermes and Claude Code need essentially the same content — domain identity, routing rules, page conventions, prohibitions, session protocol, tool reference, and pitfalls. The delivery mechanism differs (Skill vs. CLAUDE.md, on-demand loading vs. global routing trigger), but the knowledge is portable. A Hermes skill can be translated to a Claude CLAUDE.md section and vice versa with minimal adaptation (mainly MCP tool name prefixes and the routing trigger format).

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

Project Status

Current version: 0.1.2 — released, Docker image published to Docker Hub.

The server is production-ready for single-instance deployments (one process per wiki, bearer token auth, optimistic concurrency for page writes, serialized log/index access). It has been deployed behind Traefik with TLS termination and is in active daily use serving the BIG-IP Administrator LLM Wiki instance.

What's working: init_wiki, get_schema, list_pages, read_page, write_page (with optimistic concurrency), append_log, add_raw_source, search, get_recent_log, bearer token auth, path traversal protection, structural validation, Docker Compose deployment, Traefik reverse proxy integration, GitHub Actions release pipeline.

What's not yet implemented: binary file upload (explicitly out of scope per PLAN.md), wiki deletion, page archival, batch operations, rate limiting.

Deployed instances: One — the BIG-IP Administrator wiki at mcp-bigipadmin.work.itlostandfound.xyz, accessed by both Hermes and Claude Code agents.

License

MIT — see LICENSE.