@redairforce/wikijs-mcp

@redairforce/wikijs-mcp

 

A comprehensive Model Context Protocol (MCP) server for Wiki.js integration with hierarchical documentation support and multi-level context management. Now available on npm for easy installation and use with Claude Code.

🚀 Quick Start

npm Installation (Recommended)

# Install globally for CLI usage
npm install -g @redairforce/wikijs-mcp

# Or install locally in your project
npm install @redairforce/wikijs-mcp

Local Development Installation

# Clone the repository
git clone https://github.com/redairforce/wikijs-mcp.git
cd wikijs-mcp

# Install dependencies
npm install

# Build the package
npm run build

Configuration

Create a .env file in your project directory:

# Copy the example configuration
cp .env.example .env

# Edit with your Wiki.js credentials
WIKIJS_API_URL=https://your-wiki.example.com
WIKIJS_TOKEN=your_jwt_token_here

Quick CLI Test

# Test your Wiki.js connection
wikijs-mcp test-connection

# List existing pages
wikijs-mcp list-pages

# Start the MCP server
wikijs-mcp server

Usage with Claude Code

Add to your Claude Code MCP configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "wikijs": {
      "command": "wikijs-mcp",
      "args": ["server"]
    }
  }
}

🎯 Features

📝 Core Page Management

• Create/Update/Delete pages with full content support
• Search across all Wiki.js content
• List pages with pagination
• Get individual pages by ID or path

🏗️ Hierarchical Documentation

• Nested page creation with automatic path management
• Repository structure generation for organized documentation
• Auto-categorization by file type (components, API, utils, etc.)

🔧 Advanced Features

• Bulk operations for creating multiple pages
• File-to-documentation sync with code analysis
• Automatic content generation from source files
• GraphQL integration with comprehensive error handling

🔌 Claude Integration

• 22 MCP tools available to Claude Code
• Real-time documentation updates during development
• Code-aware content generation with syntax highlighting
• Project structure analysis and documentation

📊 Available MCP Tools

Connection & Status

1. wikijs_connection_status - Test Wiki.js connection
2. wikijs_get_site_info - Get detailed site information

Core Page Management

1. wikijs_create_page - Create new pages
2. wikijs_update_page - Update existing pages
3. wikijs_get_page - Retrieve pages by ID/path
4. wikijs_delete_page - Delete pages
5. wikijs_list_pages - List pages with pagination
6. wikijs_search_pages - Search page content

Hierarchical Documentation

1. wikijs_create_nested_page - Create pages with parent-child relationships
2. wikijs_create_repo_structure - Generate complete repository documentation

Bulk Operations

1. wikijs_bulk_create_pages - Create multiple pages at once

File Integration

1. wikijs_sync_file_docs - Sync source files with documentation
2. wikijs_generate_file_overview - Generate documentation from code files

Multi-Level Context Management

1. wikijs_detect_context - Auto-detect repository and workspace context
2. wikijs_init_repository - Initialize repository documentation context
3. wikijs_init_workspace - Initialize multi-repository workspace
4. wikijs_set_context_mode - Switch between repository/workspace/architectural modes
5. wikijs_get_context - Get current context optimized for Claude consumption
6. wikijs_repository_status - Show current repository context and documentation status
7. wikijs_workspace_status - Show workspace with all repositories and status
8. wikijs_cross_repo_link - Create architectural mapping between repositories
9. wikijs_smart_sync_file - Intelligently sync files with context awareness

🛠️ Command Line Usage

The package also provides a CLI for direct Wiki.js management:

Test Connection

wikijs-mcp test-connection

Create a Page

wikijs-mcp create-page "My Page Title" "# Content here" "/docs/my-page"

List Pages

wikijs-mcp list-pages --limit 20

Search Pages

wikijs-mcp search "API documentation"

Start MCP Server

wikijs-mcp server
# or simply
wikijs-mcp

📚 Usage Examples

Creating Nested Documentation

// Claude can execute this via MCP tools
await wikijs_create_nested_page({
  title: "Button Component",
  content: "# Button Component\n\nReusable button with multiple variants...",
  parentPath: "/frontend/components",
  description: "React button component documentation"
});

