Wikijs Mcp Server

Wiki.js MCP サーバー

GraphQL API を介して Wiki.js と連携する Model Context Protocol（MCP）サーバーです。

📖 説明

このプロジェクトは、GraphQL API を介して Wiki.js とやり取りするための MCP サーバーを提供します。MCP（Model Context Protocol）は Anthropic が開発したオープンプロトコルで、AI モデルが外部サービスやツールと安全にやり取りできるようにします。

このサーバーは、MCP をサポートするさまざまな AI エージェントやツールから利用できる、Wiki.js を操作するための統一インターフェースを提供します。

✨ 機能

📄 ページ管理

• ID で Wiki.js のページを取得
• ID でページの内容を取得
• 並べ替えオプションを指定してページを一覧表示
• クエリでページを検索
• ページを新規作成
• 既存のページを更新
• ページを削除
• 🆕 非公開のページを含むすべてのページを一覧表示
• 🆕 非公開のページを検索
• 🆕 ページを強制削除（非公開のページを含む）
• 🆕 ページの公開状態を取得
• 🆕 非公開のページを公開

👥 ユーザー管理

• ユーザーを一覧表示
• クエリでユーザーを検索
• ユーザーを新規作成
• ユーザー情報を更新

🔧 グループ管理

• ユーザーグループを一覧表示

🌐 トランスポート

• STDIO：エディター連携用（Cursor、VS Code）
• HTTP：ウェブ連携と API アクセス用

🚀 クイックスタート

⚡ 今すぐ始めますか？ 5 分でわかるガイドをご覧ください。

インストール

1. リポジトリをクローンします：

git clone https://github.com/heAdz0r/wikijs-mcp-server.git
cd wikijs-mcp-server

2. 自動セットアップを実行します：

npm run setup

このスクリプトは次の処理を自動で行います。

• 依存関係をインストール
• example.env を基に .env ファイルを作成
• TypeScript コードをビルド

設定

3. .env ファイルを編集して、Wiki.js の設定を指定します。

# Port for HTTP MCP server
PORT=3200

# Base URL for Wiki.js (without /graphql)
WIKIJS_BASE_URL=http://localhost:3000

# Wiki.js API token
WIKIJS_TOKEN=your_wikijs_api_token_here

4. .cursor/mcp.json ファイルを編集し、your_wikijs_api_token_here を実際のトークンに置き換えます。

Wiki.js API トークンの取得方法：

1. Wiki.js の管理パネルにログインします
2. 「API」セクションに移動します
3. 必要な権限を付与した新しい API キーを作成します
4. トークンを .env と .cursor/mcp.json の両方にコピーします

📦 実行

HTTP サーバー（推奨）

# Start main HTTP server with Cursor MCP support
npm start
# or
npm run start:http

# Stop server
npm run stop

TypeScript 版

npm run start:typescript

STDIO モード（エディターとの直接連携用）

npm run server:stdio

開発モード

npm run dev

テスト

npm test

🔌 エディター連携

Cursor IDE

⚠️ 重要： .cursor/mcp.json ファイルがないと、Cursor との連携は動作しません！

クイックセットアップ

1. HTTP サーバーを起動します：

npm start

2. 設定を自動セットアップします：

npm run setup:cursor

3. .cursor/mcp.json を編集し、実際のトークンを指定します。

{
  "mcpServers": {
    "wikijs": {
      "transport": "http",
      "url": "http://localhost:3200/mcp",
      "events": "http://localhost:3200/mcp/events",
      "cwd": ".",
      "env": {
        "WIKIJS_BASE_URL": "http://localhost:3000",
        "WIKIJS_TOKEN": "your_real_wiki_js_token_here"
      }
    }
  }
}

重要なパラメーター

• transport: "http" - 必須の HTTP トランスポート
• url: "http://localhost:3200/mcp" - JSON-RPC 用の正確な URL
• events: "http://localhost:3200/mcp/events" - Server-Sent Events 用の URL
• WIKIJS_TOKEN - 実際の Wiki.js API トークン（プレースホルダーではありません！）

確認

セットアップ後、mcp_wikijs_* というプレフィックスが付いたツールが Cursor に表示されます。

• mcp_wikijs_list_pages()
• mcp_wikijs_search_pages()
• mcp_wikijs_get_page()
• その他...

VS Code（MCP 拡張機能を使用）

VS Code の設定に追加します。

{
  "mcp.servers": {
    "wikijs": {
      "command": "node",
      "args": ["lib/mcp_wikijs_stdin.js"],
      "cwd": "/path/to/wikijs-mcp"
    }
  }
}

🛠 開発

プロジェクト構成

