leo-claude-mktplace/mcp-servers/wikijs/README.md

Wiki.js MCP Server

Model Context Protocol (MCP) server for Wiki.js integration with Claude Code.

Overview

The Wiki.js MCP Server provides Claude Code with direct access to Wiki.js for documentation management, lessons learned capture, and knowledge base operations. It supports both single-project (project mode) and company-wide (PMO mode) operations.

Status: ✅ Phase 1.1b Complete - Fully functional and tested

Features

Core Functionality

• Page Management: CRUD operations for Wiki.js pages with markdown content
• Lessons Learned: Systematic capture and searchable repository of sprint insights
• Mode Detection: Automatic project vs company-wide mode detection
• Hybrid Configuration: System-level credentials + project-level paths
• PMO Support: Company-wide documentation and cross-project lesson search

Tools Provided

Tool	Description	Mode
search_pages	Search pages by keywords and tags	Both
get_page	Get specific page content	Both
create_page	Create new page with markdown content	Both
update_page	Update existing page	Both
list_pages	List pages under a path	Both
create_lesson	Create lessons learned entry	Both
search_lessons	Search lessons from previous sprints	Both
tag_lesson	Add/update tags on lessons	Both

Architecture

Directory Structure

mcp-servers/wikijs/
├── .venv/                      # Python virtual environment
├── requirements.txt            # Python dependencies
├── mcp_server/
│   ├── __init__.py
│   ├── server.py              # MCP server entry point
│   ├── config.py              # Configuration loader
│   ├── wikijs_client.py       # Wiki.js GraphQL client
│   └── tools/
│       ├── __init__.py
│       ├── pages.py           # Page management tools
│       └── lessons_learned.py # Lessons learned tools
├── tests/
│   ├── __init__.py
│   ├── test_config.py
│   └── test_wikijs_client.py
├── README.md                   # This file
└── TESTING.md                  # Testing instructions

Mode Detection

The server operates in two modes based on environment variables:

Project Mode (Single Project):

• When WIKIJS_PROJECT is set
• Operates on single project path
• Used by projman plugin
• Pages scoped to /base_path/project/

Company Mode (Multi-Project / PMO):

• When WIKIJS_PROJECT is NOT set
• Operates on all projects in organization
• Used by projman-pmo plugin
• Pages scoped to /base_path/

GraphQL Integration

The server uses Wiki.js GraphQL API for all operations:

• Pages API: Create, read, update, list, search pages
• Tags: Categorize and filter content
• Search: Full-text search with tag filtering
• Lessons Learned: Specialized workflow for sprint insights

Installation

Prerequisites

• Python 3.10 or higher
• Access to Wiki.js instance with API token
• GraphQL API enabled on Wiki.js

Step 1: Install Dependencies

cd mcp-servers/wikijs
python3 -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or .venv\Scripts\activate  # Windows

pip install -r requirements.txt

Step 2: System Configuration

Create system-level configuration with credentials:

mkdir -p ~/.config/claude

cat > ~/.config/claude/wikijs.env << 'EOF'
# Wiki.js API Configuration
WIKIJS_API_URL=http://wikijs.hotport/graphql
WIKIJS_API_TOKEN=your_api_token_here
WIKIJS_BASE_PATH=/hyper-hive-labs
EOF

chmod 600 ~/.config/claude/wikijs.env

Obtaining Wiki.js API Token:

1. Log in to Wiki.js as administrator
2. Navigate to Administration → API Access
3. Click "New API Key"
4. Set permissions: Pages (read/write), Search (read)
5. Copy the generated JWT token

Step 3: Project Configuration (Optional)

For project-scoped operations, create .env in project root:

# In your project directory
cat > .env << 'EOF'
# Wiki.js project path
WIKIJS_PROJECT=projects/your-project-name
EOF

# Add to .gitignore
echo ".env" >> .gitignore

Note: Omit .env for company-wide (PMO) mode.

Usage

Running the MCP Server

cd mcp-servers/wikijs
source .venv/bin/activate
python -m mcp_server.server

The server runs as a stdio-based MCP server and communicates via JSON-RPC 2.0.

Integration with Claude Code

The MCP server is referenced in plugin .mcp.json:

{
  "mcpServers": {
    "wikijs": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs",
      "env": {}
    }
  }
}

Example Tool Calls

Search Pages:

{
  "name": "search_pages",
  "arguments": {
    "query": "API documentation",
    "tags": "backend,api",
    "limit": 10
  }
}

Create Lesson Learned:

{
  "name": "create_lesson",
  "arguments": {
    "title": "Sprint 16 - Prevent Claude Code Infinite Loops",
    "content": "## Problem\\n\\nClaude Code entered infinite loop...\\n\\n## Solution\\n\\n...",
    "tags": "claude-code,testing,validation",
    "category": "sprints"
  }
}

Search Lessons:

{
  "name": "search_lessons",
  "arguments": {
    "query": "validation",
    "tags": "testing,claude-code",
    "limit": 20
  }
}

