helldivers2-mcp

helldivers2-mcp

LLM に Helldivers 2 の銀河規模戦争に関するライブデータを提供する、ステートレスな Model Context Protocol（MCP）サーバーです。

データは、コミュニティ API の api.helldivers2.dev から取得します。

パッケージ

レジストリ	パッケージ
npm	helldivers2-mcp
Docker Hub	xerno42/helldivers2-mcp
GitHub Container Registry	ghcr.io/xerno42/helldivers2-mcp
MCP Registry	io.github.xerno42/helldivers2-mcp

---

ツール

ツール	説明
get_war_status	銀河全体の戦争統計（陣営別撃破数、ミッションの勝敗、命中率、死亡数、影響倍率）と、所有者、プレイヤー数、進行中のイベント、攻撃経路、地域の耐久度を含む活動中の惑星
get_assignments	タイトル、ブリーフィング、デコード済みタスクリスト（陣営、難易度、目標惑星）、現在の進捗数、報酬の種類と量、有効期限までの時間を含む進行中の大規模作戦
get_all_planets	ID、名前、セクターを含む全惑星のリスト
get_planet_details	惑星ごとの詳細情報：バイオーム、危険要因、初期／現在の所有者、耐久度、ウェイポイント、進行中のイベント、全戦闘統計、攻撃中の惑星、地域（呼び出しあたり最大 5 惑星）
get_dispatches	ゲーム内の配信フィード — 公開日（相対時間）とメッセージ本文を含む最高司令部からのブロードキャスト。limit パラメーターは任意（デフォルト 20、最大 50）
get_steam_news	Helldivers 2 の Steam ニュース。タイトル、URL、公開日（相対時間）、記事全文を含みます。limit パラメーターは任意（デフォルト 10、最大 30）
get_space_station_details	DSS の詳細：現在の母星（惑星の全情報）、次回選挙までの時間、名前、説明、ステータス、惑星への効果、リソースコストを含む実行中の戦術行動

---

クイックスタート

前提条件

• Node.js 22+ または Docker
• X-Super-Contact ヘッダー用の連絡先メールアドレス（上流 API が必須としています）

ローカル開発

cp .env.example .env   # set [email protected]
npm install
npm run dev               # hot-reload via tsx watch on :3000

本番ビルド

npm run build   # tsc → dist/
npm run start

Docker

イメージは Docker Hub および GitHub Container Registry で利用できます。

docker pull xerno42/helldivers2-mcp        # pull from Docker Hub
# or
docker pull ghcr.io/xerno42/helldivers2-mcp # pull from GHCR
# or
docker build -t helldivers2-mcp . # build locally

#then run with:
docker run -p 3000:3000 -e [email protected] helldivers2-mcp

---

設定

すべての設定は環境変数で行います。

変数	デフォルト	説明
X_SUPER_CONTACT	(必須)	利用ガイドラインに従い、上流 API に X-Super-Contact として転送されます
PORT	3000	リッスンする HTTP ポート
BIND_HOST	127.0.0.1	バインドするインターフェース（Docker／コンテナーでは 0.0.0.0）
MCP_ALLOWED_ORIGINS	(未設定)	許可するブラウザーの Origin ヘッダーをカンマ区切りで指定します。未設定の場合、ブラウザーからのリクエストはブロックされます。サーバー間の呼び出し（Origin ヘッダーなし）は常に許可されます
MCP_RATE_LIMIT_PER_MIN	60	継続的なリクエストレート制限（1 分あたりのリクエスト数）
MCP_RATE_LIMIT_BURST	= MCP_RATE_LIMIT_PER_MIN	トークンバケット方式のレートリミッターのバースト容量

---

エンドポイント

メソッド	パス	説明
POST	/mcp	MCP Streamable HTTP トランスポートのエンドポイント
GET	/health	稼働確認 — { "ok": true } を返します

サーバーはステートレスな Streamable HTTP トランスポートを使用します。各 POST /mcp リクエストで新しい McpServer とトランスポートのペアを作成し、リクエストを処理した後に破棄します。セッション状態はありません。

---

コードでの使用方法

Streamable HTTP トランスポートを使用して、HTTP 経由で MCP サーバーを直接呼び出します。各リクエストは、POST /mcp に送信する JSON-RPC の tools/call メッセージです。

JavaScript / TypeScript

