WikiMCP

<p align="center"> <img src="src/www/images/_raydeStar.png" alt="WikiMCP" width="120" /> </p>

<h1 align="center">WikiMCP</h1>

<p align="center"> MCP server for a Wiki.js project. Provides full-text search, page retrieval, and optional page creation via the Model Context Protocol. </p>

What this repo gives you

• A Wiki.js stack (Wiki.js + Postgres) you can run locally with Docker.
• An MCP server (Node/TypeScript) that exposes Wiki tools over stdio (spawned by a client like LM Studio / Cursor / Claude Desktop).
• Receipts-first tooling: wiki.quote returns exact line ranges so answers can cite sources.

---

Architecture in one picture

┌──────────────┐        ┌───────────────────────┐
│ MCP Client   │        │ Wiki.js (UI)          │
│ (LM Studio / │        │ + Postgres            │
│ Cursor / …)  │        └──────────┬────────────┘
└──────┬───────┘                   │
       │ spawns (stdio)            │
       ▼                           │ reads/imports
┌───────────────────────┐          │ markdown
│ WikiMCP (this repo)   │◄─────────┘
│ - tools: search/get/  │
│   quote/list/(create) │
└───────────────────────┘

Important: Docker is for Wiki.js + Postgres. The MCP server is typically spawned directly by your MCP client (no Docker required for the MCP server unless you want it).

---

Quick Start (sample data)

git clone https://github.com/raydeStar/WikiMCP WikiMCP
cd WikiMCP
.\bootstrap-local.ps1 -OpenUi

• Wiki.js opens at: http://localhost:3030
• The stack includes sample content in ./wiki-content

---

Setup paths (choose your adventure)

1) Local with sample data (default)

.\bootstrap-local.ps1 -OpenUi

Uses ./wiki-content (characters, locations, chapters, etc.).

2) Local with empty wiki

.\bootstrap-local.ps1 -ContentMode Empty -OpenUi

Creates ./wiki-content-empty with just the en/ locale folder (sample data stays untouched).

3) Local with custom content path

.\bootstrap-local.ps1 -ContentMode Path -ContentPath "D:\my-wiki" -OpenUi

Points to any folder on your machine.

4) Reset everything (wipe DB, keep content)

.\bootstrap-local.ps1 -Reset -OpenUi

Removes Docker volumes and rebuilds from scratch. Your content folder survives.

---

Wiki.js first-run setup

After containers start:

1. Open http://localhost:3030
2. Complete the Wiki.js setup wizard (create admin account)
3. Go to Administration → Storage → Local File System (or Git)
4. Set the path to: file:///wiki-storage
5. Click Apply and Import Everything

Your markdown files will appear in the wiki.

---

Connect an LLM / MCP client (the fun part)

WikiMCP communicates via stdio (stdin/stdout). Your MCP client spawns the server directly.

1) Build the MCP server

npm install
npm run build

This produces dist/index.js.

2) Configure your MCP client

Cursor / Claude Desktop (example)

Add to your MCP config (example file: mcp-config.example.json):

{
  "mcpServers": {
    "novel-wiki": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "C:/Users/YourName/WikiMCP",
      "env": {
        "WIKI_REPO_PATH": "C:/Users/YourName/WikiMCP/wiki-content",
        "WIKI_WRITE_ENABLED": "false",
        "MCP_AUTH_USERNAME": "",
        "MCP_AUTH_PASSWORD": ""
      }
    }
  }
}

Adjust paths for your system.

LM Studio (concept)

LM Studio can act as an MCP host as well. Add a server entry that spawns:

• node dist/index.js …and pass WIKI_REPO_PATH to point at your content directory.

---

MCP vs REST/Swagger (1-minute version)

If you’re used to normal APIs, MCP can feel weird at first. Here’s the simple mapping:

• REST/Swagger: You design lots of URLs like GET /pages/{id} and document them in OpenAPI.
• MCP: You expose a tool list (functions) like wiki.search, wiki.get_page, wiki.quote with JSON schemas.

In other words:

• REST is resource-oriented (endpoints)
• MCP is capability-oriented (tools)

A typical REST call:

• GET /api/wiki/pages/Tim

A typical MCP call (conceptually):

• call tool wiki.get_page({ path: "/characters/white-bunny" })

The MCP client/host (LM Studio, Cursor, etc.) is the thing that:

1. discovers the tool list
2. decides when to call a tool
3. feeds tool results back into the model

---

MCP Authentication (optional) (optional)

If MCP_AUTH_USERNAME and MCP_AUTH_PASSWORD are both set, every tool call must include:

{
  "auth": {
    "username": "your-user",
    "password": "your-pass"
  },
  "query": "The Knights who say Ni"
}

