# SovietRepublic-MCP

MCP server for [Workers & Resources: Soviet Republic](https://store.steampowered.com/app/784150/Workers__Resources_Soviet_Republic/). Exposes live game data as tools for Claude Code and Claude Desktop.

## What it does

Reads live game data on every tool call — no background process, no stale cache. Two data sources are used:

- **`header.bin`** — contains the current in-game date and money balance, updated every autosave (~weekly in-game). Used by `get_realtime`.
- **`stats.ini`** — contains periodic records (one snapshot every ~5 in-game days) with economy prices, trade volumes, spending, and population data. Used by all other tools.

### Available tools

| Tool | Description |
| --- | --- |
| `get_stats` | Full snapshot: population, economy, year/day |
| `get_population` | Citizen counts and demographics |
| `get_economy` | All resource prices in RUB and USD |
| `get_citizen_status` | Happiness metrics (food, water, healthcare, …) on 0–1 scale |
| `get_history` | Time series for any metric across all autosave records |
| `get_trade` | Cumulative import/export totals since game start |
| `get_trade_period` | Import/export quantities for a date range (summed across all periodic records) |
| `list_buildings` | Browse building definitions filtered by type, produced or consumed resource |
| `get_building_info` | Full I/O details for a specific building (workers, production rates, consumption rates) |
| `get_spend_period` | Resources consumed by constructions, factories, shops, or vehicles in a date range |
| `get_production_chain` | All buildings that produce a resource, with input requirements and efficiency ranking |
| `get_break_even` | Material cost per unit output vs import price — shows margin and profitability |
| `get_realtime` | Current date and money (RUB + USD) from `header.bin` — more up-to-date than period records |
| `list_saves` | All available save folders |
| `set_active_save` | Pin a specific save folder as the active save |
| `get_active_save` | Show which save is active and how it was selected |
| `clear_active_save` | Remove the pin and follow the newest save again |

## Requirements

- Python 3.10+
- Workers & Resources: Soviet Republic installed (Steam)
- `mcp[cli]==1.3.0`

```bash
pip install -r requirements.txt
```

## Setup

### Claude Code (`~/.claude/settings.json`)

```json
{
  "mcpServers": {
    "soviet-republic": {
      "command": "python",
      "args": ["E:/SteamLibrary/steamapps/common/SovietRepublic/soviet_dashboard/main.py"]
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "soviet-republic": {
      "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python313\\python.exe",
      "args": ["E:\\SteamLibrary\\steamapps\\common\\SovietRepublic\\soviet_dashboard\\main.py"]
    }
  }
}
```

Restart Claude after editing the config. The server starts automatically when needed.

### Choosing a save

By default the server loads the **most recently modified** save — whatever you last saved or autosaved in-game. No configuration needed.

To pin a specific save permanently for this local checkout, use the MCP tools `set_active_save`, `get_active_save`, and `clear_active_save`.

To pin a specific save via configuration, set the `SOVIET_SAVE` environment variable to the folder name inside `media_soviet/save/`:

**Claude Code** (`~/.claude/settings.json`):

```json
{
  "mcpServers": {
    "soviet-republic": {
      "command": "python",
      "args": ["E:/SteamLibrary/steamapps/common/SovietRepublic/soviet_dashboard/main.py"],
      "env": {
        "SOVIET_SAVE": "autosave2"
      }
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "soviet-republic": {
      "command": "python.exe",
      "args": ["E:\\SteamLibrary\\steamapps\\common\\SovietRepublic\\soviet_dashboard\\main.py"],
      "env": {
        "SOVIET_SAVE": "Meine Stadt"
      }
    }
  }
}
```

Use `list_saves` to see all available save folders. The response includes `"active_save"` showing which one is currently loaded.
Use `set_active_save` to pin one save from inside Claude, `get_active_save` to inspect the current mode, and `clear_active_save` to go back to automatic newest-save selection.

## Data sources and field meanings

Understanding what each data field actually represents avoids common misinterpretations:

### `economy_rub` / `economy_usd` — Market prices, NOT production quantities

The most important thing to know: the `economy_rub` and `economy_usd` fields returned by `get_stats` and `get_economy` are **import/export market prices per unit** (RUB or USD per tonne, per MWh, per m³, etc.). They do NOT represent how much of a resource your republic produced.

```json
"economy_rub": {
  "steel": 763.18,       ← 763 RUB per tonne (market price)
  "chemicals": 1953.67,  ← 1953 RUB per tonne (market price)
  "nuclearfuel": 246327  ← 246,327 RUB per unit (market price)
}
```

### `Resources_Produced` — Actual production quantities (natural resources only)

The game only logs production quantities for **naturally extracted / grown resources**:

- `rawbauxite` (Rohes Bauxit)
- `plants` (Pflanzen)
- `food` (Essen)
- `gravel` (Kies)
- `rawgravel` (Bruchstein)
- `asphalt`, `concrete`, etc.

Factory-processed goods (steel, aluminium, chemicals, electronics, …) are **not tracked as production quantities** in `stats.ini`. Use the in-game Statistics → Production tab for those.

### Data sources summary

| What you want | Tool | What it returns |
| --- | --- | --- |
| Current date & money balance | `get_realtime` | Live from `header.bin` |
| Production quantities (natural) | `get_spend_period section=factories` | Factory input consumption as proxy |
| Market prices for resources | `get_economy` / `get_stats` → economy_rub/usd | Price per unit |
| Import/export volumes | `get_trade_period` | Tonnes traded per resource (costs only via `get_trade` cumulative) |
| Population & demographics | `get_population` | Citizen counts |
| Historical price trends | `get_history metric=steel` | Price over time |

## Usage

Once connected, ask Claude naturally:

### Economy & trade

> *"What's my current food supply satisfaction?"*
> *"Show me steel import history."*
> *"How much have I imported vs exported this year?"*
> *"What are the current market prices for building materials?"*

### Production planning

> *"What buildings can produce aluminium, and which is the most efficient?"*
> *"What's the full production chain for steel — what raw materials do I need?"*
> *"Is it cheaper to produce electricity with a coal plant or to import it?"*
> *"Show me the break-even analysis for the steel mill."*

### Resource consumption

> *"What resources did my construction sites use this year?"*
> *"How much fuel have my vehicles consumed since the start of the game?"*
> *"What did my factories consume last year compared to this year?"*

### Building lookup

> *"List all buildings that produce concrete."*
> *"What are the input and output rates of the coal processing plant?"*

## Project structure

```text
main.py          # Entry point — asyncio.run(run_mcp())
mcp_server.py    # 17 MCP tools, reads fresh from disk per call
parser.py        # Parses stats.ini → StatRecord dataclasses
requirements.txt # mcp[cli]==1.3.0
```