Stardew Valley MCP

Stardew MCP大桥

星露谷的AI同伴，通过 模型上下文协议.产卵同伴如 玩家2/3 使用自定义精灵——由AI代理通过MCP工具调用直接控制。移动、使用工具、战斗、捕鱼、耕种、探索矿井、打开箱子，并作为一个真正的玩家与世界互动。

还支持自主模式（跟随、农场、采矿、捕鱼），便于轻松玩耍。

建筑

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

SMAPI模块 (smapi-mod/)：在游戏中运行。生成与阴影配对的伙伴NPC Farmer 在中注册的实例 Game1.otherFarmers。影子农民处理所有游戏机制（工具、战斗、捕鱼、库存），而NPC提供可见的自定义精灵。将游戏状态写入 bridge_data.json，从读取命令 actions.json.

MCP服务器 (mcp-server/)：通过stdio传输暴露25个工具。13个全局工具用于基于模式的控制+12个玩家模式工具用于直接同伴控制。

配套系统

每个同伴都是一个可见的NPC，与一个隐藏的“影子农夫”配对，负责处理游戏机制：

• 非玩家角色 --自定义角色，寻路，玩家可见
• 影子农夫 --扩展 Farmer 类，注册于 Game1.otherFarmers 用于位置激活。持有工具/库存，通过实际的游戏API执行工具使用、战斗和捕鱼。看不见（绘制不是操作）。

模式

播放器模式

在 player 模式下，自主AI行为被禁用。该伴侣完全通过MCP工具调用进行控制：

1. 看 — stardew_get_surroundings 返回半径内的瓷砖、物体、作物、怪物、NPC
2. 移动 — stardew_move_to 找到拼贴块的路径， stardew_warp_companion 传送到某个位置
3. 法案 — stardew_use_tool, stardew_interact, stardew_attack, stardew_cast_fishing_rod
4. 切换 — stardew_set_auto_combat 用于实时作战（对于LLM往返来说太快）

桥牌数据包括每个同伴的环境、库存和玩家模式下的最后一个命令结果。

MCP工具

全球工具

玩家模式工具（直接控制）

设置

先决条件

• 星露谷物语 (1.6+)
• SMAPI (4.0+)
• (18+)

1.构建SMAPI模块

cd smapi-mod

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

dotnet build

该构建将自动部署到您的 Mods/ 文件夹。

2.添加配套资产

将您的自定义精灵和肖像放在 smapi-mod/assets/:

• Companion1_sprite.png --64x128子画面（4x4网格，每帧16x32）
• Companion1_portrait.png --肖像图片
• Companion2_sprite.png --64x128子画面
• Companion2_portrait.png --肖像图片

Sprite表格遵循标准的Stardew Valley格式：4列（行走框架）x 4行（下、右、上、左）。

3.构建MCP服务器

cd mcp-server
npm install
npm run build

4.配置您的AI代理

添加到您的MCP客户端配置中（例如，Claude Code的 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"
      }
    }
  }
}

如果您从repo目录运行这两个变量，则env-var是可选的——默认为 ../../smapi-mod/ 相对路径。

5.玩

1. 与SMAPI一起推出Stardew Valley
2. 加载保存
3. 使用 stardew_spawn 把同伴带到世界上
4. 自主：使用设置模式 stardew_farm, stardew_mine, stardew_fish，或 stardew_follow
5. 直接控制：设置 stardew_set_mode 到 player，然后使用播放器模式工具

项目结构

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

注释（v0.3.0）

玩家2功能（新）

• 影子农民登记 --BotFarmer注册于 Game1.otherFarmers 用于位置激活和游戏机制
• 隐形影子农民 — draw() 这是一个禁忌；NPC角色处理所有渲染
• 睡眠同步 --机器人农民在日终和凌晨2点自动发出睡眠准备信号，以防止死锁
• 玩家模式 新 CompanionMode.Player 禁用自主AI；所有控制都来自MCP
• 环境扫描仪 --扫描同伴周围半径内的瓷砖、物体、农作物、怪物、NPC
• 12个直接控制工具 --移动、扭曲、面部、使用工具、互动、攻击、钓鱼、进食、自动战斗切换
• 根据配套桥梁数据 --玩家模式伙伴包括周围环境、库存和bridge_data.json中的命令结果
• 命令结果 --每个命令返回成功/失败+详细信息，可在下次网桥同步中使用
• 自动战斗切换 --LLM往返速度太慢时的实时战斗自动化
• 自动钩钓 --通过MCP铸造棒材，自动检测咬边+钩住

以前的修复程序（v0.2.1）

• AI滴答频率固定（60/sec，为2/sec）
• 原子文件双向写入
• 操作文件竞争修复
• 钓竿生命周期
• 单个互动程序动作
• WarpTo清除寻路
• 碎片掉落资源
• 风暴天气报告
• 农场模式卡住检测
• 矿井模式阶梯下降
• 钓鱼超时
• 根据同伴碰撞隔离
• 影子农民同步每一个滴答声
• 日间过渡安全
• 输入验证
• 死代码清理

许可证

麻省理工学院

学分

用反重力和克劳德密码建造——凯和卢西恩，与梅。

MCP概念的火花(https://github.com/SparksQACR)

灵感源自 Farmtronics.

______________________________________________________________________

支持

如果这对你有帮助，考虑支持我的工作