Bootstrap helpers:

.\bootstrap-local.ps1 -AuthFromDb

or:

.\bootstrap-local.ps1 -McpAuthUsername "admin" -McpAuthPassword "secret"

---

Write operations

wiki.create_page is disabled by default.

Enable it by either:

1. .env:

• set WIKI_WRITE_ENABLED=true
• ensure your wiki content mount is not read-only

or

2. bootstrap flag:

.\bootstrap-local.ps1 -WriteEnabled

---

Available MCP tools

Tool	Description
wiki.search	Full-text search with optional filters (type, tags, path prefix)
wiki.get_page	Retrieve full page content by path
wiki.quote	Extract specific lines from a page (citations/receipts)
wiki.list	List pages, optionally filtered by type or tag
wiki.reindex	Rebuild the search index
wiki.get_context_bundle	Get everything about a topic: main page, related pages, summaries, citations
wiki.create_page	Create a new page (requires WIKI_WRITE_ENABLED=true)

wiki.get_context_bundle (the power tool)

This is the bridge between librarian and editor. Instead of orchestrating multiple calls, ask:

{ "topic": "Kazalt", "maxPages": 5 }

Returns:

• mainPage: Full content of the best-match page
• relatedPages: Summaries of linked and related pages
• citations: Version info for every page (receipts)
• totalPagesFound: How many matches exist

The model can now say "give me everything about X" and get a ready-to-use context bundle.

---

Environment variables

Variable	Description	Default
WIKI_DB_NAME	Postgres database name	wikijs
WIKI_DB_USER	Postgres username	wikijs
WIKI_DB_PASSWORD	Postgres password	(required)
WIKI_CONTENT_DIR	Content folder path (Docker/Wiki.js)	./wiki-content
WIKI_WRITE_ENABLED	Enable wiki.create_page	false
MCP_AUTH_USERNAME	MCP auth username	(empty)
MCP_AUTH_PASSWORD	MCP auth password	(empty)
WIKI_REPO_PATH	Content path used by MCP server	/wiki
DB_PATH	SQLite index path	/app/data/wiki-index.db

---

Project structure

WikiMCP/
├── src/
│   ├── index.ts        # MCP server entry point
│   ├── indexer.ts      # SQLite FTS indexer
│   └── config.ts       # Environment config
├── wiki-content/       # Sample markdown content
├── docker-compose.yml  # Local dev stack (Wiki.js + Postgres)
├── docker-compose.prod.yml  # Production overrides
├── bootstrap-local.ps1 # PowerShell setup script
├── Dockerfile          # Optional container for MCP server
└── .env.example        # Environment template

---

Troubleshooting

“password authentication failed”

Old Postgres volume credentials. Reset:

.\bootstrap-local.ps1 -Reset

“detected dubious ownership in repository”

Git safety check. The compose file configures safe.directory. Restart:

docker compose restart wiki-js

MCP server not connecting

• Ensure npm run build succeeded
• Ensure absolute paths in the MCP client config
• Ensure WIKI_REPO_PATH points to real content

---

How this differs from a normal REST API (quick intuition)

WikiMCP is not a traditional HTTP API meant for humans or frontends.

• A REST API exposes endpoints (URLs) and HTTP verbs.
• An MCP server exposes tools (named capabilities with JSON schemas).

In practice:

• Your MCP client (LM Studio, Cursor, Claude Desktop) spawns this server.
• The server advertises its tools (e.g. wiki.search, wiki.quote).
• The LLM decides which tool to call and with what arguments.
• WikiMCP enforces validation, permissions, and returns structured results.

Think of it as "controllers for an AI client" rather than endpoints for a web app.

If you understand that one sentence, you understand MCP well enough to build useful things.

---

When not to use WikiMCP

WikiMCP is intentionally simple. You probably should not use it if:

• You only want a normal REST API over your wiki
• You don’t need citations or exact quotes
• You don’t plan to use an LLM with tool-calling

WikiMCP shines when:

• You want an LLM to prove where it got information
• You’re experimenting with agents, RAG, or MCP
• You want a clean learning project that scales into something real

---

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

WikiMCP intentionally mirrors the license of Wiki.js, which is also AGPL-3.0. This ensures:

• Clear legal alignment with the upstream project
• Transparency for anyone running modified versions as a service
• A shared expectation that improvements remain open

If you are unfamiliar with AGPL, the practical takeaway is simple:

If you modify this project and make it available to users over a network, you must provide the source code of your modified version.

For personal use, learning, tinkering, and local deployments, AGPL imposes no additional burden.

See the LICENSE file for full terms.

---