Stardew Valley MCP Bridge

A hybrid AI-controlled game mod that bridges Stardew Valley with AI assistants via the Model Context Protocol (MCP). Enables autonomous AI agents to control and play Stardew Valley through real-time game state synchronization.

Architecture

┌─────────────────────────────────────────────────────────┐
│ STARDEW VALLEY (Game)                                   │
│   SMAPI Mod (C# .NET 6)                                 │
│     ModEntry → GameStateSerializer                      │
│              → CommandExecutor (w/ Pathfinder)          │
│              → WebSocketServer                          │
└─────────────────────────────────────────────────────────┘
              ↕ ws://localhost:8765/game
┌─────────────────────────────────────────────────────────┐
│ MCP Server (Go)                                         │
│   GameClient: WebSocket connection, state tracking      │
│   StardewAgent: 12 tools + 30 cheats, autonomous loop   │
└─────────────────────────────────────────────────────────┘
              ↕ Copilot SDK
┌─────────────────────────────────────────────────────────┐
│ Claude Sonnet (via GitHub Copilot SDK)                  │
└─────────────────────────────────────────────────────────┘

Prerequisites

For the SMAPI Mod

• Stardew Valley (game)
• SMAPI (Stardew Modding API) v4.0.0+
• .NET 6.0 SDK

For the MCP Server

• Go 1.23+
• GitHub Copilot access (for Claude Sonnet via Copilot SDK)

Building

1. Build the C# Mod

cd mod/StardewMCP
dotnet build

This compiles StardewMCP.dll and places it in bin/Debug/net6.0/.

2. Build the Go MCP Server

cd mcp-server
go build -o stardew-mcp

This produces the stardew-mcp executable.

Installation

Install the SMAPI Mod

1. Build the mod (see above)
2. Copy the entire mod/StardewMCP/bin/Debug/net6.0/ folder to your Stardew Valley mods directory:
   • Windows: %AppData%\StardewValley\Mods\StardewMCP\
   • macOS: ~/.config/StardewValley/Mods/StardewMCP/
   • Linux: ~/.config/StardewValley/Mods/StardewMCP/
3. Copy manifest.json to the same folder

Or use SMAPI's mod folder structure:

Mods/
└── StardewMCP/
    ├── manifest.json
    ├── StardewMCP.dll
    └── (other build outputs)

Usage

1. Start Stardew Valley with SMAPI

Launch the game through SMAPI. The mod will automatically start a WebSocket server on ws://localhost:8765/game.

2. Load a Save File

The mod activates once you load into a game save.

3. Run the MCP Server

cd mcp-server
./stardew-mcp                    # Run with default autonomous mode
./stardew-mcp -auto=false        # Connect without starting AI agent
./stardew-mcp -goal "Clear the farm and plant parsnips"
./stardew-mcp -url ws://localhost:8765/game  # Custom WebSocket URL

The server connects to the game via WebSocket and begins the autonomous AI agent loop.

Available AI Tools

The AI agent has access to 12 tools for controlling the game:

Tool	Description
move_to	Navigate to specific coordinates using A* pathfinding
get_surroundings	Get current game state and 61x61 ASCII map vision
interact	Interact with objects/NPCs at a position
use_tool	Use the currently equipped tool
use_tool_repeat	Use tool multiple times in succession
face_direction	Turn player to face a direction
select_item	Select an item from inventory by name
switch_tool	Switch to a specific tool
eat_item	Consume a food item for energy
enter_door	Enter a building or warp point
find_best_target	Find optimal target for current tool
clear_target	Clear the current target

Cheat Mode

Cheat mode provides instant god-mode capabilities for rapid testing or stress-free gameplay. Must call cheat_mode_enable first before any other cheat commands work.

Mode Control

Tool	Description
cheat_mode_enable	Enable cheat mode (required first)
cheat_mode_disable	Disable cheat mode and all persistent effects
cheat_time_freeze	Toggle time freeze on/off
cheat_infinite_energy	Toggle infinite stamina on/off

Teleportation

Tool	Description
cheat_warp	Teleport to location (Farm, Town, Mountain, Beach, Forest, Mine, Desert)
cheat_mine_warp	Warp to specific mine level (1-120 = Mines, 121+ = Skull Cavern)

Farming Automation

Tool	Description
cheat_clear_debris	Remove all weeds, stones, twigs, grass
cheat_cut_trees	Chop all trees, collect wood/hardwood
cheat_mine_rocks	Mine all rocks/boulders, collect ores
cheat_hoe_all	Till all diggable tiles
cheat_water_all	Water all tilled soil
cheat_plant_seeds	Plant seeds on all empty hoed tiles (requires seedId)
cheat_fertilize_all	Apply fertilizer to all hoed tiles
cheat_grow_crops	Instantly grow all crops to harvest-ready
cheat_harvest_all	Harvest all ready crops
cheat_dig_artifacts	Dig up all artifact spots

Pattern Drawing

Tool	Description
cheat_hoe_tiles	Hoe specific tiles by coordinates (tiles="x,y;x,y")
cheat_clear_tiles	Clear specific tiles
cheat_hoe_custom_pattern	Draw shapes using ASCII grid input

Resources & Items

Tool	Description
cheat_set_money	Set gold amount
cheat_add_item	Add item by ID (e.g., "(O)465" for starfruit seeds)
cheat_spawn_ores	Add ores: copper, iron, gold, iridium, coal
cheat_set_energy	Restore stamina to max
cheat_set_health	Restore health to max

Social

Tool	Description
cheat_set_friendship	Set friendship with NPC (hearts 1-10 or points)
cheat_max_all_friendships	Max out all NPC friendships
cheat_give_gift	Give gift to NPC instantly

Upgrades

Tool	Description
cheat_upgrade_backpack	Upgrade backpack (12, 24, or 36 slots)
cheat_upgrade_tool	Upgrade tool (0=Basic to 4=Iridium)
cheat_upgrade_all_tools	Upgrade all tools to specified level
cheat_unlock_all	Max everything: backpack, tools, recipes, skills

Example: Instant Farm Setup

1. cheat_mode_enable
2. cheat_warp Farm
3. cheat_clear_debris, cheat_cut_trees, cheat_mine_rocks
4. cheat_hoe_all
5. cheat_plant_seeds (with seedId "472" for parsnips)
6. cheat_grow_crops
7. cheat_harvest_all

WebSocket Protocol

The mod and server communicate via JSON over WebSocket.

Request format:

{
  "id": "uuid",
  "type": "command",
  "action": "move_to",
  "params": {"x": 10, "y": 20}
}

Response format:

{
  "id": "uuid",
  "type": "response",
  "success": true,
  "message": "Moved to position",
  "data": {}
}

Configuration

• WebSocket Port: Default 8765 (configured in WebSocketServer.cs)
• Tool Cooldown: 30 game ticks between tool swings (~0.5s at 60fps)
• State Broadcast: Game state sent every 1 second
• Pathfinding: A* with 50,000 iteration limit, 30-tile scan radius

Troubleshooting

Mod not loading: Ensure SMAPI 4.0.0+ is installed and the mod files are in the correct Mods folder structure.

WebSocket connection failed: Check that the game is running and a save is loaded. The server retries connection every 5 seconds.

Pathfinding failures: The A* algorithm attempts up to 5 path recalculations. Some areas may be unreachable due to obstacles.