wowaudit-mcp-server

文書化された WoWAudit API 向けの MCP サーバーです。ギルド名簿、レイド計画、出席状況、週間アクティビティ、ウィッシュリスト、戦利品履歴、アプリケーションを構造化されたツールとして公開し、Raid Lens やその他の MCP クライアントで利用できます。

このサーバーは stdio と @modelcontextprotocol/server 2.x を使用しています。現在の MCP プロトコルに対応し、また古いクライアント向けに SDK のレガシーな 2025 年対応の initialize ハンドシェイクも保持しています。すべての結果にはネイティブの structuredContent に加え、構造化結果を利用しないクライアント向けに同じ JSON がテキストブロックとして含まれます。

要件

• Node.js 20 以降。

• WoWAudit チーム API キー。チーム管理者はチームの 設定 > チーム > API キー フィールドからコピーするか、https://wowaudit.com/api を開いてチームを選択して取得できます。現在 WoWAudit は読み取り専用のスコープ付き公開 API キーを提供していません。このサーバーはデフォルトでローカルに読み取り専用アクセスを強制します。

Related MCP server: wow-mcp

セットアップ

npm install

.env.example から .env を作成し、次の項目を設定します:

WOWAUDIT_API_KEY=your-team-api-key

サーバーをビルドします:

npm run build

API キーは遅延読み込みされるため、MCP プロセスはキーが設定されていなくても起動し、ツール一覧を表示できます。API コールはキーが利用可能になるまで構造化エラーを返します。

MCP クライアントの設定

MCP クライアントからコンパイル済みのエントリポイントを使用します:

{
  "mcpServers": {
    "wowaudit": {
      "command": "node",
      "args": [
        "C:\\programming\\typescript\\wowaudit-mcp-server\\dist\\index.js"
      ]
    }
  }
}

サーバーは .env を自身のインストール場所からの相対パスで解決します。MCP クライアントの作業ディレクトリは参照しません。認証情報はクライアントの env 設定を通じて提供することも可能です。

セキュリティモデル

WoWAudit チーム API キーはチームの全環境にアクセスできます。サーバーは以下の保護策を適用します:

• キーは Authorization: Bearer ヘッダーでのみ送信されます。URL、結果、エラーに含まれることはありません。

• 文書化された /v1/ ルートのみが利用可能です。任意の HTTP ツールはありません。

• WOWAUDIT_ENABLE_WRITES=true が設定されていない限り、書き込みツールは公開されず、呼び出しもできません。HTTP クライアントは無効時に変更リクエストを独立してブロックします。

• 破壊的な削除ツールは、呼び出しごとに追加で confirm: true が必要です。

• アプリケーションツールは WOWAUDIT_ENABLE_APPLICATIONS=true が設定されていない限り無効です。アプリケーションには本人情報、アンケート回答、アップロードファイルの URL が含まれる可能性があるためです。

• ツールアノテーションは、読み取り専用、べき等、破壊的な操作を最新の MCP クライアントに識別させます。

• レスポンスはデフォルトで 2 MiB に制限されます。WOWAUDIT_MAX_RESPONSE_BYTES は必要な場合にのみ調整してください。

• GET レスポンスはプロセス内で 30 秒間キャッシュされます。書き込みが成功するとキャッシュがクリアされます。

アプリケーションツールを有効にしても、チャンネル認証は提供されません。Discord 連携は、それらのツールを公開する前に、役員専用アクセスを強制する必要があります。同様に、マルチギルドボットは、信頼できる Discord ギルド ID を、モデル制御のツール引数外で正しい WoWAudit 認証情報にバインドする必要があります。

設定

デフォルト設定では、11 の非機密 GET ツールが公開されます。WOWAUDIT_ENABLE_APPLICATIONS=true を設定すると、2 つの読み取り専用アプリケーションツールが追加されます。WOWAUDIT_ENABLE_WRITES=true を設定すると、変更ツールが追加されます。厳密に読み取り専用の MCP サーフェスが必要な場合は、この設定をオフのままにしてください。

ツール

以下に示す変更ツールは WOWAUDIT_ENABLE_WRITES=true の場合のみ登録されます。アプリケーションツールは WOWAUDIT_ENABLE_APPLICATIONS=true の場合のみ登録されます。

チームと名簿

アクティビティと出席状況

レイドと参加表明

wowaudit_update_raid はステータスとスケジュールの変更、エンカウンターの有効/無効リスト、参加表明ステータス、コメント、ロール/クラスオーバーライド、選択ステータス、エンカウンター固有の選択に対応しています。

ウィッシュリストと戦利品

全キャラクターのウィッシュリストと戦利品エンドポイントは大きくなる可能性があります。可能な限りキャラクター固有の呼び出しを優先し、コレクションツールでは limit を使用してください。

アプリケーション

アプリケーションは WOWAUDIT_ENABLE_APPLICATIONS=true によって別途制御されます。変更するにはさらに WOWAUDIT_ENABLE_WRITES=true が必要です。

結果のラッパー

成功したツールは次の形式を返します:

{
  "data": {},
  "meta": {
    "endpoint": "/v1/team",
    "method": "GET"
  }
}

limit を受け付けるコレクションツールは、追加で totalItems、returnedItems、truncated を報告します。制限は WoWAudit が応答した後に適用されます。公開 API がサーバーサイドのページネーションを文書化していないためです。

エラーは isError: true、構造化 {"error": "..."}、およびテキストフォールバックを返します。上流のエラーには、利用可能な場合に kind、HTTP status、retryAfterSeconds も含まれます。

開発

npm run dev
npm test

テストではサーバーをコンパイルし、最新およびレガシー両方のプロトコルネゴシエーションを検証し、すべてのツールスキーマとアノテーションを検査し、セキュリティゲートをテストし、実際の API キーを使用せずに HTTP クライアントをテストします。

小規模なライブ読み取り専用チェックの場合は:

npm run test:live

ライブスモークテストは、チーム、期間、名簿、レイド一覧のエンドポイントを呼び出します。アプリケーションツールや書き込みツールは呼び出しません。

WoWAudit API の注意点

• 公開ドキュメントにはページネーションやレート制限の契約は定義されていません。

• ドキュメントは主に厳密な再利用可能スキーマではなく応答例を提供しているため、ペイロードフィールドは変更される可能性があります。

• 埋め込みドキュメントには開発用と思われるサーバー URL が含まれています。このプロジェクトは、確認された本番オリジン https://api.wowaudit.com をデフォルトで使用します。

• WoWAudit はクエリパラメータでの API キーを受け入れますが、このサーバーは認証情報の漏洩を減らすために、認証ヘッダーのみを意図的に使用しています。

ライセンス

MIT、著作権 WoWAudit MCP Server コントリビューター。