wikijs-mcp-server/
├── src/                    # TypeScript source code
│   ├── server.ts          # HTTP server
│   ├── tools.ts           # Tool definitions
│   ├── api.ts             # Wiki.js API client
│   ├── types.ts           # Data types
│   ├── schemas.ts         # Zod validation schemas
│   └── README.md          # Source code documentation
├── lib/                   # JavaScript library files
│   ├── fixed_mcp_http_server.js    # Main HTTP server (compiled)
│   ├── mcp_wikijs_stdin.js         # STDIN server for editors
│   ├── mcp_client.js               # Demo MCP client
│   ├── mcp_wrapper.js              # MCP protocol utilities
│   └── README.md                   # Library documentation
├── scripts/               # Management scripts
│   ├── setup.sh          # Initial setup
│   ├── start_http.sh     # Start HTTP server
│   ├── stop_server.sh    # Stop HTTP server
│   ├── start_typescript.sh # Start TypeScript version
│   ├── setup_cursor_mcp.sh # Cursor setup
│   ├── test.sh           # Run tests
│   ├── test_mcp.js       # Test HTTP server
│   ├── test_mcp_stdin.js # Test STDIN server
│   └── README.md         # Scripts documentation
├── .cursor/               # Cursor MCP configuration
│   └── mcp.json          # MCP configuration file (CRITICALLY IMPORTANT!)
├── dist/                  # Compiled TypeScript code
├── package.json           # Project metadata
└── README.md             # Main documentation

🚨 非常に重要： Cursor との連携には .cursor/mcp.json ファイルが必要です！

利用可能なスクリプト

セットアップとビルド

• npm run setup - プロジェクトの初期セットアップ
• npm run build - TypeScript プロジェクトをビルド
• npm run setup:cursor - Cursor 連携をセットアップ

サーバーの実行

• npm start / npm run start:http - HTTP MCP サーバー（ポート 3200）
• npm run stop - すべての MCP サーバーを停止
• npm run start:typescript - サーバーの TypeScript 版（ポート 8000）
• npm run server:stdio - 直接連携用の STDIO 版

開発とテスト

• npm run dev - ホットリロード対応の開発モード
• npm run demo - 機能のデモを実行
• npm test - テストを実行
• npm run client - デモクライアントを実行

API エンドポイント（HTTP モード）

• GET /tools - 利用可能なツールの一覧
• GET /health - サーバーのヘルスチェック
• POST /mcp - MCP JSON-RPC エンドポイント

使用例

// Get list of pages
{
  "method": "list_pages",
  "params": {
    "limit": 10,
    "orderBy": "TITLE"
  }
}

// Create new page
{
  "method": "create_page",
  "params": {
    "title": "New Page",
    "content": "# Title\n\nContent...",
    "path": "folder/new-page"
  }
}