公式の MCP TypeScript SDK を使用する場合：

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-app", version: "1.0.0" });

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.avengersofsuperearth.com/mcp")
);

await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log(tools.map((t) => t.name));

// Get current war status
const warStatus = await client.callTool({
  name: "get_war_status",
  arguments: {},
});
console.log(warStatus.content[0].text);

// Get details for specific planets by index (up to 5)
const planets = await client.callTool({
  name: "get_planet_details",
  arguments: { planetindices: [57, 153] },
});
console.log(planets.content[0].text);

await client.close();

SDK を使用せず、fetch で生の JSON-RPC を送信する場合：

async function callTool(name: string, args: Record<string, unknown> = {}) {
  const res = await fetch("https://mcp.avengersofsuperearth.com/mcp", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Accept": "application/json, text/event-stream",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: 1,
      method: "tools/call",
      params: { name, arguments: args },
    }),
  });
  const text = await res.text();
  // The response is an SSE frame ("event: message\ndata: {json}\n\n");
  // concatenate its data line(s) to recover the JSON-RPC payload.
  const json = text
    .split("\n")
    .filter((line) => line.startsWith("data:"))
    .map((line) => line.slice(5).trim())
    .join("");
  const data = JSON.parse(json);
  return data.result.content[0].text;
}

const status = await callTool("get_war_status");
const assignments = await callTool("get_assignments");
const dispatches = await callTool("get_dispatches", { limit: 5 });
const planets = await callTool("get_planet_details", { planetindices: [57, 153] });

Python

公式の MCP Python SDK を使用する場合：

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("https://mcp.avengersofsuperearth.com/mcp") as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            # Get current war status
            result = await session.call_tool("get_war_status", {})
            print(result.content[0].text)

            # Get details for specific planets by index (up to 5)
            result = await session.call_tool(
                "get_planet_details",
                {"planetindices": [57, 153]},
            )
            print(result.content[0].text)

asyncio.run(main())

SDK を使用せず、httpx で生の JSON-RPC を送信する場合：

import httpx

MCP_URL = "https://mcp.avengersofsuperearth.com/mcp"

def call_tool(name: str, arguments: dict = {}) -> str:
    payload = {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {"name": name, "arguments": arguments},
    }
    headers = {
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
    }
    response = httpx.post(MCP_URL, json=payload, headers=headers)
    response.raise_for_status()
    import json
    # The response is an SSE frame ("event: message\ndata: {json}\n\n");
    # concatenate its data line(s) to recover the JSON-RPC payload.
    text = "".join(
        line[5:].strip()
        for line in response.text.splitlines()
        if line.startswith("data:")
    )
    return json.loads(text)["result"]["content"][0]["text"]

status = call_tool("get_war_status")
assignments = call_tool("get_assignments")
planets = call_tool("get_planet_details", {"planetindices": [57, 153]})

---

Claude Desktop への接続

ホスト型サーバー（最も簡単）

公開インスタンスを https://mcp.avengersofsuperearth.com/mcp で利用できます。セットアップは不要です。claude_desktop_config.json に追加するだけです。

{
  "mcpServers": {
    "helldivers2": {
      "url": "https://mcp.avengersofsuperearth.com/mcp"
    }
  }
}

セルフホスト（ローカルバイナリ）

{
  "mcpServers": {
    "helldivers2": {
      "command": "node",
      "args": ["/path/to/helldivers2-mcp/dist/index.js"],
      "env": {
        "X_SUPER_CONTACT": "[email protected]"
      }
    }
  }
}

セルフホスト（HTTP サーバー）

{
  "mcpServers": {
    "helldivers2": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

---

開発

npm run test              # Jest (ESM mode)
npm run test:watch
npm run test:coverage
npm run lint              # ESLint

単一のテストファイルを実行します：

npm run test src/__tests__/tools.war.test.ts

ツールの追加

1. src/tools/your-tool.ts を作成し、.definition と .handler を含む Tool オブジェクトをエクスポートします。
2. src/index.ts でインポートし、TOOLS 配列に追加します。
3. 成功時は textResponse(...) を、失敗時は errorResponse(...) を返します。ハンドラーから例外をスローしないでください。
4. 上流へのすべての呼び出しは hd2Fetch（メモリ内の2分間キャッシュと、レート制限を考慮したキュー）を経由する必要があります。

---

ライセンス

MIT