# 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`](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](https://docs.docker.com/get-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:

```bash
docker compose up -d
```

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

```bash
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

```bash
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`. |
| `MCP_DOMAIN` | No | Public hostname this server is reachable at (bare hostname, no scheme), e.g. `mcp-llm-wiki.example.com`. Required for any public/reverse-proxied deployment — without it the server only accepts requests with `Host: localhost`/`127.0.0.1`/`::1` and rejects everything else with `403`. Also drives the Traefik router rule in `compose.traefik.yml`. |

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

```bash
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.

## Control Mechanism

A local LLM Wiki (one accessed via direct filesystem reads on the agent's own machine, like the
[TMSH LLM Wiki](https://github.com/itlostandfound/BIG-IP-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`:

```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:

```markdown
## 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

```bash
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

```bash
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.

```bash
# 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](LICENSE).