avr-docs-mcp

公式

このMCP（Model Context Protocol）サーバーは、Agent Voice Response Wiki.JSインスタンスからページを検索・一覧表示するためのWiki.JSとの統合を提供します。

GitHub

Avr Docs MCPで何ができますか？

キーワードでWikiページを検索 — search_wiki_pagesを使用してクエリに一致するページを検索します。オプションでページネーション制御が可能です。
すべてのWikiページを一覧表示 — list_wiki_pagesを介してWiki.JSインスタンスから利用可能なページのページネーション付きリストを取得します。
特定のページを取得 — get_wiki_pageを使用して、数値IDまたはパス文字列で単一ページの全コンテンツを取得します。
Wiki.JS接続をテスト — サーバーがWiki.JSインスタンスに到達し、認証できることを確認します。

ドキュメント

AVR Docs MCP Server with Wiki.JS Integration

このMCP（Model Context Protocol）サーバーは、Wiki.JSとの統合を提供し、Wiki.JSインスタンスからページを検索・一覧表示します。

機能

Wiki.JSページの検索: キーワードやトピックでページを検索
Wiki.JSページの一覧表示: 利用可能な全ページのページネーション付き一覧を取得
特定ページの取得: IDで特定のページを取得
接続テスト: Wiki.JSインスタンスへの接続をテスト
複数のトランスポートモード: stdioとHTTPストリームモードの両方をサポート
Dockerサポート: ヘルスチェック付きのすぐに使えるDockerイメージ

セットアップ

前提条件

稼働中のWiki.JSインスタンス
ページ読み取りに適切な権限を持つAPIキー

環境変数

環境変数は2つの方法で設定できます：

オプション1: .envファイルを使用（推奨）

サンプル環境ファイルをコピーします：

cp .env.example .env

.envファイルを実際の値で編集します：

# Wiki.JS Configuration
WIKI_JS_BASE_URL=https://your-wiki-instance.com
WIKI_JS_API_KEY=your-api-key-here
LOG_LEVEL=info

# MCP Server Configuration
MCP_MODE=stdio
PORT=3000

オプション2: システム環境変数を使用

export WIKI_JS_BASE_URL="https://your-wiki-instance.com"
export WIKI_JS_API_KEY="your-api-key-here"
export LOG_LEVEL="info"
export MCP_MODE="stdio"
export PORT="3000"

インストール

依存関係をインストールします：

npm install

プロジェクトをビルドします：

npm run build

接続をテストします（任意）：

npm test

サーバーを実行します：

npm start

開発用：

npm run dev

実行モード

サーバーは2つの動作モードをサポートしています：

Stdioモード（デフォルト）

サーバーはデフォルトでstdioモードで実行され、標準入出力を通じて通信します。これは従来のMCPモードです。

npm start
# or
npm run start:http  # for HTTP mode
# or
MCP_MODE=stdio npm start

HTTPストリームモード

サーバーはHTTPモードでも実行でき、MCP通信用のServer-Sent Events（SSE）を備えたREST APIを提供します。

npm run start:http
# or
MCP_MODE=http npm start

HTTPモードで実行する場合、サーバーは以下を提供します：

ヘルスチェック: GET /health - サーバーステータスを返します
MCPエンドポイント: POST /mcp - JSON-RPC 2.0を使用したMCP通信エンドポイント

HTTPモードのテスト

curlまたはPostmanを使用してHTTPモードをテストできます：

# Health check
curl http://localhost:3000/health

# Initialize MCP session
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-client",
        "version": "1.0.0"
      }
    }
  }'

# List available tools (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool (use session ID from initialize response)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_wiki_pages",
      "arguments": {
        "query": "deepgram",
        "page": 1,
        "limit": 10
      }
    }
  }'

または、組み込みのテストクライアントを使用します：

npm run test:http

Dockerの使用法

Dockerイメージの使用

# Run in stdio mode (default)
docker run -d \
  --name avr-docs-mcp \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  agentvoiceresponse/avr-docs-mcp:latest

