# Tamagotchi MCP

MCP server (stdio) that lets an LLM care for a virtual pet. Read-only web UI shows the pet's state in real time.

## Setup

```bash
npm install
npm run build
```

## Usage

**MCP server** -- add to your MCP client config:

```json
{
  "mcpServers": {
    "tamagotchi": {
      "command": "node",
      "args": ["/path/to/tamagotchi-mcp-2/dist/index.js"]
    }
  }
}
```

**Web UI** -- run in a separate terminal:

```bash
node dist/server.js
# → http://localhost:3333
```

## Tools

| Tool | Params | Effect |
|------|--------|--------|
| `check_status` | -- | Full state: stats, mood, age, recent actions |
| `feed_pet` | `food`: fish, meat, salad, candy, premium_food | Restores hunger/happiness/health |
| `play_with_pet` | `activity`: ball, laser, puzzle, walk | Boosts happiness, costs energy |
| `put_to_sleep` | -- | +40 energy (requires energy < 60) |
| `heal_pet` | -- | +30 health (requires health < 70) |
| `rename_pet` | `new_name`: 1-30 chars | Changes pet name |
| `change_species` | `species`: cat, dog, rabbit, dragon, alien | Transforms pet, resets stats to 70 |
| `revive_pet` | -- | Revives dead pet, all stats to 50 |

## Stat Decay

- Hunger: -1 every 2 min
- Happiness: -1 every 3 min
- Energy: -1 every 4 min
- Health: -1 every 5 min (only when hunger < 20)

Pet dies if hunger or health reaches 0.

## Architecture

```
src/index.ts   → MCP server (stdio), tool definitions
src/pet.ts     → Game logic, types, decay, persistence
src/server.ts  → HTTP server for web UI
data/pet.json  → Persistent pet state
web/index.html → Pixel art UI (canvas sprites, CSS animations, polling)
```

The web UI is **read-only**. All control happens through the LLM via MCP tools.