Wiki.js MCP Server

Wiki.js MCP Server

Model Context Protocol（MCP）サーバーとして、階層型ドキュメントに対応し、Docker でデプロイできる、Wiki.js と連携する包括的なサーバーです。複数のリポジトリや大規模なドキュメントを管理する組織に最適です。

🚀 クイックスタート

1. 環境のセットアップ

まず、このリポジトリをクローンし、環境変数を設定します。

# Copy environment template
cp config/example.env .env

# Edit .env with your credentials:
# - Set POSTGRES_PASSWORD to a secure password
# - Update other settings as needed

2. Docker でのデプロイ（推奨）

# Start Wiki.js with Docker
docker-compose -f docker.yml up -d

Wiki.js は http://localhost:3000 で利用できます。

Web インターフェースで初期設定を完了します。

3. MCP サーバーのセットアップ

# Install Python dependencies
./setup.sh

# Update .env with Wiki.js API credentials:
# - Get API key from Wiki.js admin panel  
# - Set WIKIJS_TOKEN in .env file

# Test the connection
./test-server.sh

# Start MCP server
# (not needed for AI IDEs like Cursor, simply click on the refresh icon after editing mcp.json
# and you should see a green dot with all tools listed. In existing open Cursor windows,
# this refresh is necessary in order to use this MCP)
./start-server.sh

4. Cursor MCP の設定

~/.cursor/mcp.json に追加します。

{
  "mcpServers": {
    "wikijs": {
      "command": "/path/to/wiki-js-mcp/start-server.sh"
    }
  }
}

🎯 Cursor との連携を強化

ドキュメントを優先する開発のためのグローバルルール

コーディングの前にドキュメントが自動的に活用されるよう、Cursor にグローバルルールを追加します。

Before writing any code, always:
1. Search existing documentation using wikijs_search_pages to understand current patterns and architecture
2. Check for related components, functions, or modules that might already exist
3. If documentation exists for similar functionality, follow the established patterns and naming conventions
4. If no documentation exists, create it using wikijs_create_page or wikijs_create_nested_page before implementing
5. Always update documentation when making changes using wikijs_sync_file_docs
6. For new features, use wikijs_create_repo_structure to plan the documentation hierarchy first

これらのルールにより、AI アシスタントは次のことを行えます。

• ✅ 実装を提案する前にドキュメントを確認する
• ✅ 既存のパターンと規約に従う
• ✅ ドキュメントを自動的に最新の状態に保つ
• ✅ 新機能のための構造化されたドキュメントを作成する
• ✅ 既存の機能との重複を避ける

Cursor の使用上のヒント

# Before starting a new feature
"Search the documentation for authentication patterns before implementing login"

# When creating components
"Create nested documentation under frontend-app/components before building the React component"

# For API development
"Check existing API documentation and create endpoint docs using the established structure"

# During refactoring
"Update all related documentation pages for the files I'm about to modify"

🚀 主な機能

📁 階層型ドキュメント

• リポジトリ単位の整理：複数のリポジトリ向けに構造化されたドキュメントを作成
• ネストされたページの作成：親子関係を自動的に設定
• 自動整理：ファイルの種類（コンポーネント、API、ユーティリティなど）に応じてスマートに分類
• エンタープライズ規模への対応：数百のリポジトリと数千のファイルを処理

🔧 主な機能

• GraphQL API との連携：Wiki.js v2 以降に完全対応
• ファイルとページのマッピング：ソースコードとドキュメントを自動的にリンク
• コード構造の分析：クラス、関数、依存関係を抽出
• 一括操作：複数のページを同時に更新
• 変更の追跡：ファイルの変更を監視し、ドキュメントを同期

🐳 Docker のセットアップ

• 1 つのコマンドでデプロイ：PostgreSQL を含む Wiki.js のセットアップを完了
• 永続ストレージ：コンテナを再起動してもデータを保持
• ヘルスチェック：サービスを自動的に監視
• 本番環境に対応：開発とデプロイに最適化

🔍 スマート機能

• リポジトリコンテキストの検出：Git リポジトリを自動検出
• コンテンツの生成：コード構造からドキュメントを自動作成
• 検索との連携：階層構造のコンテンツを全文検索
• ヘルスモニタリング：接続状態とエラーを管理

📊 MCP ツール（合計 21 個）

🏗️ 階層型ドキュメントツール

