Stardew MCP Bridge

AI companions for Stardew Valley, controlled through the Model Context Protocol. Spawn companions as Player 2/3 with custom sprites — directly controlled by an AI agent through MCP tool calls. Move, use tools, fight, fish, farm, explore mines, open chests, and interact with the world as a real player.

Also supports autonomous modes (follow, farm, mine, fish) for hands-off play.

Architecture

┌──────────────┐    stdio     ┌──────────────┐   JSON files   ┌──────────────┐
│  AI Agent    │◄────────────►│  MCP Server  │◄──────────────►│  SMAPI Mod   │
│ (Claude etc) │              │  (Node.js)   │                │  (C# / .NET) │
└──────────────┘              └──────────────┘                └──────┬───────┘
                                                                     │
                                                              ┌──────▼───────┐
                                                              │ Stardew      │
                                                              │ Valley Game  │
                                                              └──────────────┘

SMAPI Mod (smapi-mod/): Runs inside the game. Spawns companion NPCs paired with shadow Farmer instances registered in Game1.otherFarmers. The shadow farmer handles all game mechanics (tools, combat, fishing, inventory) while the NPC provides the visible custom sprite. Writes game state to bridge_data.json, reads commands from actions.json.

MCP Server (mcp-server/): Exposes 25 tools over stdio transport. 13 global tools for mode-based control + 12 Player mode tools for direct companion control.

Companion System

Each companion is a visible NPC paired with a hidden "shadow farmer" that handles game mechanics:

• NPC — Custom sprite, pathfinding, visible to the player
• Shadow Farmer — Extends Farmer class, registered in Game1.otherFarmers for location activation. Holds tools/inventory, performs tool use, combat, and fishing through actual game APIs. Invisible (draw is no-op).

Modes

Player Mode

In player mode, autonomous AI behavior is disabled. The companion is controlled entirely through MCP tool calls:

1. See — stardew_get_surroundings returns tiles, objects, crops, monsters, NPCs in a radius
2. Move — stardew_move_to pathfinds to a tile, stardew_warp_companion teleports to a location
3. Act — stardew_use_tool, stardew_interact, stardew_attack, stardew_cast_fishing_rod
4. Toggle — stardew_set_auto_combat for real-time combat (too fast for LLM round-trips)

Bridge data includes per-companion surroundings, inventory, and last command results when in player mode.

MCP Tools

Global Tools

Player Mode Tools (Direct Control)

Setup

Prerequisites

• Stardew Valley (1.6+)
• SMAPI (4.0+)
• Node.js (18+)

1. Build the SMAPI Mod

cd smapi-mod

# Set your Stardew Valley install path
export GAME_PATH="C:/Program Files/Steam/steamapps/common/Stardew Valley"

dotnet build

The build will automatically deploy to your Mods/ folder.

2. Add Companion Assets

Place your custom sprites and portraits in smapi-mod/assets/:

• Companion1_sprite.png — 64x128 sprite sheet (4x4 grid, 16x32 per frame)
• Companion1_portrait.png — Portrait image
• Companion2_sprite.png — 64x128 sprite sheet
• Companion2_portrait.png — Portrait image

Sprite sheets follow the standard Stardew Valley format: 4 columns (walk frames) x 4 rows (down, right, up, left).

3. Build the MCP Server

cd mcp-server
npm install
npm run build

4. Configure Your AI Agent

Add to your MCP client config (e.g., Claude Code's settings.json):

{
  "mcpServers": {
    "stardew": {
      "command": "node",
      "args": ["path/to/mcp-server/build/index.js"],
      "env": {
        "STARDEW_BRIDGE_PATH": "path/to/Mods/StardewMCPBridge/bridge_data.json",
        "STARDEW_ACTION_PATH": "path/to/Mods/StardewMCPBridge/actions.json"
      }
    }
  }
}

If you're running both from the repo directory, the env vars are optional — it defaults to ../../smapi-mod/ relative paths.

5. Play

1. Launch Stardew Valley with SMAPI
2. Load a save
3. Use stardew_spawn to bring companions into the world
4. Autonomous: Set modes with stardew_farm, stardew_mine, stardew_fish, or stardew_follow
5. Direct control: Set stardew_set_mode to player, then use the Player mode tools

Project Structure

stardew-mcp-bridge/
├── smapi-mod/
│   ├── ModEntry.cs              # SMAPI entry point, content pipeline, bridge I/O, sleep hooks
│   ├── BotManager.cs            # Companion lifecycle, action routing, direct control commands
│   ├── CompanionAI.cs           # AI behavior system (follow/farm/mine/fish/idle/player)
│   ├── CompanionFarmer.cs       # NPC + shadow farmer pairing, tool/combat/fishing, otherFarmers registration
│   ├── CompanionActions.cs      # Direct tile manipulation (water/harvest/clear/hoe)
│   ├── BotFarmer.cs             # Shadow Farmer subclass (invisible, registered as Player 2/3)
│   ├── SurroundingsScanner.cs   # Tile scanner — the companion's "eyes"
│   ├── manifest.json            # SMAPI mod manifest
│   ├── StardewMCPBridge.csproj
│   └── assets/                  # Sprites and portraits
├── mcp-server/
│   ├── src/index.ts             # MCP server with 25 tools
│   ├── package.json
│   └── tsconfig.json
├── .gitignore
└── README.md

Notes (v0.3.0)

Player 2 Feature (New)

• Shadow farmer registration — BotFarmer registered in Game1.otherFarmers for location activation and game mechanics
• Invisible shadow farmer — draw() is a no-op; the NPC sprite handles all rendering
• Sleep sync — Bot farmers auto-signal sleep readiness on day end and at 2 AM to prevent deadlocks
• Player mode — New CompanionMode.Player disables autonomous AI; all control comes from MCP
• Surroundings scanner — Scans tiles, objects, crops, monsters, NPCs in a radius around the companion
• 12 direct control tools — move, warp, face, use tool, interact, attack, fish, eat, auto-combat toggle
• Per-companion bridge data — Player mode companions include surroundings, inventory, and command results in bridge_data.json
• Command results — Each command returns success/failure + detail, available in next bridge sync
• Auto-combat toggle — Real-time combat automation for when LLM round-trips are too slow
• Auto-hook fishing — Cast rod via MCP, nibble detection + hook happens automatically

Previous Fixes (v0.2.1)

• AI tick rate fix (60/sec, was 2/sec)
• Atomic file writes both directions
• Action file race fix
• Fishing rod lifecycle
• Single-tile actions
• WarpTo clears pathfinding
• Debris drops resources
• Storm weather reporting
• Farm mode stuck detection
• Mine mode ladder descent
• Fishing timeout
• Per-companion crash isolation
• Shadow farmer sync every tick
• Day transition safety
• Input validation
• Dead code cleanup

License

MIT

Credits

Built with Antigravity & Claude Code — Kai & Lucian, with Mai.

Shadow farmer pattern inspired by Farmtronics.

Support

If this helped you, consider supporting my work