helldivers2-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

A standalone MCP server that exposes live Helldivers 2 galactic war data to LLMs. It uses the stateless Streamable HTTP transport: each POST /mcp request spins up a fresh McpServer + transport pair, handles the request, and tears them down. There is no session state.

The upstream data source is the community API at https://api.helldivers2.dev. A GET /health endpoint is also served for liveness checks.

Development Commands

npm run dev              # tsx watch — hot reload
npm run build            # tsc → dist/
npm run start            # node dist/index.js (after build)
npm run lint             # eslint src
npm run test             # Jest (ESM mode via --experimental-vm-modules)
npm run test:watch
npm run test:coverage

Run a single test file:

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

Architecture

src/
  index.ts           — Express app, MCP server factory, request routing, origin guard, incoming rate limiter
  client.ts          — hd2Fetch(): in-memory cache + rate-limit queue over api.helldivers2.dev
  rate-limit.ts      — createRateLimiter(): token-bucket middleware for incoming /mcp requests (per-IP)
  reference-data.ts  — reads json/ files at startup, exposes lookup helpers
  format-planet.ts   — loadWarSnapshot() (fetches 3 endpoints in parallel), formatPlanetDetails(), formatActivePlanetSummary()
  tool-types.ts      — Tool / ToolDefinition / ToolResult / ToolHandler interfaces
  utils.ts           — textResponse(), errorResponse(), stripMarkup helpers, toRelativeTime()
  enums.ts           — game enum maps (Races, AssignmentTypes, difficulty levels, etc.)
  api-types.ts       — raw API response types (RawWarStatus, RawPlanetInfo, etc.)
  tools/
    war.ts           — get_war_status
    planets.ts       — get_all_planets, get_planet_details
    assignments.ts   — get_assignments
    news.ts          — get_dispatches, get_steam_news
    dss.ts           — get_space_station_details
json/                — static reference data files (planets, biomes, factions, effects, items…)