HoYoLAB MCP

HoYoLABの公開記事・返信・HoYoWikiを検索し、AIが参照しやすいMDX風Markdownとして取得するMCPサーバーです。目次・階層・文書内検索・節やブロック・表の行範囲による部分取得に対応し、リビジョンを固定して続きを取得できます。

セットアップ

必要最低バージョンはNode.js 20です。運用には保守期限内のLTS（Node.js 22または24）を推奨します。対応状況はNode.jsのリリース情報を確認してください。MCPのAPI取得・変換にはブラウザのインストールやHoYoLABへのログインは不要です。

npm ci
cp -n hoyolab.config.example.yaml hoyolab.config.yaml
npm run --silent mcp:server

設定はhoyolab.config.yamlに記述します。設定例を初回にコピーし、既に設定ファイルがある場合はそのファイルを編集してください。ローカル設定はGitの対象外です。言語とゲームは各ツールの引数による指定が優先されます。

language: "ja-jp"
gameId: 2
api:
  timeoutMs: 30000
  minRequestIntervalMs: 1000
  concurrency: 1
  maxQueue: 24

この例では、APIの開始頻度を最大約1回/秒に抑えます。通常は作業ディレクトリのhoyolab.config.yamlを読み込み、別のファイルを使う場合は起動引数で指定します。

node scripts/mcp-server.mjs --config /path/to/hoyolab.config.yaml

APIアクセスの上限に達した要求は、空き枠や開始間隔を待ってから取得し、結果を返します。設定変更はサーバー再起動後に反映されます。既定値は従来どおりです。

コメントと部分的な設定を使用できます。未知のキー、不正な型・範囲、重複キー、複数のYAML文書、別名参照・未対応タグは起動時エラーにします。設定ファイルは64KiBまでです。明示したファイルがない場合もエラーにし、黙って既定値に戻しません。

設定ファイルがある場合は.envを読み込みません。優先順位は設定ファイルの指定値、既存の環境変数、組み込みの既定値の順です。既定の設定ファイルがない場合だけ、従来の.env読み込みを互換用に継続します。新規設定に.envは不要です。

間隔を長くする場合は、待機時間に合わせてタイムアウトも調整してください。記事・Wiki・検索・返信・再試行に同じAPIクライアントの制限を適用し、キャッシュだけで返せる取得は待たせません。複数プロセス間では制限を共有しません。

Related MCP server: SocialDataX 小红书 Xiaohongshu XHS RedNote MCP

MCPサーバー

MCPサーバーは、公開HoYoLAB APIを読み取り専用ツールとしてstdioで公開します。記事とWikiエントリの取得ツールは、contentに変換後のMDXを返し、構造化結果にも同じ本文をstructuredContent.mdxとして含めます。reply取得はcontentとstructuredContent.markdownにMarkdownを返し、structuredContent.repliesには返信単位の本文・投稿者・日時・親子関係を含めます。検索ツールは候補ID・タイトル・URLを軽量なMarkdownと構造化結果で返すため、検索後に記事またはWiki取得ツールを呼び出せます。

npm run --silent mcp:server

登録されるツール:

• search_hoyolab_posts — HoYoLAB記事検索

• search_hoyowiki — 記事・HoYoWikiエントリ検索

• read_hoyolab_article — 記事全文をMDXで取得

• read_hoyowiki_entry — Wikiエントリ全体を番号付きMDXで取得

• get_hoyowiki_hierarchy — 1.、1.1.、1.1.1. の番号付き階層とAPI上の場所を取得

• read_hoyowiki_module — module[1]やモジュール名を指定して、そのモジュールだけを番号付きMDXで取得

• read_hoyowiki_component — モジュールとcomponent[1]等を指定して、そのコンポーネントだけを番号付きMDXで取得

• read_hoyolab_replies — 記事返信をMarkdownで取得（構造化本文、絵文字、画像、sub-replies対応）

検索ツールでは、HoYoLABの検索画面と同じフィルターを指定できます。order_typeは0が通常順、2が新着順です。author_typeは0が全投稿者、1が公式アカウント、2が認証済みアカウントです。返却結果のstructuredContent.filtersにも適用した値と意味を含めます。

言語はja-jp、en-us、zh-cnなどの正式コードを指定できます。HoYoLABの言語カタログにあるJA／JP／ENなどの別名は正式コードへ正規化し、カタログ外の値はMCPエラーとして返します。多言語記事では、記事MDXのfrontmatterとstructuredContentに実際に返された言語、原言語、利用可能言語を記録します。

Wikiの階層番号は1始まりで、表示とAPI指定場所を対応させています。例えば1.2.は1番目のModuleに属する2番目のComponentで、場所はmodule[1].component[2]です。module[...]とmodule[...].component[...]は階層取得結果から直接取得ツールへ渡せます。番号は文書の版に依存するため、階層取得結果のrevisionを直接取得へ引き継ぐと同じ文書を参照できます。個別項目の取得には、目次に返されたsection_idを使用します。

記事とWikiの取得ツールはview: "outline"で目次、view: "search"とqueryで文書内検索を返します。節・ブロック・表の行範囲を選択でき、出力上限に達した場合はcontinuationに次の呼び出し引数を返します。要求言語と実際の言語、変換上の警告、取得範囲を別々に記録します。実際の言語がAPIで未報告の場合は推測せずlanguage_status: "unknown"とします。

仕様・呼び出し例・取得状態とエラーの意味は文書アクセスの使い方を参照してください。

MCPクライアント設定例（/path/to/hoyolab-mcpは実際のインストール先に置き換えてください）:

{
  "mcpServers": {
    "hoyolab": {
      "command": "node",
      "args": ["/path/to/hoyolab-mcp/scripts/mcp-server.mjs"],
      "cwd": "/path/to/hoyolab-mcp"
    }
  }
}

動作確認

API通信を伴わない回帰テスト:

npm test

SDKクライアント経由で、ツール一覧・検索・記事MDX・Wiki MDX・階層・Module/Component直接取得・返信取得を実APIに対して確認するには次を実行します。

npm run mcp:check

崩壊：スターレイルとゼンレスゾーンゼロを含む複数ゲームの全ツールを実APIで確認するには次を実行します。

npm run mcp:check:games

3タイトルで、多言語と通常の記事、Wikiの全モジュール／コンポーネント、検索フィルター、返信のカーソルと分割取得を確認するには次を実行します。

npm run mcp:check:regressions

キャラクター以外の装備・素材・敵・ボンプなどのWikiと、検索から選んだ新しい記事を使って、元データの文章、部分取得、表の行選択、継続取得を照合する場合:

npm run mcp:check:corpus

大きな表などは指定予算に収まらないことがあるため、BUDGET_TOO_SMALLを確認してから予算を拡大します。上流APIに本文がない場合はEMPTY_BODYを報告します。テストの成功はすべての投稿や今後のAPI変更への対応を保証するものではありません。

返信の次ページは、返されたnext_pageをカーソルlast_idごと同じツールへ渡してください。pageの番号だけではAPIのページは進みません。continuationがある場合は現在のページを先に読み終えます。

コントリビュート

Issue / Pull Request を歓迎します。PR には以下を含めてください。

• 変更目的

• 実装内容の要約

• 再現手順または確認手順

生成AIによる開発支援の表記

• 使用した生成AIモデル: GPT‑5.6 Luna

  • 活用範囲: HoYoLAB API仕様の調査、実装方針の検討、コードの作成・修正、テストの設計・検証、ドキュメントの作成

ライセンス

本プロジェクトは GNU AGPL v3以降 の条件で提供されます。