# Run in HTTP mode
docker run -d \
  --name avr-docs-mcp \
  -p 3000:3000 \
  -e WIKI_JS_BASE_URL="https://your-wiki-instance.com" \
  -e WIKI_JS_API_KEY="your-api-key-here" \
  -e MCP_MODE="http" \
  -e PORT="3000" \
  agentvoiceresponse/avr-docs-mcp:latest

Docker Compose

version: '3.8'

services:
  avr-docs-mcp:
    image: agentvoiceresponse/avr-docs-mcp:latest
    container_name: avr-docs-mcp
    ports:
      - "3000:3000"  # Only needed for HTTP mode
    environment:
      - WIKI_JS_BASE_URL=https://your-wiki-instance.com
      - WIKI_JS_API_KEY=your-api-key-here
      - MCP_MODE=http
      - PORT=3000
      - LOG_LEVEL=info
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

利用可能なツール

1. search_wiki_pages

キーワードでWiki.JS内のページを検索します。

パラメータ:

query（必須）: 検索クエリ
page（任意）: ページネーションのページ番号（デフォルト: 1）
limit（任意）: 1ページあたりの結果数（デフォルト: 10、最大: 50）

2. list_wiki_pages

Wiki.JS内の利用可能な全ページを一覧表示します。

パラメータ:

page（任意）: ページネーションのページ番号（デフォルト: 1）
limit（任意）: 1ページあたりの結果数（デフォルト: 20、最大: 50）

3. get_wiki_page

IDまたはパスで特定のページを取得します。

パラメータ:

pageId（必須）: 取得するページのID（数値）またはパス（文字列）。例: IDの場合は'3'、パスの場合は'deepgram'

Wiki.JS API設定

このMCPサーバーはWiki.JS GraphQL API（/graphqlエンドポイント）を使用します。Wiki.JSインスタンスでAPIアクセスが有効になっており、APIキーに以下の権限があることを確認してください：

page:read - ページコンテンツの読み取り
page:list - ページの一覧表示
search:read - ページの検索

サーバーはすべての操作でGraphQLクエリとレスポンスを自動的に処理します。Wiki.JS GraphQL APIにはいくつかの制限があることに注意してください：

検索および一覧表示操作はネイティブのページネーションをサポートしていないため、ページネーションはクライアント側でシミュレートされます
検索結果には完全なページコンテンツは含まれません
一覧表示結果には完全なページコンテンツは含まれません（完全なコンテンツにはget_wiki_pageを使用してください）
タグはカンマ区切りの文字列ではなく、文字列の配列として返されます

ログ

サーバーには、設定可能なログレベルを備えた包括的なログ機能が含まれています：

debug - 詳細なデバッグ情報
info - 一般情報（デフォルト）
warn - 警告メッセージのみ
error - エラーメッセージのみ

ログの詳細度を制御するには、LOG_LEVEL環境変数を設定します。

エラーハンドリング

サーバーには、以下に対する包括的なエラーハンドリングが含まれています：

環境変数の欠落
ネットワーク接続の問題
API認証の失敗
無効なページID
レート制限

開発

ホットリロードを使用した開発モードで実行するには：

npm run watch

ビルド

本番用にビルドするには：

npm run build

コンパイルされたJavaScriptはdist/ディレクトリに出力されます。

サポート＆コミュニティ

GitHub: https://github.com/agentvoiceresponse - 問題の報告、コードの貢献。
Discord: https://discord.gg/DFTU69Hg74 - コミュニティディスカッションに参加。
Docker Hub: https://hub.docker.com/u/agentvoiceresponse - Dockerイメージを検索。
Wiki: https://wiki.agentvoiceresponse.com/en/home - プロジェクトのドキュメントとガイド。

AVRのサポート

AVRは無料のオープンソースです。いかなるサポートも完全に任意であり、個人的な感謝の印として意図されています。寄付は機能、サービス、または特別な利益へのアクセスを提供するものではなく、プロジェクトは寄付に関係なく完全に利用可能です。

ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。