np-mcp

MCP server that exposes your Neptune's Pride games as tools, so an AI agent (e.g. a Hermes Agent on a 10-minute cron) can read game state and alert you over Telegram when something needs attention: incoming attacks, stars lost, research finished, production cycles, low cash, diplomacy changes, new messages, turn deadlines.

Sibling of np-reminder (which only emails before deadlines); this exposes everything the API knows, plus a change-detection tool.

Quick start

cp config.example.yaml config.yaml   # add each game's game_number + API code
cp .env.example .env                 # host/port; NP creds only for messages

make test                            # run the test suite
make run                             # serve http://127.0.0.1:8721/mcp (foreground)

Long-term, run it under systemd:

make service-install     # install + enable + start (sudo)
make service-status
make service-logs
make smoke               # call the running server once via MCP (peek mode)

• game_number is in the game URL: https://np.ironhelmet.com/game/<game_number>.

• code is the read-only API key from the game menu → API Key.

• NP_EMAIL/NP_PASSWORD (optional, .env) enable the get_messages tool and new_message events. They use the unofficial login API (the read-only key cannot see your inbox); everything else works without them.

Tools

game accepts a label or game number; empty selects the first configured game. All tools are read-only with respect to the game (the API key cannot issue orders).

check_events

The alerting workhorse. Keeps a summary snapshot in data/state.json and returns only what changed since the previous call:

incoming_attack, star_lost, star_captured, research_complete, production_occurred, low_cash, war_declared, relation_changed, player_conceded, player_eliminated, new_message, turn_deadline_soon, plus a one-time baseline on first run.

Every event has a stable id for dedup. Reading consumes events (the snapshot is saved) unless you pass peek=true — so point exactly one cron at it and use peek for manual poking (make smoke does this).

Wiring up Hermes

Point your Hermes Agent's MCP client at http://<host>:8721/mcp (streamable HTTP, stateless). Suggested 10-minute cron prompt:

Call check_events for each game returned by list_games. If any events come back, send me a Telegram message summarizing them in one or two sentences each, most urgent first. For incoming_attack events, call get_threats and include attacker strength vs defending ships. If there are no events, do nothing and send nothing.

If Hermes runs on another machine, set NP_MCP_HOST=0.0.0.0 in .env and firewall the port appropriately (the server has no auth of its own).

Notes & caveats

• Field semantics (tech kind ids, research cost = level * cost, fleet order arrays [delay, target_star, action, ships]) were cross-checked against the open-source Neptune's Pride Agent (anicolao/npa). Tech kinds: 0 banking, 1 experimentation, 2 manufacturing, 3 range, 4 scanning, 5 weapons, 6 terraforming. (Kind 3 is "propulsion" in the raw NP4 data; exposed here as "range", the player-facing name for hyperspace range.)

• war relation labels are best-effort (0 = war, 3 = peace/default); the raw value is always included, and any change fires an event regardless.

• Threats only include fleets inside your scan range — a fleet can "appear" with a short ETA when it enters scan. That's the game, not a bug.

• The messages endpoints are undocumented and may break; tools report an error field instead of crashing, and check_events keeps working. The current flow (verified live, cross-checked with anicolao/aib): POST /account_api/login (form: type, alias, password) then POST /game_api/fetch_game_messages (form: type, gameId, group, count, offset, version=np4) with the session cookie. The events group returns templated payloads (war_declared, peace_requested, ...) with player uids, which the server enriches with aliases.

Tests

make test

Covers threat detection/ETA math, research ETA, production timing, the event diff engine (one test per event type, dedup, JSON round-trip), and sanity checks against a captured live scanning_data fixture.

References

• https://github.com/anicolao/npa was heavily referenced for NP4 API discovery and manipulation

License

MIT — do whatever you like, just keep the copyright notice.

Unofficial. Not affiliated with or endorsed by Ironhelmet/Neptune's Pride; "Neptune's Pride" is their trademark. This project uses the game's read-only API key plus an undocumented login endpoint, either of which may change or break without notice.