1. wikijs_create_repo_structure - リポジトリのドキュメント構造を一式作成
2. wikijs_create_nested_page - 階層パスを指定してページを作成
3. wikijs_get_page_children - ページの親子関係をたどる
4. wikijs_create_documentation_hierarchy - プロジェクトファイルをドキュメントに自動整理

📝 ページ管理の基本機能

5. wikijs_create_page - 新しいページを作成（親ページにも対応）
6. wikijs_update_page - 既存のページを更新
7. wikijs_get_page - ページの内容とメタデータを取得
8. wikijs_search_pages - テキストでページを検索（GraphQL の問題を修正済み）

🗑️ 削除とクリーンアップのツール

9. wikijs_delete_page - ID またはパスを指定してページを削除
10. wikijs_batch_delete_pages - パターンマッチングと安全確認を行ってページを一括削除
11. wikijs_delete_hierarchy - 複数のモードでページ階層全体を削除
12. wikijs_cleanup_orphaned_mappings - 孤立したファイルとページのマッピングをクリーンアップ

🗂️ 整理と構造

13. wikijs_list_spaces - 最上位のドキュメントスペースを一覧表示
14. wikijs_create_space - 新しいドキュメントスペースを作成
15. wikijs_manage_collections - ページコレクションを管理

🔗 ファイル連携

16. wikijs_link_file_to_page - ソースファイルをドキュメントページにリンクします
17. wikijs_sync_file_docs - コードの変更をドキュメントに同期します
18. wikijs_generate_file_overview - ファイルのドキュメントを自動生成します

🚀 一括操作

19. wikijs_bulk_update_project_docs - 複数のページを一括更新します

🔧 システムツール

20. wikijs_connection_status - API 接続の状態を確認します
21. wikijs_repository_context - リポジトリのマッピングとコンテキストを表示します

🏢 エンタープライズ向けのユースケース

複数リポジトリのドキュメント

Company Documentation/
├── frontend-web-app/
│   ├── Overview/
│   ├── Components/
│   │   ├── Button/
│   │   ├── Modal/
│   │   └── Form/
│   ├── API Integration/
│   └── Deployment/
├── backend-api/
│   ├── Overview/
│   ├── Controllers/
│   ├── Models/
│   └── Database Schema/
├── mobile-app/
│   ├── Overview/
│   ├── Screens/
│   └── Native Components/
└── shared-libraries/
    ├── UI Components/
    ├── Utilities/
    └── Type Definitions/

自動分類

システムがファイルをインテリジェントに分類します。

• コンポーネント：React/Vue コンポーネント、UI 要素
• API：エンドポイント、コントローラー、ルート
• ユーティリティ：ヘルパー関数、ユーティリティ
• サービス：ビジネスロジック、外部連携
• モデル：データモデル、型、スキーマ
• テスト：ユニットテスト、統合テスト
• 設定：設定ファイル、環境設定

📚 使用例

リポジトリのドキュメントを作成する

# Create complete repository structure
await wikijs_create_repo_structure(
    "My Frontend App",
    "Modern React application with TypeScript",
    ["Overview", "Components", "API", "Testing", "Deployment"]
)

# Create nested component documentation
await wikijs_create_nested_page(
    "Button Component",
    "# Button Component\n\nReusable button with multiple variants...",
    "my-frontend-app/components"
)

# Auto-organize entire project
await wikijs_create_documentation_hierarchy(
    "My Project",
    [
        {"file_path": "src/components/Button.tsx"},
        {"file_path": "src/api/users.ts"},
        {"file_path": "src/utils/helpers.ts"}
    ],
    auto_organize=True
)

ドキュメントの管理

# Clean up and manage documentation
# Preview what would be deleted (safe)
preview = await wikijs_delete_hierarchy(
    "old-project",
    delete_mode="include_root",
    confirm_deletion=False
)

# Delete entire deprecated project
await wikijs_delete_hierarchy(
    "old-project",
    delete_mode="include_root", 
    confirm_deletion=True
)

# Batch delete test pages
await wikijs_batch_delete_pages(
    path_pattern="*test*",
    confirm_deletion=True
)

# Clean up orphaned file mappings
await wikijs_cleanup_orphaned_mappings()

⚙️ 設定

環境変数

# Docker Database Configuration
POSTGRES_DB=wikijs
POSTGRES_USER=wikijs
POSTGRES_PASSWORD=your_secure_password_here

# Wiki.js Connection
WIKIJS_API_URL=http://localhost:3000
WIKIJS_API_KEY=your_jwt_token_here

