ulicraft-server-v1/plan/15-mc-status.md

15 — mc-status (self-hosted live server card backend)

Self-hosted Minecraft Server List Ping → JSON service that feeds the landing's live ServerCard. Replaces the third-party api.mcstatus.io dependency.

Why not just use api.mcstatus.io

The public API works (CORS *, no key), but mcstatus.io's API service is not open source — only its underlying Go library, mcutil, is. To self-host we run the same library behind our own thin HTTP shell that re-emits mcstatus.io's v2 JSON shape, so the frontend (ServerCard.astro) stays byte-identical — only the URL changes. itzg/mc-status is deprecated; mc-monitor only exports Prometheus metrics (no icon/MOTD/player sample), so neither fits the card.

Service

docker/mc-status/ — Go, built from source (multi-stage → scratch), image ulicraft/mc-status:local. Wraps github.com/mcstatus-io/mcutil/v4 status.Modern() and maps StatusModern → v2 JSON:

mcutil field	v2 field ServerCard reads
Players.Online/Max	players.online / players.max
Players.Sample[].ID	players.list[].uuid
Players.Sample[].Name (formatting.Result)	players.list[].name_raw/clean/html
MOTD (formatting.Result)	motd.raw/clean/html
Favicon (data:image/png;base64,…)	icon

On any ping failure it returns {"online": false} so the card shows an offline state without erroring.

Hardening

• No open SSRF relay. The <addr> segment in /v2/status/java/<addr> is ignored — the service only ever pings MC_STATUS_TARGET. The segment exists only to keep the URL drop-in compatible with the public API.
• TTL cache (MC_STATUS_CACHE_TTL, default 30s) so a busy landing page can't ping the Minecraft server once per visitor.

Env

Var	Default	Notes
MC_STATUS_TARGET	minecraft:25565	pinged internally over mcnet
MC_STATUS_CACHE_TTL	30s	in-memory cache window
MC_STATUS_LISTEN	:8080	bind address

Ingress

Path-on-apex (no new DNS subdomain, no Let's Encrypt cert change — DNS/TLS are managed outside this repo). caddy/conf.d/10-static.caddy:

handle /api/mcstatus/* {
	uri strip_prefix /api/mcstatus
	reverse_proxy mc-status:8080
}

Same-origin → the ServerCard fetch needs no CORS. site.ts: statusApi: \/api/mcstatus/v2/status/java/${BASE_DOMAIN}``.

Data flow

guest browser ─ GET /api/mcstatus/v2/status/java/${BASE_DOMAIN}
   └► caddy (apex) ─ strip_prefix /api/mcstatus ─► mc-status:8080
        └► mcutil SLP ping ─► minecraft:25565 (internal, mcnet)
   ◄── v2 JSON {online, players.list[uuid,name_*], motd.html, icon}
ServerCard → player heads via NMSR: avatar.${BASE_DOMAIN}/headiso/<uuid>?size=64

Relationship to Uptime Kuma (plan/10)

Distinct roles. Kuma = uptime history + alerting backend (Minecraft Server monitor, status page). mc-status = live, public-facing data for the landing card (richer: icon/MOTD/player heads). Both ping minecraft over mcnet.

Validation notes

Built + go vet/gofmt clean. The live ping path can't be exercised from the dev sandbox (egress proxy allows TCP connect but filters the raw SLP handshake → context deadline exceeded); it resolves on the prod host where minecraft is reachable over mcnet. After deploy, confirm:

curl -s https://${BASE_DOMAIN}/api/mcstatus/v2/status/java/${BASE_DOMAIN} | jq .

expecting online:true, a populated players.list, and motd.html.

Tasks

• docker compose up -d --build mc-status on prod, verify the curl above.
• Confirm the SLP player sample carries real (Drasl) UUIDs so NMSR heads render; if empty, the card falls back to the count-only / empty state.