# MCP Tools — Minimal War

Auto-generated from `packages/shared/src/actions/registry.ts` and
`apps/server/src/mcp/tools.ts`. Do not edit by hand — run
`npm run mcp:docs` (from the repo root) to regenerate.

All tools require a `Bearer mw_live_*` API token in the
`Authorization` header. Mint tokens at `/settings/api-tokens`.

## Read tools

### `mw_list_my_games`

List every game the authenticated user has a faction in, with status, current turn, and whose turn it is.

**Input:** (no arguments)

### `mw_get_game_state`

Full JSON snapshot of a game: every territory, faction, army, and diplomatic relation.

**Input:** gameId

### `mw_get_briefing`

Per-faction structured briefing: own territories (frontline/interior), adjacent enemies, economy, recruitment capacity, diplomacy, world titles.

**Input:** gameId

### `mw_get_available_actions`

Every legal action the calling faction may submit right now, with per-action costs and gating preconditions. Call before each write tool.

**Input:** gameId

### `mw_get_recent_turn_log`

Recent TurnLog rows for the game, newest first. Each entry is the submitted action plus the server result.

**Input:** gameId, limit? (1-200, default 40)

### `mw_get_my_recent_events`

Per-faction projection of recent TurnLog rows — the agent equivalent of the in-game "you conquered / you lost / you were attacked" modals. Each event is either an action YOU took or an action by someone else that affected you. Newest first.

**Input:** gameId, limit? (1-200, default 40), sinceTurn?

### `mw_get_factions_summary`

One-shot summary across all factions in the game: territory count, total army strength, treasury, score with per-axis breakdown (military/conquest/development/army/titles), unitsKilled/unitsLost/territoriesConquered/territoriesLost counters, current diplomatic status with you, eliminated flag. Sorted by territory count desc. Use to size up threats without fanning out across mw_get_game_state.

**Input:** gameId

### `mw_get_rules`

Return the active gameplay ruleset (combat formulas, fortification bonuses, economy rates, recruitment slots, morale/rally mechanics, terrain modifiers, world titles, province policies, faction bonuses, upgrade costs, gods/temples) plus the BUILDING_SPECS registry (per-building level gates, uniqueness, eligibility). Scope the response with an optional section name.

**Input:** gameId?, section? (meta|combat|economy|morale|upgradeCosts|fortificationCosts|harbor|research|gods|recruitment|provincePolicies|factionBonuses|titles|buildings)

### `mw_explain_combat`

Return the deterministic multiplier math for a hypothetical attack — attacker and defender effective strengths after morale + terrain + fortification + garrison, plus the ruleset's random-factor band. NO win probability, NO expected losses (combat keeps its real RNG). Use to pre-check whether an even-looking fight is actually even.

**Input:** gameId, armyId, toTerritoryId

### `mw_list_chat`

List chat messages in a game visible to the calling faction (sent by you, sent to you, or sent to "all"). Newest first.

**Input:** gameId, limit? (1-200, default 50)

### `mw_send_chat`

Send a chat message in a game. Recipient is another faction's id, or "all" for a public broadcast. 500-char limit. Does not consume any action.

**Input:** gameId, toFactionId, content

### `mw_wait_for_my_turn`

Block until it becomes the calling faction's turn, the game ends, or the timeout elapses. Returns immediately if already your turn.

**Input:** gameId, timeoutSeconds? (1-55, default 50)

## Lobby tools

### `mw_list_open_games`

List every multiplayer game currently in the LOBBY phase. Use to find a game to join.

**Input:** (no arguments)

### `mw_list_playable_factions`

List the playable faction definitions (factionKey, name, color).

**Input:** (no arguments)

### `mw_list_rulesets`

List available rulesets (easy / normal / hard / ...).

**Input:** (no arguments)

### `mw_create_solo_game`

Create a new local single-player game seated on the chosen faction; starts ACTIVE with AI in every other seat.

**Input:** name, factionKey, rulesetName?

### `mw_create_multiplayer_game`

Create a new online game in LOBBY status. Call mw_join_game afterwards to claim a seat.

**Input:** name, rulesetName?

### `mw_join_game`

Claim a faction in a LOBBY-phase game. One API token can hold at most one seat per game.

**Input:** gameId, factionKey

### `mw_start_game`

Transition a multiplayer game from LOBBY to ACTIVE. Requires at least one faction to have joined. Solo games created via mw_create_solo_game start ACTIVE automatically and do not need this call.

**Input:** gameId

## Write tools (one per game action)

Each takes a `gameId` (string) on top of the fields listed below.
The `factionId` is resolved from your token and never accepted as input.

### `mw_attack`

Move an army into an adjacent enemy-controlled territory and resolve a combat round. Requires WAR with the target's owner. The result reports `winner: "attacker" | "defender"` AND a separate `territoryConquered: boolean` — winning the field does NOT always conquer the tile: a defender that retains any units after the resolver hits max rounds keeps the territory. On a conquest the survivor may need to be split between the conquered tile and the origin (separate SPLIT_ARMY action, prompted via the result). For sea crossings the army embarks and resolves next turn. Consumes one army action.

**Cost:** army-action

**Input:**
  - `armyId` (string)
  - `fromTerritoryId?` (string)
  - `toTerritoryId` (string)

### `mw_claim_favor`

Pay gold to claim a god's favor. Requires at least one of your temples to be dedicated to that god. Price when the favor is vacant is basePriceFlat + basePricePerRound × current round; when held by another faction the price is twice what they paid. On a successful claim the favor transfers to you and your bonus is bonusPerClaimStep × the god's total claim count. Does not consume an action.

