HoYoLAB MCP server

HoYoLABの公開APIを読み取り専用のMCPツールとして提供します。記事本文とHoYoWikiの内容を、AIが扱いやすいMDX風Markdownへ変換します。

セットアップ

npm install
npm test

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

MCPサーバー

stdio MCPサーバーとして起動します。

npm run mcp:server

MCPクライアント設定例（/path/to/HoYoLAB-MCPは実際の配置先へ置き換えてください）:

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

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

ツール

• 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が認証済みアカウントです。author_type=3（フォロー中のアカウント）は匿名公開検索では利用できないため、MCPの入力スキーマには公開していません。返却結果のstructuredContent.filtersにも適用した値と意味を含めます。

言語と多言語記事

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

Wikiの階層指定

Wikiの階層番号は1始まりで、表示とAPI指定場所を対応させています。例えば1.2.は1番目のModuleに属する2番目のComponentで、場所はmodule[1].component[2]です。module[...]とmodule[...].component[...]は階層取得結果から直接取得ツールへ渡せます。item[...]はComponent内の項目位置を示す情報で、取得時は親Componentを指定します。

動作確認

ローカルのモックテスト:

npm test

公開APIを使ったMCP疎通確認:

npm run mcp:check

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

npm run mcp:check:games

コントリビュート

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

• 変更目的

• 実装内容の要約

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

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

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

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

ライセンス

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