### Search for pages:
```python
# Search in all content and metadata
result = await mcp_client.call_tool("search_pages", {
    "query": "magic system",
    "limit": 5
})

未公開ページの操作：

# Get all pages including unpublished ones
all_pages = await mcp_client.call_tool("list_all_pages", {
    "limit": 100,
    "includeUnpublished": True
})

# Search only unpublished pages
unpublished = await mcp_client.call_tool("search_unpublished_pages", {
    "query": "draft",
    "limit": 10
})

# Check page publication status
status = await mcp_client.call_tool("get_page_status", {
    "id": 42
})

# Publish an unpublished page
result = await mcp_client.call_tool("publish_page", {
    "id": 42
})

# Force delete page (works with unpublished pages)
result = await mcp_client.call_tool("force_delete_page", {
    "id": 42
})

ユーザー管理：

# List all users
users = await mcp_client.call_tool("list_users")

# Search users by query
search_result = await mcp_client.call_tool("search_users", {
    "query": "John"
})

# Create new user
new_user = await mcp_client.call_tool("create_user", {
    "email": "[email protected]",
    "name": "John Doe",
    "passwordRaw": "password123",
    "providerKey": "local",
    "groups": [1],
    "mustChangePassword": false,
    "sendWelcomeEmail": true
})

# Update user information
updated_user = await mcp_client.call_tool("update_user", {
    "id": 1,
    "name": "John Doe Updated"
})

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

接続の問題

1. Wiki.js が起動しており、アクセス可能であることを確認します
2. WIKIJS_BASE_URL が正しいことを確認します
3. API トークンが有効であることを確認します

MCP の問題

1. Node.js のバージョンを確認します（>=18.0.0 が必要です）
2. すべての依存関係がインストールされていることを確認します
3. サーバーログにエラーがないか確認します

📚 ドキュメント

• ソースコードのドキュメント - TypeScript ソースコードの構造
• ライブラリのドキュメント - JavaScript ライブラリファイル
• スクリプトのドキュメント - すべての管理スクリプトの説明
• 変更履歴 - リリースと更新のログ
• ライセンス - プロジェクトの使用条件

🤝 コントリビューション

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 ファイルをご覧ください。

🔗 便利なリンク

• Wiki.js - Wiki.js 公式ウェブサイト
• Model Context Protocol - MCP 仕様
• Anthropic - MCP プロトコルの開発元
• GraphQL - API のクエリ言語

⭐ サポート

このプロジェクトが役に立った場合は、GitHub で ⭐ を付けてください！

ご質問がありますか？Issue を作成するか、ドキュメントをご覧ください。

🆕 新機能：自動 URL

検索ステージ

検索は 4 つのステージで行われます：

1. GraphQL API 検索 - インデックス化されたコンテンツを高速に検索
2. メタデータ検索 - タイトル、パス、ページの説明を検索
3. HTTP コンテンツ検索 - HTTP 経由でページコンテンツを詳細に検索
4. 強制検証 - 既知のページを対象としたフォールバック検索

使用例

コンテンツ検索

{
  "method": "search_pages",
  "params": {
    "query": "ZELEBOBA",
    "limit": 5
  }
}

結果：

[
  {
    "id": 103,
    "path": "test/test-page",
    "title": "Test Page",
    "description": "Test page to demonstrate Wiki.js API capabilities",
    "url": "http://localhost:8080/en/test/test-page"
  }
]

タイトル検索

{
  "method": "search_pages",
  "params": {
    "query": "find me",
    "limit": 3
  }
}

結果：

[
  {
    "id": 108,
    "path": "test/test-gemini-mcp",
    "title": "Test Gemini MCP Page (find me)",
    "url": "http://localhost:8080/en/test/test-gemini-mcp"
  }
]

新しい検索機能のメリット

• ✅ API 権限が限られていてもページを検索 - HTTP フォールバックを使用します
• ✅ 多段階検索 - 複数の方法を組み合わせます
• ✅ コンテンツ検索 - ページ内のテキストを検索します
• ✅ メタデータ検索 - タイトル、パス、説明を検索します
• ✅ フォールバック方法 - 既知のページについて確実に結果を取得します
• ✅ 正しい URL - すべての結果にすぐ使えるリンクが含まれます

技術詳細

HTML コンテンツの処理

システムは以下の方法で HTML からテキストを自動的に抽出します：

• <template slot="contents"> ブロックを検索
• HTML タグとエンティティをクリーンアップ
• ページ全体のコンテンツにフォールバック

GraphQL API の権限が限られている場合、システムは以下の処理を行います：

• コンテンツ取得に HTTP 方式へ切り替え
• HTML ページに直接リクエストを送信
• すべてのページメタデータを保持

📝 変更履歴

バージョン 1.3.0 - 未公開ページ管理（最新）

🆕 新機能：

• list_all_pages - 未公開ページを含むすべてのページを取得
• search_unpublished_pages - 未公開ページのみを検索
• force_delete_page - 未公開ページにも対応する強化された削除機能
• get_page_status - 任意のページの公開状態を確認
• publish_page - 未公開ページをプログラムから公開

🔧 改善：

• 未公開ページ管理用の新しいルートをサーバー API に追加
• ページ削除処理のエラーハンドリングを改善
• 高度なページ操作に対応する包括的な GraphQL ミューテーションをサポート
• プロジェクトを再構成：整理しやすくするため、JavaScript ファイルを lib/ ディレクトリに移動

🐛 バグ修正：

• 標準 API 経由で未公開ページにアクセスする際の問題を修正
• 管理者レベルの操作における認証処理を改善

バージョン 1.2.0 - 国際版

🌍 国際化：

• ドキュメントを英語に完全翻訳
• README.md と QUICK_START.md が英語で利用可能になりました
• 国際市場への展開に向けて準備しました

バージョン 1.1.0 - 検索機能とユーザー管理の強化

✨ 機能：

• 複数の方法を組み合わせたスマートなページ検索（GraphQL + コンテンツ + メタデータ）
• ユーザー管理ツール（作成、更新、検索）
• グループ管理機能
• HTML ページからのコンテンツ抽出を改善

🛠️ 利用可能なツール

📄 ページツール

ツール名	説明	パラメーター
get_page	ID でページ情報を取得	id: number
get_page_content	ID でページのコンテンツを取得	id: number
list_pages	並べ替えてページを一覧表示	limit?: number, orderBy?: string
search_pages	クエリでページを検索	query: string, limit?: number
create_page	新しいページを作成	title: string, content: string, path: string, description?: string, tags?: string[]
update_page	既存のページを更新	id: number, content: string
delete_page	ページを削除	id: number
list_all_pages	🆕 非公開ページを含むすべてのページを一覧表示	limit?: number, orderBy?: string, includeUnpublished?: boolean
search_unpublished_pages	🆕 非公開ページのみを検索	query: string, limit?: number
force_delete_page	🆕 ページを強制削除（非公開ページにも対応）	id: number
get_page_status	🆕 ページの公開ステータスを取得	id: number
publish_page	🆕 非公開ページを公開	id: number

👥 ユーザーツール

ツール名	説明	パラメーター
list_users	すべてのユーザーを一覧表示します	なし
search_users	クエリでユーザーを検索します	query: string
create_user	新しいユーザーを作成します	email: string, name: string, passwordRaw: string, providerKey?: string, groups?: number[], mustChangePassword?: boolean, sendWelcomeEmail?: boolean
update_user	ユーザー情報を更新します	id: number, name: string

🔗 グループツール

ツール名	説明	パラメーター
list_groups	ユーザーグループを一覧表示します	なし