# 🧑‍🌾 HayDay MCP Server

![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/github/v/release/Mohib1992/hayday-mcp-server)

<p align="center">
  <img src="https://static.wikia.nocookie.net/hayday/images/8/82/Hay_Day-Logo.jpg/revision/latest?cb=20210703105216" alt="Hay Day" width="400">
</p>

**Live HayDay game data** — crops, products, animals, machines, and level unlocks — served as MCP tools for any AI agent.

Works with opencode, Claude Desktop, Cursor, VS Code, and any MCP-compatible client.

> **Not a bot. Not an auto-player.** This is a read-only data lookup tool. It does not interact with the HayDay game, does not send inputs, does not automate gameplay, and cannot be used to play on your behalf. It only answers questions about game mechanics — like a wiki you can query from your AI.

## Why?

HayDay is a deep game with hundreds of items, recipes, and levels. Keeping track of what to plant, what to craft, and what unlocks next is tedious. This MCP server gives your AI assistant the full game data so it can help you **plan your farm** — not play it for you.

## How It Works

```
AI agent → MCP protocol → HayDay Data MCP → hayday.info API (live) → structured data
                                    ↓
                           1-hour in-memory cache
```

Data is fetched **live** from [hayday.info](https://hayday.info) on every tool call, with a 1-hour cache to avoid rate limits. When Supercell updates the game, your AI sees the new data automatically — no manual updates needed.

## Quick Start

```bash
git clone https://github.com/Mohib1992/hayday-mcp-server.git
cd hayday-mcp-server
npm install
node server.js
```

The server starts and listens for MCP connections via stdio. Nothing happens until an AI client connects.

## Tools

| Tool | Description | Example |
|------|-------------|---------|
| `search_items` | Search items by name or machine | `"wheat"`, `"bakery"`, `"cheese"` |
| `get_item` | Full details for a specific product | `"Bread"` |
| `get_machines` | List all 48 machine/category names | — |
| `get_by_machine` | All products from a machine | `"Dairy"`, `"Bakery"`, `"Crops"` |
| `get_crops` | All field crops + trees/bushes | — |
| `get_animals` | All animal products (eggs, milk, etc.) | — |
| `get_level_unlocks` | What unlocks at a specific level | `level: 30` |
| `get_unlocks_upto` | Everything available up to a level | `level: 20` |
| `get_best_profit` | Top items by profit/hour | `limit: 10, minLevel: 1` |
| `compare_profit` | Compare profit/time for specific items | `["Wheat", "Corn", "Bread"]` |
| `clear_cache` | Force refresh from live source | — |

### Example Queries

**"What's the most profitable crop at level 15?"**

→ Call `get_best_profit(minLevel: 1, limit: 5)` and filter by `machine: "Crops"`.

**"Compare bread vs corn bread"**

→ Call `compare_profit(products: ["Bread", "Corn bread"])`.

**"What do I unlock at level 30?"**

→ Call `get_level_unlocks(level: 30)`.

## Client Setup

### opencode

Add to `opencode.jsonc` in your project root:

```json
{
  "mcpServers": {
    "hayday-data": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "/path/to/hayday-data-mcp"
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hayday-data": {
      "command": "node",
      "args": ["server.js"],
      "cwd": "/path/to/hayday-data-mcp"
    }
  }
}
```

### Cursor

Settings → Features → MCP → Add new server:

| Field | Value |
|-------|-------|
| Name | `hayday-data` |
| Type | `command` |
| Command | `node /path/to/hayday-data-mcp/server.js` |

### VS Code (Continue.dev)

Add to `~/.continue/config.json`:

```json
{
  "experimental": {
    "mcpServers": {
      "hayday-data": {
        "command": "node",
        "args": ["server.js"],
        "cwd": "/path/to/hayday-data-mcp"
      }
    }
  }
}
```

## Data Source

All data comes from [hayday.info](https://hayday.info) — a community-run HayDay database. The `/api/production-data` endpoint returns 348 items across 48 categories. Data is cached in memory for 1 hour.

**What's included:**
- Field crops + trees & bushes
- Animal products (eggs, milk, bacon, wool, etc.)
- All machine-made products (Bakery, Dairy, BBQ Grill, etc.)
- Level unlock information
- Profit/hour calculations (provided by source)
- XP and XP/hour

**What's not included:**
- Ingredient/recipe details (which items combine to make a product)
- Building upgrade costs
- Derby / boat / town data

## Architecture

```
hayday-mcp-server/
  server.js            # MCP server (JSON-RPC over stdio, zero framework deps)
  lib/
    hayday.js          # Fetches & indexes live data from hayday.info
    cache.js           # 1-hour TTL cache
  test/
    api.test.js        # API layer smoke tests
    mcp.test.js        # MCP protocol smoke tests
  package.json
  CHANGELOG.md
  LICENSE              # MIT
```

## Troubleshooting

| Problem | Likely Cause | Fix |
|---------|-------------|-----|
| Server starts but tools return nothing | Client not connected to server | Check MCP config path in your client settings |
| "API returned 429" or slow responses | Rate limited by hayday.info | Wait 1 hour (cache auto-cools down), or call `clear_cache` |
| "Product not found" for a known item | Case mismatch or item name changed | Use `search_items` first to find exact name |
| "Machine not found" | Name mismatch | Use `get_machines` to get exact machine names |
| Server crashes after stdin closes | Expected behavior (stdio transport ended) | Just restart the server |
| Data seems outdated | Cache hit (1hr TTL) | Call `clear_cache` to force a live fetch |

## Testing

```bash
npm test
```

Runs 20+ smoke tests covering the API layer and MCP protocol using Node.js built-in `node:test`.

## Contributing

1. Fork the repo
2. Create a feature branch
3. Run `npm test` to verify
4. Open a pull request

## License

MIT

---

## Legal notice

This project is an independent data tool and is not affiliated with, endorsed by, or connected to Supercell Oy. HayDay is a trademark of Supercell Oy. All game data is sourced from publicly available community resources. This tool is read-only and does not interact with the HayDay game client, its servers, or its APIs. It is designed for informational and educational purposes only.