<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
```text
┌──────────────┐ ┌───────────────────────┐
│ 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)
```powershell
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)
```powershell
.\bootstrap-local.ps1 -OpenUi
```
Uses `./wiki-content` (characters, locations, chapters, etc.).
### 2) Local with empty wiki
```powershell
.\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
```powershell
.\bootstrap-local.ps1 -ContentMode Path -ContentPath "D:\my-wiki" -OpenUi
```
Points to any folder on your machine.
### 4) Reset everything (wipe DB, keep content)
```powershell
.\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
```powershell
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`):
```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:
```json
{
"auth": {
"username": "your-user",
"password": "your-pass"
},
"query": "The Knights who say Ni"
}
```
Bootstrap helpers:
```powershell
.\bootstrap-local.ps1 -AuthFromDb
```
or:
```powershell
.\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:
```powershell
.\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:
```json
{ "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
```text
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:
```powershell
.\bootstrap-local.ps1 -Reset
```
### “detected dubious ownership in repository”
Git safety check. The compose file configures `safe.directory`. Restart:
```powershell
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.
---
