helldivers2-mcp

helldivers2-mcp

一个无状态的模型上下文协议（MCP）服务，可向大模型提供实时的 Helldivers 2 银河战争数据。

数据来自社区 API：api.helldivers2.dev。

软件包

Registry	Package
npm	helldivers2-mcp
Docker Hub	xerno42/helldivers2-mcp
GitHub Container Registry	ghcr.io/xerno42/helldivers2-mcp
MCP Registry	io.github.xerno42/helldivers2-mcp

---

工具

Tool	Description
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

---

配置

所有配置均通过环境变量进行。

Variable	Default	Description
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	持续请求速率限制（每分钟请求数）
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