Configuration Reference

Required Variables

Variable	Description	Example
WIKIJS_API_URL	Wiki.js GraphQL endpoint	http://wiki.example.com/graphql
WIKIJS_API_TOKEN	API authentication token (JWT)	eyJhbGciOiJSUzI1...
WIKIJS_BASE_PATH	Base path in Wiki.js	/hyper-hive-labs

Optional Variables

Variable	Description	Mode
WIKIJS_PROJECT	Project-specific path	Project mode only

Configuration Priority

1. Project-level .env (overrides system)
2. System-level ~/.config/claude/wikijs.env

Wiki.js Structure

Recommended Organization

/hyper-hive-labs/                  # Base path
├── projects/                      # Project-specific
│   ├── your-project/
│   │   ├── lessons-learned/
│   │   │   ├── sprints/
│   │   │   ├── patterns/
│   │   │   └── INDEX.md
│   │   └── documentation/
│   ├── another-project/
│   └── shared-library/
├── company/                       # Company-wide
│   ├── processes/
│   ├── standards/
│   └── tools/
└── shared/                        # Cross-project
    ├── architecture-patterns/
    ├── best-practices/
    └── tech-stack/

Lessons Learned Categories

• sprints/: Sprint-specific lessons and retrospectives
• patterns/: Recurring patterns and solutions
• architecture/: Architectural decisions and outcomes
• tools/: Tool-specific tips and gotchas

Testing

See TESTING.md for comprehensive testing instructions.

Quick Test:

source .venv/bin/activate
pytest -v

Test Coverage:

• 18 tests covering all major functionality
• Mock-based unit tests (fast)
• Integration tests with real Wiki.js instance
• Configuration validation
• Mode detection
• Error handling

Lessons Learned System

Why This Matters

After 15 sprints without systematic lesson capture, repeated mistakes occurred:

• Claude Code infinite loops on similar issues: 2-3 times
• Same architectural mistakes: Multiple occurrences
• Forgotten optimizations: Re-discovered each time

Solution: Mandatory lessons learned capture at sprint close, searchable at sprint start.

Workflow

Sprint Close (Orchestrator):

1. Capture what went wrong
2. Document what went right
3. Note preventable repetitions
4. Tag for discoverability

Sprint Start (Planner):

1. Search relevant lessons by tags/keywords
2. Review applicable patterns
3. Apply preventive measures
4. Avoid known pitfalls

Lesson Structure

# Sprint X - [Lesson Title]

## Context
[What were you trying to do?]

## Problem
[What went wrong or what insight emerged?]

## Solution
[How did you solve it?]

## Prevention
[How can this be avoided or optimized in the future?]

## Tags
[Comma-separated tags for search]

Troubleshooting

Connection Errors

Error: Failed to connect to Wiki.js GraphQL endpoint

Solutions:

• Verify WIKIJS_API_URL is correct and includes /graphql
• Check Wiki.js is running and accessible
• Ensure GraphQL API is enabled in Wiki.js admin settings

Authentication Errors

Error: Unauthorized or Invalid token

Solutions:

• Verify API token is correct and not expired
• Check token has required permissions (Pages: read/write, Search: read)
• Regenerate token in Wiki.js admin if needed

Permission Errors

Error: Page creation failed: Permission denied

Solutions:

• Verify API key has write permissions
• Check user/group permissions in Wiki.js
• Ensure base path exists and is accessible

Mode Detection Issues

Error: Operating in wrong mode

Solutions:

• Check WIKIJS_PROJECT environment variable
• Clear project .env for company mode
• Verify configuration loading order (project overrides system)

Security Considerations

1. Never commit tokens: Keep ~/.config/claude/wikijs.env and .env out of git
2. Token scope: Use minimum required permissions (Pages + Search)
3. Token rotation: Regenerate tokens periodically
4. Access control: Use Wiki.js groups/permissions for sensitive docs
5. Audit logs: Review Wiki.js audit logs for unexpected operations

Performance

• GraphQL queries: Optimized for minimal data transfer
• Search: Indexed by Wiki.js for fast results
• Pagination: Configurable result limits (default: 20)
• Caching: Wiki.js handles internal caching

Development

Running Tests

# All tests
pytest -v

# Specific test file
pytest tests/test_config.py -v

# Integration tests only
pytest tests/test_wikijs_client.py -v -k integration

Code Structure

• config.py: Configuration loading and validation
• wikijs_client.py: GraphQL client implementation
• server.py: MCP server setup and tool routing
• tools/pages.py: Page management MCP tools
• tools/lessons_learned.py: Lessons learned MCP tools

License

MIT License - See repository root for details

Support

For issues and questions:

• Repository: ssh://git@hotserv.tailc9b278.ts.net:2222/bandit/support-claude-mktplace.git
• Issues: Contact repository maintainer
• Documentation: /docs/references/MCP-WIKIJS.md