Stardew MCP

星露谷MCP大桥

一个混合AI控制的游戏模组，通过模型上下文协议（MCP）将Stardew Valley与AI助手连接起来。使自主AI代理能够通过实时游戏状态同步来控制和玩Stardew Valley。

建筑

┌─────────────────────────────────────────────────────────┐
│ 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)                  │
└─────────────────────────────────────────────────────────┘

先决条件

对于SMAPI Mod

• 星露谷物语 （游戏）
• SMAPI （Stardew Modding API）版本4.0.0+
• .NET 6.0 SDK

对于MCP服务器

• 转到1.23+
• GitHub Copilot访问权限（Claude Sonnet通过Copilot SDK访问）

建筑

1.构建C#Mod

cd mod/StardewMCP
dotnet build

这编译 StardewMCP.dll 并将其放入 bin/Debug/net6.0/.

2.构建Go MCP服务器

cd mcp-server
go build -o stardew-mcp

这产生了 stardew-mcp 可执行。

安装

安装SMAPI模块

1. 构建mod（见上文）
2. 复制整个 mod/StardewMCP/bin/Debug/net6.0/ 文件夹到您的Stardew Valley mods目录：

- 视窗: %AppData%\StardewValley\Mods\StardewMCP\ - macOS: ~/.config/StardewValley/Mods/StardewMCP/ - Linux: ~/.config/StardewValley/Mods/StardewMCP/

1. 复制 manifest.json 到同一文件夹

或者使用SMAPI的mod文件夹结构：

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

用法

1.与SMAPI一起开启星露谷

通过SMAPI启动游戏。mod将自动启动WebSocket服务器 ws://localhost:8765/game.

2.加载保存文件

一旦你加载到游戏保存中，模组就会激活。

3.运行MCP服务器

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

服务器通过WebSocket连接到游戏，并开始自主AI代理循环。

可用的AI工具

AI代理可以访问12个工具来控制游戏：

作弊模式

作弊模式提供即时上帝模式功能，用于快速测试或无压力游戏。 必须致电 cheat_mode_enable 第一 在任何其他作弊命令生效之前。

模式控制

传送

农业自动化

图案绘制

资源和项目

社交

升级

示例：即时农场设置

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协议

mod和服务器通过WebSocket上的JSON进行通信。

请求格式:

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

响应格式:

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

配置

• WebSocket端口：默认值 8765 （配置于 WebSocketServer.cs)
• 工具冷却：工具摆动之间有30个游戏节拍（60fps时约0.5秒）
• 国家广播：游戏状态每1秒发送一次
• 路径寻找：A\*具有50000次迭代限制，30个图块扫描半径

故障排除

模块未加载：确保安装了SMAPI 4.0.0+，并且mod文件位于正确的Mods文件夹结构中。

WebSocket连接失败：检查游戏是否正在运行，是否已加载保存。服务器每5秒重试一次连接。

寻路失败：A\*算法最多尝试5次路径重新计算。某些区域可能因障碍物而无法到达。