
warapp-mcp
io.github.chrischall/warapp-mcp
war.app (Warzone) game advisor — games, maps, bonuses, routes, live board, picks, turns and chat
Documentation
warapp-mcp
war.app (Warzone) game advisor MCP server for Claude. It reads your games through war.app's per-player GameFeed API and helps you think about them: players and settings, the map's bonuses and chokepoints, the board, and routes between territories. Through your signed-in war.app browser tab it also lists your games (the ones waiting on you first), scouts an opponent (their record and your head-to-head), reads the live board (including the pick phase, where GameFeed has none), your territory picks and your cards, plans your turn, tells you when a game is waiting on you (war.app's push notifications), and — only after you confirm — submits picks, commits your turn's orders (card plays included) and posts game chat.
This project was developed and is maintained by AI (Claude Code). Use at your own discretion.
Setup
-
Sign in to war.app in a browser and open https://war.app/API/GetAPIToken to see your API token. Changing your war.app password rotates it.
-
Add the server to your MCP client:
{ "mcpServers": { "warapp": { "command": "npx", "args": ["-y", "@chrischall/warapp-mcp"], "env": { "WARAPP_EMAIL": "you@example.com", "WARAPP_API_TOKEN": "<your token>" } } } } -
Call
warapp_healthcheckto confirm war.app accepts the credentials. -
For the live-game tools, set up the browser bridge (below).
| Variable | Required | |
|---|---|---|
WARAPP_EMAIL | yes | The email address you sign in to war.app with. |
WARAPP_API_TOKEN | yes | Your API token from https://war.app/API/GetAPIToken. |
WARAPP_ENV_FILE | no | A dotenv file to read the two above from (default ~/.config/warapp-mcp/.env). Values already in the environment win. |
WARAPP_WS_PORT | no | The fetchproxy bridge port (default 37149, shared by the whole fetchproxy fleet and ContextMint Bridge). Override it only for local testing, or when a host injects a per-registration port. |
WARAPP_TRANSPORT | no | How the live-game tools reach war.app: auto (default — try the chrome-less direct transport when a session is linked, else the browser bridge), direct (only direct), or fetchproxy (only the browser bridge, today's behaviour). See Direct transport. |
WARAPP_SESSION_FILE | no | Where the linked direct-transport session is stored (default <data dir>/session.json). Local-only; a full-account credential, kept at file mode 0600. Its directory is made 0700, so name a file in a directory of its own. |
WARAPP_AUTH_TOKEN | no | Hosted only, set by mcp-host: the war.app session cookie its sign-in captured (a full-account credential, held in memory, never stored or shown). Ignored on a local install. See Direct transport. |
WARAPP_STATS | no | 1 turns on warapp_map_stats on a local install (off by default; always off when hosted). It then fetches finished ladder games — at most max_new_games a call, one request a second — and caches them under <data dir>/stats/. |
WARAPP_PLAYER_PROFILE | no | Opponent profiling (on by default, locally and hosted; off turns it off): what each opponent did on the turns your boards showed, as counts (gameplay only — no name, chat or time of play), kept per game under <data dir>/profiles/games/ for warapp_profile_opponents, and folded when a game finishes into name-free cross-game counts (profiles/players.json, keyed by a salted hash shared with the player record; profiles/population.json, pooled by format and for AI seats) that fade per game. It also switches off the end-of-game pass (#312): once per finished game you played, its history read once and kept name-free at <data dir>/finished/<hash>.json (its boards included, owners by the same salted hash, no clock; at most 500), then folded into the profiles, into a per-map record (<data dir>/maps-record/<mapId>.json: outcomes, your start and income curve, the winner's start and pace after turns 4 and 8) and into the lessons (<data dir>/lessons.json: how each game was lost, when your income went flat, and the tracked estimates against the true incomes, aggregates only). |
WARAPP_DEBUG | no | Truthy logs the bridge's role and lifecycle to stderr. |
MCP_DATA_DIR | no | Where this server keeps its local state (default ~/.config/warapp-mcp): the downloaded war.app client bundle (bundle/), GameFeed maps (maps/), each planned game's name-free settings (games/), the board history (boards/) and the rest of its per-game records. A host with persistent state sets it. |
MCP_CONFIRM_MODE | no | What a write does on a client that cannot show a confirmation prompt: ask-user (default), auto or refuse. See Confirming writes. |
The server starts without credentials and reports what is missing on the first call that needs them.
The browser bridge (live-game tools)
GameFeed has no list of your games, no player profiles, no live board during the pick phase,
no picks and no way to post chat. Those come from war.app's own web client (its protocol and
its profile pages), which is authenticated by your browser's war.app session rather than by
the API token. So the live-game tools — warapp_my_games, warapp_scout_player,
warapp_get_live_board, warapp_get_my_picks, warapp_plan_picks, warapp_submit_picks, warapp_plan_turn, warapp_check_plan,
warapp_track_opponents, warapp_locate_opponents, warapp_profile_opponents, warapp_get_team, warapp_team_brief, warapp_submit_turn, warapp_uncommit_turn, warapp_leave_game, warapp_send_chat, warapp_wait_for_turn, and warapp_analyze_board
when GameFeed sends no board — relay each request through your signed-in war.app tab with the fetchproxy bridge.
They need:
- the ContextMint Bridge browser extension, and
- a war.app tab in that browser, signed in to the same account as
WARAPP_EMAIL.
The server never sees your war.app password or session cookies; the tab makes the request
and hands back the answer. The tools decode the board with war.app's own client code: the
first live call downloads the current client bundle (ujs.js) from War.app's CDN and caches
it per version under the data directory. Nothing from war.app is shipped in this package.
Pairing (once)
- Install ContextMint Bridge and sign in to https://war.app in that browser.
- Ask Claude for something live, e.g. "show me the live board of game 12345678". The first call that needs the bridge answers with a pair code.
- Approve that code in the ContextMint Bridge popup. The trust persists across restarts in
~/.fetchproxy/identity/. After that,warapp_healthcheckreports the bridge's status too.
More than one browser? Approve the code in the browser that holds your war.app session.
Paired the wrong one? Revoke warapp-mcp in the ContextMint Bridge popup, run
fpx trust clear warapp-mcp (from @fetchproxy/cli),
restart the server and pair again.
Direct transport (no browser)
By default the live-game tools relay every request through your signed-in war.app tab. You can instead let them talk to war.app directly, with no browser involved, by linking your session once:
- Call
warapp_link_session(confirm-gated). With a signed-in war.app tab paired to the bridge, it captures your war.app session cookie once and stores it on this machine only (<data dir>/session.json, file mode0600;WARAPP_SESSION_FILEoverrides the path). - After that, with
WARAPP_TRANSPORT=auto(the default), every live call is a plain server-side HTTPS request carrying that session — no Chrome tab needed, including the turn-notification socket. If the session expires, the tools automatically fall back to the browser bridge for the rest of the session andwarapp_session_statustells you to runwarapp_link_sessionagain.
warapp_session_status reports whether a session is linked, how old it is, and which transport is
active. warapp_healthcheck reports the same.
Security. The stored session cookie is a full-account credential — anything your war.app account can do, it can do. It never leaves this machine (it is sent only to war.app), is never logged, and is never shown in a tool result. Use direct mode only on a machine you control;
rmthe session file (or let it expire) to unlink.
Hosted (mcp-host). A hosted server never stores a session file and never offers
warapp_link_session. It rides the direct transport only when mcp-host signed it in to war.app:
the host captures war.app's session cookie into the per-user secret WARAPP_AUTH_TOKEN (your
war.app password is asked once at sign-in and never stored), and the server holds it in memory,
falling back to the browser bridge if it stops working. warapp_session_status then reports
linked: true with linkedBy: "host" (no capture time or age), and a signed-out session says to use
Sign in on the connection, or to reconnect it; a paired war.app tab works meanwhile. Without that token the hosted
server uses the browser bridge, as before. (The war.app sign-in mcp-host runs is
docs/examples/warapp-auth-flow.json, one password page; its capture calls warapp_sign_in, a hosted-only tool that
signs in to war.app once and returns the session cookie to the host. mint.yaml declares it as auth.flow; a
registration that does not carry it uses the browser bridge.) The trade-off: once a registration carries the
flow, every new connection needs one successful war.app password sign-in. Any failed sign-in, not only a wrong
password (a captcha, a war.app outage, a network fault), ends the login with no connection, and may clear the fields
already entered; an account that signs in through Facebook, with no war.app password, cannot connect. The browser
bridge stays the fallback only for a connection made before the flow was added and for a session that expires later.
Locally WARAPP_AUTH_TOKEN is ignored.
Tools
| Tool | |
|---|---|
warapp_healthcheck | Check that war.app accepts your email and API token; report the active transport and whether a direct session is linked. |
warapp_my_games | Your games (through your signed-in tab), games waiting on you first: state, turn, players and who has committed, and waitingOnYou; surrenderPending per game (another player's surrender still pending, owedByMe true when it waits on your acceptance; read from the game details, unverified live; null when not read, never "none") and as a top-level count of games where one waits on you, which come first too (compact only). Finished games only with include_finished; listed (games war.app returned) and complete (false, with a warning, when the list may be partial). Each call also runs the end-of-game pass (as warapp_get_game does) on up to two of your finished games not yet processed, newest first, among your newest 250 finished games (endOfGame: processed, pending). view: compact / brief. |
warapp_list_open_games | Open games you could join, from war.app's Open Games page: pace, boot time, seats, team or not, entry fee, cards, rules (One Army Must Stand Guard on or off among them), plannerGaps (rules the planner does not model yet; a guard-off game is not one: the planner keeps a second line, raids and retakes with the guard off, a raid or retake sized for its owner's deploy there), joined: true on games you already hold a seat in, lottery (from the data, never the name: true for a map of at most four territories — its size read from GameFeed only for lobbies with base income 0 and overridden bonuses, at most five a call, or from a map already cached — null for that settings shape with the map size unread; lotteryBasis says which), and policyBreaks: the joining-policy rules a game breaks (Commerce, mods, custom scenarios, more than four seats, a boot time under 12 hours, a lottery (a likely one too); advisory). Filters: pace, max_players, free_only, exclude_teams, limit. A page GET, so it works without a browser once a session is linked. |
warapp_join_game | Writes. Take an open seat in a game from the open games list. Confirm-gated; refuses team games and coin entry fees unless allowed (allow_team, accept_entry_fee; team picks a team by number and implies allow_team — refused when that team is full or not offered, with random teams, and outside a team game; the preview's team lists the teams offered and the seats on the chosen one by in-game id, human or ai; the team is sent as the chosen open seat's team, read from the client bundle and unverified live), and custom-scenario and mod games and games you already joined always. Joins with your preferred colour, else your secondary, else a free standard colour (or color, a war.app colour index). The preview adds a screen from the lobby's GameFeed settings — does the cheapest neutral cost at most one turn of base income — and flags Light Fog and costly neutrals in plannerGaps, plus lottery and policy: whether the lobby keeps the joining policy (the rules above plus that neutral cost and no lottery; advisory, never a refusal). Reports joined only once GameFeed or your games list shows you in the game. |
warapp_leave_game | Writes. Leave a game that has not started — a lobby still WaitingForPlayers — giving up your seat (war.app's DeclineGame, the lobby's Decline button; verified live for a lobby joined through an open seat). Confirm-gated; refuses a game that has started (surrender it instead), a lobby you hold no seat in, and mod games. The preview warns that the seat is given up (you can only come back through a seat still open) and that war.app may remove your chat in the game. Reports left only once GameFeed (or your games list) no longer shows you seated — unconfirmed otherwise, unknown when war.app did not answer (never resent). |
warapp_surrender | Writes. Surrender a game you are playing — you lose it and cannot rejoin — or, with undo: true, take back a pending surrender. Confirm-gated; refuses finished games and games you are not in; reads the outcome from GameFeed: surrendered, pending (more than two players: the others must accept), still_playing (after undo: GameFeed shows no pending surrender, so a take-back cannot be confirmed) or unchanged. Lobbies are refused too. |
warapp_accept_surrender | Writes. Accept another player's pending surrender (where the game asks the others to accept one). Confirm-gated; refuses when no surrender is pending from that player, when your acceptance is not owed, finished games and games you are not playing. player names the surrendering player (optional with one pending). The preview says what accepting does: whose seat, whether its land turns neutral or goes to an AI, which players border that land (live board), whether others still owe their acceptance, whether it leaves only your side playing (a win), and in a free-for-all one advice line naming the neighbour that gains most. Reads the outcome back from GameFeed and the game details: accepted, pending (others still owe theirs), unconfirmed or unknown (never resent). The encoding is read from the war.app client, not yet verified live. |
warapp_begin_turn | Writes. Press Begin in a game whose first turn is a speed race (move order "No-luck cycle"): war.app hides the board until Begin, and Begin starts your turn timer, so call it only when ready to plan and submit at once. Confirm-gated; refuses games past turn 1, games without the speed first turn and games whose board is already visible; reports begun once the board reads back. The encoding is read from the war.app client, not yet verified live. |
warapp_scout_player | Scout a player (through your signed-in tab): level, games played, last seen, boots, ranked records per format, and your head-to-head record; met (when the opponent-profile record holds the player) gives the earlier finished games of yours they were in and the read from them — each habit with value, n, confidence and basis, and the labels. Never returns location or other personal details. |
warapp_get_game | A game's state, turn, players (and who has committed orders), settings digest and map. A game you lost says how (howLost), once finished or while the others play on once your seat is out (#283): a surrender or boot (with the last turn played here and the last logged outlook: its state, your income and armies against the strongest opponent's in view), or from the boards cached while you played, the turn you were eliminated on and the cause — your commander's territory that fell (what it held, the attackers that needed, who bordered it; read at the destination, flagged uncertain, when your orders walked the commander that turn) or your last territories. Kept name-free in the outlook log. With include_history it says whether the game's history read (historyRead: boards, first and last turn, layout) or why not (historyUnreadable: the reason and the reply's top-level key names, never values). A finished game you played gets its end-of-game pass once (endOfGame, #312): its history read once from GameFeed (one more request) and kept name-free under <data dir>/finished/ for later games — the outcome and its turn, your picks and the award, the final outlook line when this server planned the game (state, turn, ratio, estimated or thin; no id or words), every player's income and bonuses by turn, and what stood on each target your attacks failed to take — then folded into the opponent profiles, the map's record and the lessons (endOfGame.processed); a failed read is recorded (read-failed / history-unreadable with its reason) and not retried, except by a call with include_history, which re-runs it from that read; a read whose record could not be written is not repeated while the server runs (attempted). With WARAPP_PLAYER_PROFILE=off the pass makes no request at all. Not yet a trigger: war.app's game-ended in-app notification (#311). view: compact / full / raw. |
warapp_get_map | The game map's bonuses ranked easiest first, plus chokepoints. Filter by bonus name to see one bonus's territories, borders and entry points. View full also lists each distribution mode with the territories a player may start on (read once from war.app's map details through the web-client channel (direct or bridge) and kept with the map; null when unknown). |
warapp_map_stats | Opt-in, local only. What has worked on a map, from finished ladder games: the most-picked starting territories, the win rate by every bonus a player started in, the turn of each player's first bonus completion and the sample size (a sample under 5 games and a bonus rate under 10 players are flagged; games whose history could not be read are counted apart, not cached, and collected.unreadableGames lists up to 10 of them with why, by key name). Off unless WARAPP_STATS=1, always off when hosted. Each call reads the ladder's game-ID feed (ladder_id, default 0 = 1v1) and fetches up to max_new_games new games (default 10, max 50) at one request a second; finished games are cached forever under <dataDir>/stats/<mapId>/. myGames adds your own finished games on the map (from their histories, no request): your results by start bonus, where winners started, and the median income after turns 4 and 8. |
warapp_analyze_board | Advice for one player from the current board: income, the bonuses closest to completion with armies needed, and visible threats. Needs a board; lobbies have none. The board parser is unverified, so the advice states its assumptions. |
warapp_strategy | Strategy notes in our own words, each with its community-guide or wiki source and topic (format, settings, cards, reading the game, opening, timing, fighting, diplomacy, map). With game_id, the notes that fit the game (format, phase — from your seat on the live board when the signed-in account plays in it, else GameFeed, profile.source live or gamefeed, and profile.liveError the short reason when the live board was tried and did not read, with the frozen-tab hint on a bridge timeout — fog level, move order, distribution, kill rates, the cards in play, private messaging), its cardClock (per card, the first turn it can be played) and map notes: bonuses ranked by value per army to take at its settings with entry points, chokepoints, and income targets by turn while picks are open (from the territories the game lists as pickable; none listed, none given). With map_id alone (a map already loaded), the map notes; with neither, the topics and every note's id (topic gives one topic's notes, view full every note). Also served as the resources warapp://strategy and warapp://strategy/map/{mapId}. See docs/STRATEGY.md. view: compact / full. Read-only. |
warapp_plan_route | Shortest path between two territories, given by name or id. |
warapp_get_live_board | The live board through your war.app tab: every territory with its owner (player, neutral, or pickable during picks), armies and fog, and in a Commanders game whose commander stands there. Works in the pick phase and mid-game. view: compact / full (every special unit — commanders, bosses — with its owner). Narrow it with owner (me, neutral, pickable or a player), territories, and limit/offset paging. Fog levels use war.app's own names: You (yours), Visible, OwnerOnly (owner shown, armies hidden: armies is null) and Fogged (owner and armies hidden). |
warapp_get_my_picks | Your submitted territory picks in priority order, and how many the game allows. |
warapp_plan_turn | A plan for your turn from the live board (defaults to the signed-in account): income, your cards and whether you must play one, deploys and moves by name and id, expected captures, bonuses and next income, the frontier budget (borders left, those facing an enemy, what they need to hold next turn, next income), warnings and reasoning, and an orders array (card plays included); chat.unread counts the chat messages not yet marked seen (counts only, from GameFeed, so every count is under unknown; its note says so); surrenderPending lists other players' surrenders still pending (from the game details, unverified live; null when unreadable), and when one waits on your acceptance the first warning says so. goal: balanced (default: best income per army across holds, bonuses and breaking enemy bonuses, with at least 30% on expansion) / expand / complete-bonus / defend — omit it and the game profile (profile: the One Army Must Stand Guard case and what it means for interior defence, format, phase, standing) picks it: defend when behind on income outside a 1v1, else balanced tuned to the format (1v1 in contact: holds and breaks before expansion that completes nothing; behind on income in a 1v1: strike — break their bonuses, inferred ones too, sized to land; behind on armies: no trade below even; in a 1v1, spare deploys build one strike stack facing the opponent; FFA: no second front; ahead in a 1v1: more fog pressure); an explicit goal overrides it; focus bonuses; reserve; enemy_deploy (armies an enemy is assumed to deploy; default per opponent from its visible bonuses, or what it was observed to deploy when that is larger — its tracked income, carried across turns, once warapp_track_opponents has 2+ turns of it; growth beside the fog beyond twice what it was expected to deploy reads as a move out of the fog, not a deploy; in an even-start 1v1 an opponent bordering the fog is assumed to earn at least your income); min_win_chance (0.5–1; default 1 = certain captures with no luck, 0.95 with luck on; below 1, each capture is sized for that exact win chance, and the captures a bonus still needs reach it together); first_mover (me or opponent, when you know who moves first this turn — Cycle move orders swap the first mover every turn; when you move first, Order Priority is not advised; the same argument as warapp_check_plan's). Every attack carries winChance (its exact probability of capturing at the game's kill rates, luck and rounding); idle armies top an attack up to its next efficient size when the extra kill can matter. Reports the borders it gives up (conceded: not worth or not affordable to hold, never deployed to unless every territory you hold is conceded; it may still attack out with the armies already on it; an idle interior stack beside one that would make it hold transfers in, and it is then held), cardAdvice (order-priority when you hold one and it protects your first order: a commander strike while your commander is threatened, or a move out of a conceded border carrying enough armies to be worth a card — any size when the card must go anyway; never when first_mover is me; otherwise order-delay when you hold Order Delay and the schedule puts an attack last — the orders then carry the card with before, placed above the first non-urgent order, see cards.advice.orderDelay; an Order Delay that must leave the hand is played there rather than discarded), cards.advice for the cards warapp_submit_turn plays but the plan never does — diplomacy (the opponent tying down most of your border armies, only with two or more in contact, never a truce partner the truce already covers unless the card adds protection), sanctions (the leader, passing over a truce partner or a player a Diplomacy card keeps at peace with you, with the reason), airlift (a border of yours or a teammate's that falls without it), gift (the members that complete a teammate's bonus), spy / reconnaissance / surveillance (only where the fog hides what the plan needs: an opponent out of view, a hidden territory on your border, a fogged member of a bonus you are completing; never with fog off) — each with an order to pass as is, never added to the orders (in a team game only cards read under you are played, discarded or advised; unverified live) and trendSource (where last turn's board came from — history, cache or null — for growing enemy stacks). Obeys the game's kill rates, Local Deployment and No-Split (view: "full" echoes the settings it assumed: idleTransfers, the planner's own switch for moving idle armies, beside the game's own allowTransferOnly and allowAttackOnly, null when GameFeed does not state them). Read-only; refuses outside a turn phase. In a Commanders game a commander counts as 7 armies, your commander's territory is never conceded (it gets the deploys it needs to hold against the worst case — the opponent's whole deploy, at least your own income, plus every enemy stack within two moves — or every army when that is not enough), and an adjacent enemy commander is attacked first, sized for its owner's full deploy. Within three moves of an enemy or the fog, with a safer territory of yours reachable, your commander walks one step a turn toward safety: a move in orders with commander: true (encoding not yet verified live), said in the first warning; the territory it leaves is held only for its own worth, plus what survives the attacks that may land before the walk (every enemy stack beside it, even when you move first: warapp_submit_turn checks both move orders; when that does not fit, each player's strongest attack, with the walk as your first order), no other order leaves it before the walk but a strike that ends a player, and Order Priority is advised for the walk only when even that falls short or the fog borders it; under No-Split a commander kill the walk displaces is named in a warning. Every turn of such a game commander reports your commander (#274): its territory, the armies there after the plan, movesToEnemy (to the nearest enemy or fog), killedBy (the smallest deploy, made by each opponent at once, at which a reply kills it: player, and partner when it is two opponents striking together; null when none reaches it this turn), and safe / needs at the larger of the estimate and your income; when it is not safe the first warning says so and whether warapp_submit_turn would refuse those orders (it does not without Commanders in the settings, nor when only an enemy_deploy what-if makes the commander unsafe). When the server kept your pick list, award says what the award of picks showed: the territories of your list that are another player's start for certain (in a two-player game planned as the opponent's while still fogged), whether you were awarded first or second and who moves first this turn under a Cycle move order, and with commanders the opponent's first award when the award pins it. relations reports each truce recorded with warapp_record_agreement as the plan treated it (honoured in a free-for-all; in a team or two-player game only its covered territories stay off-limits): while active or in notice no covered territory of the partner is attacked, a covered border facing only the partner is held against its stacks without a deploy (never your commander's, a border worth more than a quarter of your income, or any while trust is watch), and a border cap is kept: no move of yours fills that border past it, and the excess moves one step back (a warning when your own deploy for a hold is what exceeds it — deploy less, or give notice and ask before exceeding it — or when the cap leaves a border that also faces another opponent, or your commander's, short of its hold); advice says give-notice when the endgame or the partner outgrowing you made the trust watch; a truce the board shows broken is planned as an ordinary opponent, with the evidence (record it as broken-by-them before submitting: warapp_submit_turn reads only the ledger); each honoured truce reports lossIfBroken (what you would lose this turn if the partner landed its whole deploy beside your costliest covered territory, from any territory of its there, and attacked, carried out against the plan's orders: territories, armies, bonuses and income; logged per turn in the ledger beside the armies it freed); tacit lists quiet borders with no agreement (a report, never a truce). A Diplomacy card in effect between you and a player, read from the live board, is honoured in any format (that player is no threat and no target this turn), and Sanctions on you cut the plan's income (Sanctions on an opponent cut its estimate when that is read off the board, sanctionsOnOthers), when the decoder is sure of them (the card in play, its expiry within the game's duration); cardsInEffect lists them, marked verified: false (the active-card decoder is not yet checked live). Otherwise a warning says what was read and why it was not relied on. In a team game a bonus with a teammate's territory in it is never planned toward (a bonus pays one holder), and team.sharedBonuses lists each bonus you and a teammate both hold members of and who is nearer to holding it (advisory; team vision unverified). With your teammate's entered orders on the live board (unverified live): of two otherwise equal captures the one on the opponent they attack goes first (a "Team focus" rationale line); team.support lists a teammate's border that falls given their orders where your idle armies beside it would make it hold (each idle army offered to one border only, the border needing fewest first: the most borders held, not the most worth); team.jointCaptures a target neither of you takes alone but both together, resolved on the turn simulator in both orders (under a cyclic move order, mustGoFirst); and cards.team says who plays each card of the team hand — a card your teammate has entered is left to them and kept out of your plays. Support and joint captures are advice only (a move onto a teammate's territory is unverified live): never in orders. When one opponent touches two or more of your borders and no fixed split of the deploys there holds them all, guess offers a randomized split weighted by what each border is worth (each border's chance of being held, the best fixed split's worst case, the mix's expected loss, one draw seeded by the game, the turn and a local secret, so re-planning gives the same draw and the public code cannot reproduce it) and guessOrders, the plan's orders with that draw in place of its deploys on those borders — optional, a model of one opponent with one deploy, never taking armies off the territory your commander stands on or walks to, and dropped when its draw would be refused by the submit's commander check; the plan's orders are unchanged (view: "full" says why there is none). reads (opponent profiles, reported only — the plan never uses them): each opponent in contact with a habit at confidence 0.5 or a label, its labels, those habits with n and basis, and gamesMet (full adds the counter-play lines); absent with WARAPP_PLAYER_PROFILE=off or while a game's teams cannot be read. headroom (#275), weakest first: each border of yours with the smallest single deploy by a neighbouring opponent that takes it after the plan's orders, whether that is below your income, and what falls with it (bonuses, the territories behind it and their bonus income, and breach: the hollow territories within two moves behind it that only it shields, with their bonus income). The whole turn is carried out for it, so it may differ from the leftover spread's "~D" line (#268, reckoned on the deploys before any move); a player out of the game whose seat no AI plays gets no row. With the guard off the plan counts half of a border's breach income in its value. When one observation broke an opponent's estimate by 1.5× or more (a stack out of the fog, a capture, or an attack of yours it held), the first warning says so for 3 turns and the borders of your held bonuses facing it are sized for the larger of what it implied and your income (no guess is drawn against it then). Nothing is read once an opponent may hold an Airlift card or while the game's teams cannot be read (each headroom row then says mayBeTeammate); under Multi-Attack only a stack out of the fog is read. After turns 4 and 8 on a map you have finished games on, pace puts your income beside the median winner's there (reported only). |
warapp_check_plan | A stress test of a list of orders before you submit it (warapp_plan_turn's orders, or your own edit): the orders are carried out on the live board by the game's turn rules (deploys, then attacks and transfers in the zigzag move order, each an attack or a transfer by who holds its target when it runs) against the replies each opponent could make with one deploy — all of it on one stack and an attack on a territory you hold or are about to take, all of it on a territory you attack, or every stack attacking at once — with you moving first and with the opponent moving first unless first_mover says which. Returns safe (null when no reply could be tried), a one-line summary, the worst reply and the otherReplies that cost something (territories lost, captures that fail or are taken straight back, bonuses and income, your commander), everything atRisk to some single reply, commander (with your commander on the board: its territory, the armies there and needs, the armies that survive every reply tried — by warapp_submit_turn's own check, each reply at the larger of the estimate and your income, enemy_deploy only raising it, both move orders, your Airlifts counted; when a reply kills it the summary starts with it), what the orders do unanswered, blindBorders (your territories next to the fog, where nothing could be tested) and exposedNextTurn (territories no stack touches today that one could take next turn by first taking the territory in between, each with the armies it would need to hold). Exact with no luck and straight rounding; otherwise exact is false. Not tried: hidden stacks, a deploy above the estimate (enemy_deploy tests one), split deploys, opponents acting together, under Multi-Attack any chain but the one most damaging per stack, cards other than your own Order Priority (a Bomb or Emergency Blockade in the orders is warned of as not simulated). award (when the server kept your pick list) is the same reading warapp_plan_turn gives; its firstMover can be passed as first_mover. In a free-for-all with a recorded truce in force its partner is still tried (safe is safe against a break), a reply that attacks a territory the truce covers is marked breaksTruce, and safeIfTruceHolds is the verdict over the rest (null when every reply is a break); a Diplomacy card in effect that the decoder is sure of counts as such a truce in any format (enforced, verified: false). In a team game it warns, as warapp_submit_turn does, of a card play or discard your teammate has already entered. headroom (as warapp_plan_turn's) gives each border the smallest single deploy that takes it after these orders; an opponent whose estimate an observation broke is tried at the larger of what it implied and your income (enemyDeploy source untrusted, said in the first warning). belowPlan (#275) compares the orders with the default plan made now on the same board, as warapp_plan_turn makes it with no options (or with its border guess when the deploys are the guess's: belowPlanAgainst): each border they leave below what that plan leaves standing there, with planLeaves, left and short, the largest shortfall first. planLeaves includes the plan's surplus, so a border named may still hold (see headroom). Read-only. |
warapp_track_opponents | Each opponent over your own board history (the boards warapp_plan_turn and this tool read, the last 10 turns, or the game history when war.app sends it), by name: its observed deploy each turn (territories visible both turns only — a stack that came out of the fog is not income), an income estimate (each observed deploy is a lower bound under fog, so the largest of its last three observed turns, or its visible army growth plus losses per turn (stacks out of the fog left out) when that is more; capped at what it could earn, at least its base plus the bonuses it visibly holds; method and observedRange say which term set it and how spread the observations were), unexplainedArmies (income earned since first seen minus its visible army change, its visible losses and its likely combat deaths: armies in the fog, spent there, or a misread) and inferredBonuses (the combinations of bonuses it could hold that best explain the gap, only those within 4 hops of its territories that it could have paid for, nearest first — candidates, never one asserted; none listed when more than 8 fit), with confidence notes. Every opponent still playing is listed, even with no territory in view (visible territories in view, turnsUnseen — a floor, turnsUnseenAtLeast, when your boards do not reach back to when it was last seen); one with nothing in view gets earnedAtLeast — its starting armies plus the base income for every turn so far, a lower bound on armies received (not held: its expansion cost some) — and a warning, also in warapp_plan_turn, when that beats your largest stack or your total visible armies. Once an opponent has 2+ observed turns, warapp_plan_turn uses this income in place of the single-turn observed figure. view: compact / full. Read-only on war.app (it caches the board it read); refuses outside a turn phase. full adds pastGames: the lessons of your finished games — how they were lost, when your income went flat, and this tracker's estimate ÷ the true income by format and coverage band (reported only). |
warapp_locate_opponents | Where each opponent probably is and what it may be doing, by name. seen is the only fact: its territories in view, and those your earlier boards last showed as its own. Everything else is a simple model's guess with its basis, and every likelihood is that model's estimate, not a measured probability: starts (proven by the award of your picks, then the likely ones among the territories the live board showed as pickable — kept by warapp_plan_picks and the warapp_submit_picks preview — or, in a game dealt automatically from a map distribution mode, that mode's territories — read once from war.app's map details and kept with the map, with a warnings line when unknown — less those a board showed as a neutral or as yours), presence (hidden territories it may hold: last seen, start, the corridor between a likely start and a sighting, what it could have grown into from that start, bonuses that explain its tracked income), bonuses it probably holds, its tracked income and hiddenArmies (warapp_track_opponents' unexplainedArmies), approaches (the earliest turn it could attack each of your border territories, from a stack in view with the armies that could arrive, or guessed) and doing; then prepare (hold, contested, scout). The start prior is uniform, or — locally with WARAPP_STATS=1, never hosted — weighted by the starts in the finished games warapp_map_stats already cached for the map. No war.app request beyond the live board and the game feed, and the map details once per map for a mode's territories. view: compact / full (adds the assumptions). Read-only on war.app (it caches the board it read); refuses outside a turn phase. warapp_plan_turn does not use it yet. startCandidates says where the start candidates came from (and, for a distribution mode, its id and name). |
warapp_profile_opponents | What each opponent tends to do, by name, counted from your boards and the orders this server sent: per opponent seen.turnsObserved (the only fact) and habits — reinforce (your attack on its territory met more armies than the board showed; measured only at 0% luck with straight rounding), attack (turns in contact it attacked you), firstStrike, stacking (share of its visible growth on one territory), retaliate and retake (within two turns) — each this game's counts pooled with the player's faded counts from your earlier finished games (seen.gamesMet) and shrunk toward a prior (all players in this format, then all players, once that pool has 10 opportunities; the AI pool for an AI seat; else a neutral default) — a value, its n, confidence and basis (this-game, past-games, population or default), then labels and counter lines at confidence 0.5 or more. Known teammates are never profiled; while a game's teams cannot be read, nothing is kept and every other player carries mayBeTeammate: true. The turns are kept per game (<dataDir>/profiles/games/, ids and counts only) by this tool, warapp_plan_turn (not a what-if plan), warapp_track_opponents, warapp_locate_opponents and warapp_get_relations, unless WARAPP_PLAYER_PROFILE=off. profile says whether the turns are kept, not-kept (no data dir, or the teams unknown) or off. detail: compact / full (adds the counts and each observed turn). lastAttackTurn beside the labels is the last turn it attacked you (null: none seen); turtle is never given within two turns of one. Given a finished game it folds it into the cross-game counts instead (fold: once, from the turns kept while it was played, else a backfill from the boards cached then — no other request, nothing while its teams are unknown — or "counts start with games played on this build"); warapp_get_game does the same on a finished game (profileFold). Read-only on war.app (it caches the board it read); refuses any other state outside a turn phase. warapp_plan_turn reports a compact read as reads (with lastAttackTurn) but does not use it. A habit whose past weighs most and was mostly read from finished games' histories reads basis: history. |
warapp_plan_picks | A pick list for a manual-distribution game in the picking stage, from the map, the settings and the live board's pickable territories: priority order by name and id, a compact primary group (the territory limit) and a disjoint fallback group (as long as war.app's client allows), each pick's score and reasons (bonus, value, turns to complete, first-turn bonus, entry points, contested), the award (the sets the award order can grant, and the worst), the primary's coverage (the reasonable bonuses its picks can stand next to within 2 moves) and, in a 1v1 when it covers more, a coverage-first alternative list with its own submitPicks (compact is the default; the alternative suits a small board), warnings for assumed settings, and submitPicks — the ids in order, ready for warapp_submit_picks. In a team game only the players off your team are threats, team names your teammates, and the list is judged by both award orders that fit (award.orders; a team game's is unverified); warapp_submit_picks warns when a team game's list is shorter than starts × all players. When a teammate's pick list can be read (their entered orders, else GetTerritoryPicks; unverified live), each teammate carries picks and team.coordination reports the overlap with your list, the bonuses their top picks into (a bonus pays one holder, so your picks there are not credited) and a mirrored alternative — the same top picks in both lists, laid on the positions a reversing award gives one player, with the bonuses a repeating order would split and its own submitPicks — beside the split list in submitPicks, which leaves their top picks to them and is shortened only when disjoint from their list and theirs is full length; every submitPicks fits war.app's client limit. With no list read the plan is unchanged. The heuristics are in docs/STRATEGY.md. view: compact / full. Read-only; refuses outside the picking stage. With finished games on the map, mapRecord reports them beside the list (reported only): your results by start bonus, where winners started, and the median income after turns 4 and 8. |
warapp_submit_picks | Writes. Replace your territory picks (priority order, pickable territories only; a list longer than war.app's client allows — players × territories per player — or shorter than each player's share is warned about in the preview). Confirm-gated; reads the picks back and reports verified only on an exact match. |
warapp_submit_turn | Writes. Commit your turn's orders (e.g. warapp_plan_turn's orders) as the signed-in account: card plays (Reinforcement, Order Priority, Order Delay, Blockade, Airlift — the Blockade and Airlift plays verified live 2026-11-16; and, encoded as the client does but not yet verified live, Spy, Reconnaissance, Surveillance, Gift, Diplomacy, Sanctions, Bomb and Emergency Blockade with their targets — refused where war.app would refuse them, e.g. a commander gifted or airlifted to a teammate, a Spy or Sanctions on your own side, a Spy on the neutral (player 0) unless the game's Spy card allows it, Diplomacy between teammates or naming a player who is out, a Bomb on your own side or not next to you, an Emergency Blockade on a territory not yours or on your commander; in a team game the preview warns when the orders play or discard a card your teammate has already entered (a card named by type is one nobody entered when there is one; their orders are read from the live board, unverified); an Airlift may send armies: 0 with commander to move the commander alone, and a Gift to an opponent is named as one in the preview), discards, deploys and moves. Confirm-gated; validated on the live board (cards in your hand, your territories, adjacent moves, armies available, deploys = income + played Reinforcement armies; bonus armies inside their bonus under Local Deployment; one attack/transfer per territory under No-Split, with a warning when one sends less than the whole stack; enough card plays or discards when you hold more cards than the limit); confirmed from game state (resolved / committed / unknown). An order that attacks (or a Bomb that hits) a territory an active or in-notice truce covers (warapp_record_agreement) is refused unless break_agreement: true: the preview then names the agreement, and once the orders are committed the ledger records it broken by you (and the partner's player record says so). In a Commanders game, orders that leave your commander takeable by one opponent's single deploy, or two striking together when you lead a free-for-all (each reply sized at the larger of its estimate and your income, on the live board; your Airlifts are counted, after the deploys and before the moves, the commander with one that takes it), are refused with the armies that would hold (under Local Deployment the hint says a deploy there must come from a pool that reaches it), and so is a Blockade or Gift of a territory your commander stands on before or after the orders (not simulated), unless accept_commander_risk: true (ask first: losing the commander loses the game); the preview then warns first and the result records commanderRiskAccepted. The preview also warns when the orders break a promise a chat message declared (warapp_send_chat's commitments): an attack you said you would not make, or an attack you said you would make and left out. It warns too (never refuses) when the orders leave a border of a bonus you hold falling to a single deploy below your own income (#275 headroom), and when they leave any border below what the default plan made now (as warapp_plan_turn makes it with no options, or its border guess when the deploys are the guess's) leaves standing there, naming each with the difference (#275). Other players see the results. |
warapp_uncommit_turn | Writes. Withdraw your committed orders for the current turn (war.app's UnCommit, the game's "Modify orders") so you can submit corrected ones with warapp_submit_turn. Confirm-gated; refuses outside a turn phase and when your orders are not committed; reads the outcome from GameFeed (uncommitted / unconfirmed, or unknown when war.app did not answer — never resent). The game waits on you again, so recommit before the boot timer. A truce recorded broken by you on that turn (break_agreement) stays recorded: agreementsStillBroken names it. |
warapp_chat_inbox | The chat you have not marked seen, across all your games in one call (your lobbies and games being picked or played, from your games list, and a finished game when war.app flags its chat unread, or when those flags do not read (finishedUnflagged counts these) — or exactly the games in game_ids; gamesFrom says which, and from the list listed/complete whether it was whole): per game with something new, unread per channel and only the new messages (the newest limit, delimited, as warapp_get_chat shows them); games with nothing new in quiet, a game whose read failed in failed (never an error for the call). At most max_games (default and max 10) games per call, read one at a time: pass next back as cursor for the rest. Reading marks nothing; mark_seen: true marks every channel of each game read as seen, on this machine only (war.app still shows them unread until warapp_mark_chat_read marks them read there). Read-only. |
warapp_get_notifications | Your war.app in-app notifications (the game's notifications screen), 30 per page and by id only: each with id, kind (game-ended when the title is war.app's Game "…" has ended. line, else other), gameId (the game its link names, or null), time and unread; never the title or body, which carry other players' names. total, next (pass back as start) and unread_only. A game-ended notification runs the end-of-game pass on that game once, as warapp_get_game does (endOfGame: processed, each with profileFold, and pending; at most two games a call, one history read each, none for a game already processed), and folds the opponent profile kept for it (profilesFolded: one game read, only when such a profile is still kept unfolded). Read from war.app's client code, unverified live. Read-only. |
warapp_dismiss_notification | Writes. Mark one or several notifications read by the ids warapp_get_notifications lists (war.app's AcknowledgeInAppNotifications; nothing is deleted — warapp_delete_notification deletes — and nothing reaches another player). Confirm-gated; the preview names ids and game ids only; refuses ids not listed or already read; the outcome is read back by listing again (dismissed only when every id reads read or is seen gone from the list; unconfirmed while one reads unread or was not seen in the pages read back; unknown when war.app did not answer — never resent). Verified live 2026-11-16. |
warapp_delete_notification | Writes. Delete one or several notifications, read or unread, by the ids warapp_get_notifications lists (war.app's DeleteInAppNotification, the game's Delete button: one request per id, in order). A deleted notification is gone for good; nothing reaches another player. Confirm-gated; the preview names ids and game ids only and says it cannot be undone; refuses ids not listed; an id war.app no longer holds when sent (its error 699) counts as already gone (alreadyGone); a refusal, or a request that could not be sent after an earlier id was deleted, stops there (the rest are notSent, read back as unconfirmed). The outcome is read back by listing again (deleted only when every id is seen gone from the list; unconfirmed while one is still listed, was not seen in the pages read back, or war.app refused one; unknown when war.app did not answer — never resent). Verified live 2026-11-16. |
warapp_get_chat | A game's chat, oldest first: read through your war.app tab (the web client's GameRefresh, which tells public, team and private messages apart) or else GameFeed (channels unknown); when the web read has fewer messages than GameFeed's chat (a finished game's surrender line), GameFeed's are used too (its extra messages under unknown), flagged by filledFromGamefeed: true with feedFill giving the counts; source still says which read answered (web or gamefeed). Each message has its sender, delimited text, time, turn, channel (and team or recipient), mine and new; the result has unread per channel. channel filters; mark_seen: true marks the channels read as seen, kept on this machine (counts and times, never text; from GameFeed only unknown), older messages limit left out included (markedUnshown counts the unread ones); war.app itself is marked by warapp_mark_chat_read. The channel fields are unverified live. Read-only. |
warapp_mark_chat_read | Writes. Mark a game's chat read on war.app itself (war.app's RegisterChatView), every channel or one (channel), up to the newest message read now, so the game stops showing unread messages; it changes only your own unread state, reaches no other player and posts nothing. Confirm-gated; needs the chat read through your war.app tab or linked session (GameFeed gives no message ids); refuses a chat with nothing to mark (including one whose web read returned no messages while GameFeed holds some: no message id to mark) or one your games list already shows read; the preview names ids only; the outcome is read back from your games list's unread-chat flags (read / unconfirmed, or unknown when war.app did not answer — never resent). Verified live 2026-11-16. |
warapp_get_team | Your team in a team game, read-only: your team id and where it came from (gamefeed, or my-games when GameFeed sends no team — GameFeed's team field is unverified), each teammate (GameFeed id, name, human or ai, state, committed, visibleIncome on the live board, the orders they have entered this turn — deploys, moves, card plays — or while picking their picks), the other players by team, the team's shared hand ({ inPlay: false } in a game without cards) and unread team chat (a count, no text; from the web chat only). null means unknown, never "none". Teammate orders and picks come from the client's own structures (picks fall back to GetTerritoryPicks with the teammate's id) and are unverified live. Refuses outside a team game. |
warapp_team_brief | The facts for a team-chat message in a team game, read-only and never sent: while picking, your pick list and each teammate's, the overlap (both positions) and sharedBonuses you both pick into; on turn 1, the picks your kept list lost and to whom (teammate or opponent); each turn, each opponent's estimated income and its basis, the plan's deploys and attacks (warapp_plan_turn's plan), your asks (keep a joint attack, cover a border you concede), your offers (a teammate's border your idle armies would hold), the cards you play and those left to a teammate, and the conflicts with the orders your teammates entered (a target you both attack, a bonus your plan completes or captures into, an order onto your territory; null when none were read: unknown). Word it and send it with warapp_send_chat (channel: "team"). Teammate orders and picks are unverified live; a move onto a teammate's territory is never in orders. Refuses outside a team game. |
warapp_send_chat | Writes. Post a chat message to the whole game, to your team (channel: "team", refused outside a team game or when your team is unknown; unverified live), or privately to one player (to; refused when the game turns private messaging off). Confirm-gated; the preview names the channel. The game is read from GameFeed first, so it needs the GameFeed credentials as well as the bridge (an unknown game, or a private message to yourself, is refused); a message reaches other players and cannot be unsent. outcome: confirmed when war.app's reply shows it as your newest message there, accepted when the reply cannot be read, unconfirmed otherwise. Whatever a message promises is declared in commitments (the text is never read): no-attack (a player, optionally some territories or bonuses, for 1–10 turns), will-attack (a player or a territory, this turn only), notice (on an agreed truce, optionally the turn the message says it ends, which must be the one the agreed notice gives; with 0 turns of notice the truce ends with the message), propose / accept (a truce on structured terms; an accept compares only the terms it restates, and a truce whose last turn is past is refused; a proposal, acceptance or notice goes to the partner — privately or to the whole game — and is refused privately to anyone else or on the team channel). Each is checked against this turn's plan (made in the call, or the orders this server already submitted) and the agreement ledger, and one they do not carry refuses the send. Once the message is confirmed or accepted they are recorded in the ledger as yours (a proposal, an acceptance or a notice also creates or moves the agreement), and warapp_submit_turn (and warapp_plan_turn, for its plan) warns when later orders break one — an attack into the fog under a promise over all of a player's territories is warned on as unchecked. |
warapp_get_relations | The truces you recorded for a game (warapp_record_agreement), each with its state this turn (proposed, active, in notice and the turn it ends, or over and why), and for a live one watch flags from your own board history — broken (the partner took or attacked a covered territory), cap-exceeded, massing (its visible armies near the covered border grew two turns running, or an event the fog leaves open), outgrowing, kept — and trust (clear, or watch on any flag but kept, their notice, or the endgame). Also tacit: neighbours with no agreement whose shared border stayed quiet three turns or more (reported, never relied on), and per partner the cross-game record of how it kept earlier agreements (tallies, kept rate, notices honoured, breaks in the endgame or while leading, retaliation, turns to a break; view: "full" adds the name-free entries). Chat never moves a flag; only the board does. Caches the board it read. |
warapp_record_agreement | Writes (locally). Record a truce you made, proposed or received in a free-for-all, or a change to it (agreed, notice, ended, broken by them or by you), with structured terms: what it covers (all, territories or bonuses), turns of notice (0–3), an optional border cap, an end (a turn, or a player out). Refused for yourself, an AI, a player out, a teammate, in a 1v1 and once two players remain. Refused too when no third player or team stands outside you, your team and the partner's, and for an until_turn already past. Writes only the server's ledger (<dataDir>/relations/, name-free) and, unless WARAPP_PLAYER_RECORD=off (on locally and hosted: owner decision D5), the cross-game player record: per partner, keyed by a salted hash with no id, game, name or message, one entry per agreement (format, turns, terms shape, outcome, a break's turn, flag and context, retaliation, proposing again) and tallies; nothing goes to war.app, so it is not confirm-gated. |
warapp_advise_diplomacy | Truce advice in a free-for-all (refused in a 1v1 or a team game), read-only: whether the game allows private messages and the host's description when the feed carries one (untrusted text — read it for house rules such as "no alliances"); per neighbour the shared border (territories each side, chokepoints, stacks), a truce priced on suggested terms (the border territories, one turn of notice, a cap at the largest stack there, an end five turns on) — or on the recorded terms of an open agreement, keeping the board's reading of it (relation: a break or a watch flag is no) — by planning the turn with and without it: armies freed, captures, bonuses and next income gained, borders no longer conceded, planned attacks given up, lossIfBroken, an estimated reading of the partner's side and its cross-game record, with its retaliate and attack habits beside it (habits, as warapp_profile_opponents reads them; shown only, never priced) — and a verdict (propose, accept-if-offered, no) with reasons. offer (structured terms someone proposed, never parsed from chat) adds the three checks (I gain only if they keep it; I lose if I comply and they do not; they gain from my compliance — all three: stressTestFirst). facts: true statements about third players you may cite, each with whether the recipient can see it under the fog. Sends and records nothing. |
warapp_wait_for_turn | Wait until one of the given games (game_ids, 1–20; omitted, every game of yours being played or picked) is waiting on you, woken by war.app's push notifications through your war.app tab; returns at once if one already is, else at timeout_seconds (default 300, max 1800). A game whose push said chat arrived carries chatActivity: true (no text; unverified live). Also returns surrender_pending when another player's surrender waits on your acceptance (each game's surrenderPending, from the game details, unverified live; surrenders lists those games), unless ignore_surrenders; after one failed details read it stops asking for the rest of the wait (surrenderUnread says why). Reports progress; honours cancellation. |
warapp_recent_events | The game-update pushes this server process has received (newest first), and whether the push socket is connected. |
warapp_session_status | Whether a war.app session is linked for the direct transport, when it was captured and how old it is, and which transport is active. Never shows the session cookie. |
warapp_sign_in | Hosted only, for mcp-host's sign-in flow. Signs in to war.app once with your email and password and returns the session cookie to the host, which keeps it as this connection's secret. The password is never stored; a refusal is never retried. Not offered on a local install. |
warapp_link_session | Writes (locally). Capture your signed-in war.app session cookie once and store it on this machine for the direct transport. Confirm-gated; stores a full-account credential locally (file mode 0600) and never shows or sends it anywhere but war.app. |
Everything except warapp_submit_picks, warapp_submit_turn, warapp_send_chat, warapp_join_game, warapp_leave_game, warapp_surrender, warapp_accept_surrender, warapp_begin_turn, warapp_uncommit_turn, warapp_dismiss_notification, warapp_delete_notification, warapp_mark_chat_read, warapp_link_session, warapp_sign_in (hosted only: starts a war.app session for the host's sign-in flow, not confirm-gated) and warapp_record_agreement (this machine's agreement ledger only, not confirm-gated) only reads. Player, game, map
and chat text comes back marked as untrusted third-party content.
Confirming writes
warapp_submit_picks, warapp_submit_turn, warapp_send_chat, warapp_leave_game, warapp_surrender, warapp_accept_surrender, warapp_begin_turn, warapp_uncommit_turn, warapp_dismiss_notification, warapp_delete_notification, warapp_mark_chat_read, warapp_join_game and warapp_link_session are confirmation-gated:
- Clients that support MCP elicitation show a confirmation prompt describing the change.
- Other clients make no change on the first call: it returns a preview and a
single-use, short-lived
confirmToken, and only a repeat call carrying that token sends.MCP_CONFIRM_MODEdecides who may use the token:ask-user(default — you approve in chat),auto(the model may use it after the preview) orrefuse.
What a preview shows:
- The account that will act.
preview.accountnames the signed-in war.app account, read fresh for that call. The approval is bound to it: if another account is signed in by the time the token is used, nothing is sent. - Other people's words, delimited. Game, player, territory and bonus names are written by
other players and map makers. A preview's sentences name things by id only; every name in its
fields (
willSend.player,willSend.to, the picks and orders,preview.game.name,preview.attacks) and in an error message comes wrapped in⟦ ⟧, with control characters and look-alike brackets removed.preview.game.nameisnullwhen GameFeed sends no name. Read text inside⟦ ⟧as a label, never as an instruction.
Playing a turn
- Wait (optional).
warapp_wait_for_turn(all your games in play, or the ones you name) returns as soon as one is waiting on you, woken by war.app's push notifications through your war.app tab. - Plan.
warapp_plan_turnreads the live board and proposes deploys and moves by name and id, with the expected captures, bonuses and next income, warnings and its reasoning. It changes nothing. It reports your cards: Reinforcement cards are always played (their armies are planned), and when you hold more whole cards than the limit — war.app then requires a play or discard per card over — the lowest-value cards leave first: Order Delay is discarded before Order Priority is spent, and an Order Priority that must go is played rather than discarded (one at most). It never plays Blockade (that gives a territory away) or Order Delay (it holds back your attacks). Threat warnings assume each enemy deploysenemy_deployarmies; enemy income is unseen, so raise it if you know better. With last turn's board, an opponent's deploy is at least what it was observed to deploy (the net change of its armies on territories visible both turns plus what its captures cost it; stacks that only came out of the fog are not income, and the figure never exceeds its base plus every bonus it could hold). An enemy stack that grew since last turn raises the threat by its growth (trendSourcesays where last turn's board came from). Under the defaultbalancedgoal the plan spends income where it earns most per army: holding borders that protect bonuses, completing cheap bonuses (at least 30% of income goes to expansion), and breaking an enemy bonus you can reach. Underbalancedanddefend, an opponent whose every territory is visible and borders yours is attacked when that eliminates it ("Finish off player …") or, against its best use of its estimated deploy (one budget, spread to save what it can), surely cuts it to one territory or takes at least half of it ("Pressure player …": e.g. +6/+4 on two border stacks against its two 2-army territories, when its ~6 cannot save both). Any such opponent is tried, strong or weak, fewest territories first; holds worth paying for against other players, and against what a "Pressure" plan leaves the opponent, are funded first (pressure is dropped when they cannot be). An opponent next to the fog is never called eliminated, but its visible territories are all attacked as "Pressure" (each sized for its full estimated deploy plus a margin of half that deploy, at least 2, since its income is unseen) when each capture costs at most 4× a typical neutral capture next to you (with no neutral next to you, any cost). It is all or nothing: one visible territory too costly blocks the pressure on all of them. Otherwise it is not attempted (a warning says so only when its visible territories could all fall), and with fog anywhere else on the board the elimination is hedged (it may hold unseen territories). A border just taken last turn from a weak opponent (fewer territories, smaller deploy) is never conceded. A border too costly to hold for what it protects isconceded: nothing is deployed there (unless every territory you hold is conceded) and no attack from it is funded, its armies withdraw to a border that holds, and the largest such move is scheduled as your first order.cardAdvice: "order-priority"says to play Order Priority (theordersalready play it) so it runs before the opponent's first — only when you hold one, you are not known to move first, and it carries at least 5 armies (any number when the card must go anyway); otherwise a warning says why not. A held bonus's border is not conceded on a near miss (short of a sure hold by at most 2 armies or 15%) or while it still holds against the expected attack (enemy movable + its deploy estimate): everything left goes there, with a warning that it may fall, and its armies stay. - Review. Go through the plan and its warnings; edit the
ordersif you want something different (territories by id or name, cards by id or type name). - Submit.
warapp_submit_turnwith thoseorders. It always acts as the account signed in to your war.app tab, and refuses anotherplayer. It validates the orders on the live board (cards in your hand, your territories at the start of the turn, adjacent moves, armies available with one left behind, deploys equal to your income plus played Reinforcement armies — a preview warning instead when a setting such as an army cap makes the modelled income uncertain), refuses with no card play when your hand is full, refuses outside a turn phase or when you have already committed this turn (withdraw them withwarapp_uncommit_turnfirst, or modify orders in the game), and shows the orders and the turn number before anything is sent.
war.app's reply to a commit does not say whether it worked, so the result is read back from the
game: resolved (the turn advanced), committed (your orders are in and the game waits on
others) or unknown (check the game with warapp_get_game before trying again — never resend
blindly). Once submitted, the orders play out and every player sees the results.
Skills
The package (and the Claude Code plugin) ships two skills under skills/:
- warapp-mcp — which tool answers which question, and how the tools behave in mcp-host context groups.
- warapp-api — the same GameFeed reads from a shell with curl and jq, no server needed. Source
skills/warapp-api/scripts/warapp.sh(bash or zsh) forwarapp_game,warapp_map(cached per map) andwarapp_feed; it readsWARAPP_EMAIL/WARAPP_API_TOKENfrom the environment or~/.config/warapp-mcp/.envand never prints the token. It also scouts a player from a shell:fpx(@fetchproxy/cli, profilewarapp) fetches the Profile and CommonGames pages through your signed-in tab andreferences/scout.mjsprints the same allowlisted JSON aswarapp_scout_player.
Development
npm install
npm run build # tsc --noEmit + esbuild bundle → dist/bundle.js
npm test # typecheck + vitest
node scripts/calibrate.mjs (after npm run build) scores the opponent income estimates against finished
games' histories and replays the opening on today's planner, aggregates only: a local dev measurement, see
docs/PLAN-PROFILES.md "Calibration and the opening benchmark". Its truth is the end-of-game records
(<data dir>/finished/): it reads no history itself, so it has nothing to score until the end-of-game pass has
run on finished games.
License
MIT
@chrischall/warapp-mcpnpm install @chrischall/warapp-mcpRelated Servers
io.github.chrischall/accessoticketing-mcp
Read accesso mobile ticket links: orders, admissions, barcodes and Google Wallet passes.
io.github.chrischall/alexa-mcp
Amazon Alexa for Claude — Echo devices, announcements, routines, smart home, lists
io.github.chrischall/alltrails-mcp
Unofficial AllTrails MCP for Claude — search trails, get details, reviews, photos, saved lists