Wiki MCP Server
A persistent documentation context server ("Librarian") for Claude Code and LLM Agents. It loads local Markdown documentation, indexes it using Hybrid Search (Keyword + Vector), and provides fast, cost-efficient answers to documentation queries.
> Status: Phase 1 In Progress - Core Infrastructure. See STATUS.md for details.
Key Benefit: Reduces token costs by 90-97% for repeated documentation queries by offloading context to an indexed database.
Features
| Tool | Description | Phase | Status |
|---|---|---|---|
query_docs |
Search documentation with hybrid/exact/concept search modes | 1 (Core) | Planned |
add_context |
Add new documentation to the wiki | 1 (Core) | Planned |
sync_docs |
Manually trigger documentation synchronization | 1 (Core) | Planned |
organize_inbox |
Classify and move files from 00_Inbox using LLM | 2 (Organization) | Planned |
Core Capabilities
- Hybrid Search: Combines SQLite FTS5 (Keywords) and SentenceTransformers (Vector Semantic Search) for high precision
- Context-Aware Chunking: Splits Markdown by headers to preserve hierarchy and context
- Context Garden: Automatically organizes documentation into a structured taxonomy
- Auto-Ingestion: Watches for file changes in real-time and updates the index immediately
- Incremental Sync: Monitors file changes and only re-indexes modified files
- Scoped Search: Filter searches by specific folders (e.g., just "API" or "Specs")
- Per-Project Isolation: Designed to run locally within a project, keeping indexes separate
- Type-Safe: Fully typed Python codebase (Strict
mypy/ruffcompliance)
Architecture
See docs/TDD.md for the full architectural breakdown.```
Wiki-MCP Server (The "Librarian")
+------------------------------------------------------------------+
| Server Layer <---- Search Engine ----> LLM Synthesizer |
| (MCP Protocol) (Logic Layer) (Haiku - Optional) |
+------------------------------------------------------------------+
|
+-------------+-------------+
v v
+--------------+ +--------------+
| SQLite DB | | Vector Store |
| (FTS5 BM25) | | (Semantic) |
+--------------+ +--------------+
^ ^
+-------------+-------------+
|
Ingestion Pipeline
(Sync Manager + Watcher)
^
|
+---------------+
| Context Garden|
| (docs/*.md) |
+---------------+
## Directory Structure: The Context Garden
Wiki-MCP uses a "Garden" structure to keep knowledge organized. By default, it looks for a `docs/` directory.```
docs/
├── 00_Inbox/ # Drop new, unclassified notes here
├── 10_Project_Specs/ # Requirements, PRDs, User Stories
├── 20_Architecture/ # System design, diagrams, schemas
├── 30_Patterns/ # Coding standards, snippets, idioms
├── 40_Reference/ # API docs, library notes
└── 90_Archive/ # Deprecated content
Auto-Organization
Drop raw notes into docs/00_Inbox and run the organize_inbox tool. The server will use an LLM to analyze the content and move it to the correct folder with appropriate metadata.
Installation
Prerequisites
- Python 3.10+
pipvenv(Recommended)
Local Development Setup
-
Clone the repository:
bash git clone https://github.com/your-repo/wiki-mcp-server.git cd wiki-mcp-server -
Create a virtual environment:
bash python3 -m venv venv source venv/bin/activate -
Install dependencies:
bash pip install -r requirements.txt -
Run Tests:
bash PYTHONPATH=. pytest -v tests/
Usage
Configure Claude Code (or MCP Client)
Add the server to your MCP configuration (e.g., claude_desktop_config.json or settings.json):```json
{
"mcpServers": {
"wiki": {
"command": "python3",
"args": ["/absolute/path/to/wiki-mcp-server/server.py"],
"cwd": "${workspaceFolder}",
"env": {
"ANTHROPIC_API_KEY": "sk-...",
"DOCS_DIR": "docs"
}
}
}
}
- `cwd`: Ensures the server looks for `wiki.db` and `docs/` inside your current project
- `DOCS_DIR`: Override where the server looks for markdown files (default: `docs`)
### Server CLI Tools
You can interact with the server components directly for debugging:```bash
# Sync documentation manually
python3 -c "from src.db import Database; from src.sync import SyncManager; from src.vector import VectorStore; db=Database(); v=VectorStore(); s=SyncManager(db, v); s.sync_all()"
# Run the server (Stdio mode)
python3 server.py
MCP Tools
| Tool | Description |
|---|---|
| query_docs | Search documentation with hybrid/exact/concept search modes |
| add_context | Add new documentation to the wiki |
| organize_inbox | Classify and move files from 00_Inbox using LLM |
| sync_docs | Manually trigger documentation synchronization |
query_docs
Search documentation with various modes.
Parameters:
- query (required): The search question
- intent: exact, concept, or hybrid (default)
- scope: Optional list of folders to filter by (e.g., ["10_Project_Specs"])
- mode: standard or code_only
Returns: LLM-synthesized answer with sources
add_context
Create a new documentation file.
Parameters:
- topic: Topic/title for the document
- content: Markdown content
- category: Target folder (defaults to "00_Inbox")
organize_inbox
Sort files from Inbox into the taxonomy using LLM classification.
sync_docs
Force a manual re-sync of all files.
Environment Variables
| Variable | Default | Description |
|---|---|---|
ANTHROPIC_API_KEY |
(required) | API key for LLM synthesis |
DOCS_DIR |
docs |
Directory to watch for markdown files |
WIKI_DB_PATH |
wiki.db |
Path to SQLite database |
RELEVANCE_THRESHOLD |
0.3 |
Minimum score for search results |
Configuration
Create a config.json in your project root:```json
{
"model": "claude-3-5-haiku-20241022",
"max_tokens": 2000,
"relevance_threshold": 0.3,
"docs_dir": "MyDocs"
}
## Documentation
| Document | Purpose |
|----------|---------|
| STATUS.md | Current progress and roadmap |
| docs/PRD.md | Product requirements and success metrics |
| docs/TDD.md | Technical design and architecture |
| docs/IMPLEMENTATION.md | Implementation phases and roadmap |
## Development
### Running Tests```bash
# All tests
PYTHONPATH=. pytest -v tests/
# Unit tests
PYTHONPATH=. pytest -v tests/unit/
# Integration tests
PYTHONPATH=. pytest -v tests/integration/
# Specific test
PYTHONPATH=. pytest -v tests/unit/test_processor.py::test_name
Code Quality```bash
Type checking
mypy src/ --strict
Linting and formatting
ruff check src/ tests/
ruff format src/ tests/
```
License
GPL-3.0 - See LICENSE for details.