**Cost:** free

**Input:**
  - `god` (enum(JUPITER | MARS | CERES | MERCURY | VESTA))

### `mw_declare_war`

Declare war on another faction. Required before you can ATTACK their territories. The target moves from PEACE to WAR with you. Does not consume an action.

**Cost:** free

**Input:**
  - `targetFactionId` (string)

### `mw_dedicate_temple`

Dedicate one of your Temples to a specific god — JUPITER, MARS, CERES, MERCURY, or VESTA. A temple must be dedicated before its owner is eligible to claim that god's favor. Costs a flat gold fee from the ruleset. Re-dedicating to a different god costs the same fee again. Consumes that territory's development action.

**Cost:** territory-action

**Input:**
  - `territoryId` (string)
  - `god` (enum(JUPITER | MARS | CERES | MERCURY | VESTA))

### `mw_develop`

Build or upgrade an improvement on a territory you control. Choices include GROW_FOOD, GROW_POP, GROW_GOLD, GROW_WORKSHOP, UPGRADE (development level), UPGRADE_HOUSING, SPECIALIZE, FORTIFY, TRANSFORM (change a building slot), BUILD_HARBOR, BUILD_CAMPUS, BUILD_TEMPLE. Valid choices on each territory come from get_available_actions. Consumes that territory's one development action for the round.

**Cost:** territory-action

**Input:**
  - `territoryId` (string)
  - `choice` (enum(GROW_FOOD | GROW_POP | GROW_GOLD | GROW_WORKSHOP | UPGRADE_HOUSING | UPGRADE | SPECIALIZE | FORTIFY | TRANSFORM | BUILD_HARBOR | BUILD_CAMPUS | BUILD_TEMPLE))
  - `specialization?` (enum(MILITARY | CAPITAL | ECONOMIC))
  - `slotIndex?` (number)
  - `newBuildingType?` (enum(FOOD | POPULATION | GOLD | WORKSHOP | FORTIFY | HARBOR | CAMPUS | TEMPLE))

### `mw_disband_army`

Permanently destroy one of your armies. Units do not return to the population pool. Does not consume an action.

**Cost:** free

**Input:**
  - `armyId` (string)

### `mw_end_turn`

End your turn. Advances the turn pointer to the next non-eliminated faction; if the pointer wraps around, end-of-round processing runs (economy, growth, starvation, embark resolution, world titles). After this call it is no longer your turn until the round comes back to you.

**Cost:** end-turn

**Input:**
_(no additional arguments)_

### `mw_merge_armies`

Combine two of your armies that occupy the same territory. The higher-experience army absorbs the other; veterancy is preserved on the survivor. Requires the "Combined Arms" research tech (acquired via mw_research at a Campus Martius). Consumes one army action against the surviving (absorbing) army.

**Cost:** army-action

**Input:**
  - `armyId` (string)
  - `absorbedArmyId` (string)

### `mw_move`

Move an army to an adjacent territory you control (or have free passage through). For sea crossings the army embarks and lands next turn. Consumes one army action.

**Cost:** army-action

**Input:**
  - `armyId` (string)
  - `fromTerritoryId?` (string)
  - `toTerritoryId` (string)

### `mw_raise_army`

Create a new army on a territory you control, drawing units from its population. Cannot raise on a territory that already used its development action this turn (and vice versa). Consumes that territory's one development action for the round.

**Cost:** territory-action

**Input:**
  - `territoryId` (string)
  - `infantry?` (number)
  - `cavalry?` (number)
  - `siege?` (number)

### `mw_rally`

Restore an army's morale to full. Costs gold proportional to the army's upkeep, missing morale, and veteran level. Consumes one army action against that army.

**Cost:** army-action

**Input:**
  - `armyId` (string)

### `mw_recruit`

Add units (infantry, cavalry, siege) to an existing army of yours. Units are paid for in gold; cavalry require a province military bonus or specialization; siege require a workshop. The army must not have acted this turn. Consumes one army action against this army (Level-5 Imperator armies have two actions per turn).

**Cost:** army-action

**Input:**
  - `armyId` (string)
  - `infantry?` (number)
  - `cavalry?` (number)
  - `siege?` (number)

### `mw_research`

Research a tech from the Campus Martius tree. Requires an unlocked Campus building and that the tech's prerequisites are met. Does not consume an action.

**Cost:** free

**Input:**
  - `techId` (string)

### `mw_set_province_policy`

Set the production policy for one of your provinces. MILITARY favours army upkeep / recruitment, ECONOMIC favours gold/food, HOME marks your seat of power. Each province has one active policy at a time; calling this replaces it. Does not consume an action at the top level.

**Cost:** free

**Input:**
  - `provinceId` (string)
  - `policy` (enum(MILITARY | ECONOMIC | HOME))

### `mw_split_army`

Split one army into two by leaving a garrison on `toTerritoryId` and moving the remainder to `fromTerritoryId`. Both territories must be adjacent and you must own (or have just conquered) both. The garrison{Infantry,Cavalry,Siege} numbers must not exceed the army's current composition. Does not consume an action.

**Cost:** free

**Input:**
  - `armyId` (string)
  - `fromTerritoryId?` (string)
  - `toTerritoryId` (string)
  - `garrisonInfantry?` (number)
  - `garrisonCavalry?` (number)
  - `garrisonSiege?` (number)