Repository Structure Generation

await wikijs_create_repo_structure({
  repoName: "My Frontend App",
  description: "Modern React application with TypeScript",
  sections: ["Overview", "Components", "API", "Testing", "Deployment"]
});

File-to-Documentation Sync

await wikijs_sync_file_docs({
  filePath: "./src/components/Button.tsx",
  wikiPath: "/frontend/components/button",
  extractContent: true,
  includeMetadata: true
});

⚙️ Configuration Options

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | WIKIJS_API_URL | Wiki.js instance URL | - | ✅ | | WIKIJS_TOKEN | JWT API token | - | ✅ | | WIKIJS_USERNAME | Username (alternative auth) | - | ✅ | | WIKIJS_PASSWORD | Password (alternative auth) | - | ✅* | | LOG_LEVEL | Logging level | INFO | ❌ | | DEFAULT_SPACE_NAME | Default documentation space | Documentation | ❌ | | REPOSITORY_ROOT | Repository root path | ./ | ❌ |

*Either WIKIJS_TOKEN or both WIKIJS_USERNAME and WIKIJS_PASSWORD required.

🚀 Development

Setup

git clone <repository>
cd custom-wikijs-mcp
npm install

Build

npm run build

Development Mode

npm run dev

Testing

npm test

🧠 Multi-Level Context Architecture

Overview

The WikiJS MCP server features a sophisticated multi-level context system that prevents token explosion while maintaining rich cross-repository intelligence. This enables seamless documentation workflows across multiple repositories and system architecture levels.

📊 Context Levels

| Level | Focus | Token Budget | Use Case | Wiki Spaces | |-------|-------|--------------|----------|--------------| | 📂 Repository | Single repo documentation | ~200 tokens | "Document frontend applications" | frontend-docs | | 🏢 Workspace | Multi-repo coordination | ~800 tokens | "Coordinate frontend & backend repos" | frontend-docs, backend-docs | | 🏗️ Architectural | System-wide relationships | ~1200 tokens | "Document how services integrate with database layer" | system-architecture |

🔄 Documentation Workflow

Phase 1: Individual Repository Documentation

# Navigate to your first repository
cd /path/to/your/repo

# Claude automatically detects repository context
# - Creates .wikijs-state.json for persistent tracking
# - Maps to wiki space: your-project-docs
# - Tracks individual files → wiki pages with hash tracking
# - Documents components, configurations, and setup guides

Example Interaction: ``` You: "Document all the components in this repository" Claude: [Repository Level - 200 tokens]

• Auto-detects current directory as git repository
• Creates comprehensive component catalog
• Maps files to wiki pages with change tracking
• Documents all modules, services, and dependencies

#### **Phase 2: Multi-Repository Coordination**

Navigate to workspace root to coordinate repositories

cd /workspace

Initialize workspace context (ties repositories together)

- Creates .wikijs-workspace.json for multi-repo state

- Detects all repositories in workspace (frontend/, backend/, etc.)

- Enables cross-repository page linking and references

- Coordinates documentation structure across repos

**Example Interaction:**

You: "Now tie the frontend and backend repositories together in the wiki" Claude: [Workspace Level - 800 tokens]

• Loads context from both frontend and backend repositories
• Creates cross-references between wiki spaces
• Documents how repositories relate to each other
• Builds unified navigation across different spaces

#### **Phase 3: Architectural Documentation**

Still at workspace root - switch to architectural focus

- Documents system-wide architecture and relationships

- Creates cross-repository dependency mapping

- Maintains architectural decision records (ADRs)

- Shows network flows and component interactions

**Example Interaction:**

You: "Document the system architecture showing how frontend and backend integrate" Claude: [Architectural Level - 1200 tokens]

• Creates architectural relationship: "Frontend API calls depend on backend authentication service"
• Documents network topology and data flows
• Shows dependencies between different repositories
• Creates system-wide architectural diagrams and explanations

### 🎯 Context Switching

#### **Automatic Detection** (Recommended)
Claude automatically selects appropriate context based on:
- **Current Directory**: Repository root vs workspace root
- **Request Keywords**: "architecture", "cross-repo", "system design"
- **Existing Context**: Detects existing .wikijs-state.json or .wikijs-workspace.json files

#### **Manual Control** (When Needed)

Explicit context switching

"Switch to workspace level to coordinate between repositories" "Move to architectural context to document system design" "Focus on repository level for just this application" ```