# Alternative: Username/Password
WIKIJS_USERNAME=your_username
WIKIJS_PASSWORD=your_password

# Database & Logging
WIKIJS_MCP_DB=./wikijs_mappings.db
LOG_LEVEL=INFO
LOG_FILE=wikijs_mcp.log

# Repository Settings
REPOSITORY_ROOT=./
DEFAULT_SPACE_NAME=Documentation

認証オプション

1. JWT トークン（推奨）：Wiki.js 管理パネルの API キーを使用します
2. ユーザー名／パスワード：従来のログイン認証情報

🔧 技術アーキテクチャ

GraphQL 連携

• GraphQL API の完全サポート：Wiki.js v2 以降とのネイティブ互換性
• 最適化されたクエリ：効率的なデータ取得と変更
• エラー処理：包括的な GraphQL エラー管理
• 再試行ロジック：指数バックオフによる自動再試行

データベースレイヤー

• SQLite ストレージ：ファイルとページのマッピングをローカルに保存
• リポジトリコンテキスト：Git リポジトリの検出と追跡
• 変更追跡：同期を検出するためのファイルハッシュ監視
• 関係管理：親子ページの階層構造

コード分析

• AST 解析：Python のクラス、関数、インポートを抽出
• 構造検出：コードのパターンと構成を特定
• ドキュメント生成：包括的な概要を自動作成
• 依存関係のマッピング：インポートと関係を追跡

📈 パフォーマンスとスケーラビリティ

• 非同期操作：すべての API 呼び出しでノンブロッキング I/O を使用
• 一括処理：大規模プロジェクト向けの効率的なバッチ操作
• キャッシュ：ページの関係とメタデータをスマートにキャッシュ
• コネクションプーリング：HTTP クライアント管理を最適化

🛠️ 開発

プロジェクト構成

wiki-js-mcp/
├── src/
│   └── wiki_mcp_server.py      # Main MCP server implementation
├── config/
│   └── example.env             # Configuration template
├── docker.yml                  # Docker Compose setup
├── pyproject.toml              # Poetry dependencies
├── requirements.txt            # Pip dependencies
├── setup.sh                    # Environment setup script
├── start-server.sh             # MCP server launcher
├── test-server.sh              # Interactive testing script
├── HIERARCHICAL_FEATURES.md    # Hierarchical documentation guide
├── DELETION_TOOLS.md           # Deletion and cleanup guide
├── LICENSE                     # MIT License
└── README.md                   # This file

依存関係

• FastMCP：公式 Python MCP SDK
• httpx：GraphQL 用の非同期 HTTP クライアント
• SQLAlchemy：マッピング用のデータベース ORM
• Pydantic：設定と検証
• tenacity：信頼性を高める再試行ロジック

🔍 トラブルシューティング

Docker の問題

# Check containers
docker-compose -f docker.yml ps

# View logs
docker-compose -f docker.yml logs wiki
docker-compose -f docker.yml logs postgres

# Reset everything
docker-compose -f docker.yml down -v
docker-compose -f docker.yml up -d

接続の問題

# Check Wiki.js is running
curl http://localhost:3000/graphql

# Verify authentication
./test-server.sh

# Debug mode
export LOG_LEVEL=DEBUG
./start-server.sh

よくある問題

• ポートの競合：必要に応じて docker.yml のポート 3000 を変更してください
• データベースの問題：postgres_data/ を削除して再起動してください
• API 権限：API キーに管理者権限があることを確認してください
• Python の依存関係：./setup.sh を実行して再インストールしてください

📚 ドキュメント

• 階層機能ガイド - エンタープライズ向けドキュメントの完全ガイド
• 削除ツールガイド - 削除とクリーンアップの包括的なツール
• 設定例 - 環境設定

🤝 貢献

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

📄 ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙏 謝辞

• Wiki.js Team：優れたドキュメントプラットフォームを提供してくださったことに感謝します
• MCP Protocol：標準化された AI 統合フレームワークを提供してくださったことに感謝します
• FastMCP：Python MCP SDK を提供してくださったことに感謝します

---

ドキュメントを大規模に展開する準備はできていますか？ 🚀 wikijs_create_repo_structure から始めて、エンタープライズグレードのドキュメント階層を構築しましょう！ Cursor のグローバルルールを使って、ドキュメント優先の開発を徹底しましょう！ 📚✨