@iflow-mcp/amarisaster-stardewvalley-mcp 0.3.0

package/README.md

@@ -0,0 +1,235 @@
+# Stardew MCP Bridge
+
+AI companions for Stardew Valley, controlled through the [Model Context Protocol](https://modelcontextprotocol.io). 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
+
+| Mode | Behavior |
+|------|----------|
+| `follow` | Follow the player between locations, fight if monsters nearby |
+| `farm` | Scan for crops to water/harvest, clear debris |
+| `mine` | Fight monsters, break rocks, seek ladders |
+| `fish` | Find water, cast rod, auto-hook fish |
+| `idle` | Stay in place |
+| **`player`** | **Direct MCP control — the AI IS Player 2** |
+
+### 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
+
+| Tool | Description |
+|------|-------------|
+| `stardew_get_state` | Get current game state (time, weather, player stats, companion status) |
+| `stardew_spawn` | Spawn companions near the player |
+| `stardew_follow` | Set all companions to follow mode |
+| `stardew_stay` | Set all companions to idle |
+| `stardew_farm` | Enable autonomous farming |
+| `stardew_mine` | Enable combat/mining mode |
+| `stardew_fish` | Enable fishing mode |
+| `stardew_water_all` | Instantly water all unwatered crops |
+| `stardew_harvest_all` | Instantly harvest all ready crops |
+| `stardew_warp` | Warp all companions to a location |
+| `stardew_set_mode` | Set an individual companion's mode (including `player`) |
+| `stardew_chat` | Send a message to the game chat |
+| `stardew_action` | Send a custom action command |
+
+### Player Mode Tools (Direct Control)
+
+| Tool | Description |
+|------|-------------|
+| `stardew_get_surroundings` | See tiles, objects, crops, monsters, NPCs around the companion |
+| `stardew_get_inventory` | Get the companion's tools and items |
+| `stardew_get_companion_state` | Full companion state (position, health, stamina, surroundings, inventory) |
+| `stardew_move_to` | Walk to a tile via pathfinding |
+| `stardew_warp_companion` | Teleport a specific companion to a location |
+| `stardew_face_direction` | Turn to face a direction |
+| `stardew_use_tool` | Use pickaxe, axe, hoe, watering can, or sword at a tile |
+| `stardew_interact` | Interact with objects, crops, chests, ladders, NPCs |
+| `stardew_attack` | Attack nearest monster with equipped weapon |
+| `stardew_cast_fishing_rod` | Cast rod + auto-hook on nibble |
+| `stardew_set_auto_combat` | Toggle automatic monster attacks |
+| `stardew_eat_item` | Eat food from inventory |
+
+## Setup
+
+### Prerequisites
+
+- [Stardew Valley](https://www.stardewvalley.net/) (1.6+)
+- [SMAPI](https://smapi.io/) (4.0+)
+- [Node.js](https://nodejs.org/) (18+)
+
+### 1. Build the SMAPI Mod
+
+```bash
+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
+
+```bash
+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`):
+
+```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](https://github.com/JoeStrout/Farmtronics).
+
+
+---
+
+
+ ## Support
+
+  If this helped you, consider supporting my work
+
+  [![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20Me-FF5E5B?style=flat&logo=ko-fi&logoColor=white)](https://ko-fi.com/maii983083)

package/package.json

@@ -0,0 +1 @@
+{"name": "@iflow-mcp/amarisaster-stardewvalley-mcp", "version": "0.3.0", "description": "MCP server bridging AI agents to Stardew Valley via SMAPI.", "main": "build/index.js", "files": ["build"], "bin": {"iflow-mcp-amarisaster-stardewvalley-mcp": "./build/index.js"}, "scripts": {"build": "tsc", "watch": "tsc -w", "prepublishOnly": "npm run build"}, "dependencies": {"@modelcontextprotocol/sdk": "^1.0.1"}, "devDependencies": {"@types/node": "^20.11.24", "typescript": "^5.3.3"}}