📋 Iterative Documentation Refinement

Initial Documentation → Review → Corrections

# After Claude creates initial documentation
You: "I reviewed the API documentation at https://docs.example.com/en/api 
     and need corrections. The authentication endpoint actually uses OAuth2."

Claude: [Repository Level - loads existing context]
- Accesses current .wikijs-state.json context (~200 tokens)
- Loads existing wiki page content for reference
- Makes targeted updates based on your corrections
- Updates wiki.js page with accurate information
- Maintains file change tracking for future updates

Loading Documentation for Interrogation

# Later session - return to work on repository
cd /path/to/your/repo

You: "Load the API documentation so I can ask about the authentication flow"

Claude: [Auto-loads repository context]
- Reads .wikijs-state.json (persistent repository state)  
- Loads existing wiki page mappings and content
- Tracks recent file changes since last sync
- Ready to answer questions about documented configuration

Cross-Repository Questions

# Working at workspace level
cd /workspace

You: "How does the frontend application connect to backend services?"

Claude: [Workspace Level - cross-repository intelligence]  
- Loads frontend-docs documentation context
- Loads backend-docs documentation context  
- References architectural relationship mappings
- Provides comprehensive answer spanning both repositories

🔧 Smart Features

Change Detection & Incremental Updates

# When returning to a repository later
Claude: [Automatically detects]
"I notice 3 files have changed since last documentation sync"
"The wiki page was last updated 5 days ago - should we review for updates?"
"New package.json dependencies detected - documentation may need updates"

Documentation-Driven Development

You: "I'm updating the API service - what documentation needs updates?"

Claude: [Repository context with file mappings]
"Based on tracked file mappings, updating the API service will require updates to:
- /api/endpoints page (version numbers)
- API configuration guide (if parameters change)  
- Architecture page (if networking changes)
Would you like me to prepare these updates?"

🗂️ Generated Wiki Structure

Wiki.js Organization:
├── frontend-docs/                  (Repository Level)
│   ├── components/                 ← Your component documentation
│   ├── deployment-guide/
│   ├── configuration/
│   └── troubleshooting/
│
├── backend-docs/                   (Repository Level)
│   ├── api-services/
│   ├── authentication/
│   ├── database-schemas/
│   └── middleware/
│
└── system-architecture/            (Architectural Level)
    ├── system-overview/
    ├── frontend-backend-integration/
    ├── network-topology/
    ├── dependency-mapping/
    └── architectural-decisions/

💡 Key Benefits

1. Token Efficiency: 200-1200 tokens vs 25,000+ token explosion
2. Persistent Intelligence: Context survives between sessions via JSON files
3. Cross-Repository Relationships: Documents dependencies and integrations
4. Iterative Refinement: Easy corrections and updates to existing documentation
5. Documentation Interrogation: Query your documentation like a knowledge base
6. Automatic Organization: Smart categorization and wiki space management
7. Change Tracking: File hash system prevents unnecessary wiki updates

This creates a living documentation system where your wiki becomes an intelligent, queryable knowledge base that grows and evolves with your codebase.

📖 Advanced Usage

Custom File Analysis

The package automatically categorizes files for documentation:

• Components: React/Vue components, UI elements
• API: Endpoints, controllers, routes
• Utils: Helper functions, utilities
• Services: Business logic, external integrations
• Models: Data models, types, schemas
• Tests: Unit tests, integration tests
• Config: Configuration files, environment setup

GraphQL Integration

Built on the verified GraphQL mutations that work with Wiki.js:

• Proper authentication handling
• Comprehensive error reporting
• Retry logic with exponential backoff
• Full type safety with TypeScript

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Wiki.js Team - For the excellent documentation platform
• MCP Protocol - For standardized AI integration
• @modelcontextprotocol/sdk - For the TypeScript MCP implementation

---

Ready to enhance your documentation workflow? 🚀 Install @redairforce/wikijs-mcp and let Claude manage your Wiki.js content seamlessly!