# 🧑‍🍳 Chef's Brain

> A smart pantry MCP server that turns Claude into your personal sous chef — knowing exactly what's in your kitchen and suggesting what to cook right now.

---

## What Is This?

Chef's Brain is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives Claude live, structured access to your pantry. Instead of describing your ingredients in every chat message, Claude can query your pantry directly, track what you use, and reason over real ingredient data to suggest recipes you can actually make.

Built as a CS class project exploring MCP server design, with a personal twist: the author is a foodie and baker, so the tools are designed around real kitchen workflows.

---

## Features

| Tool | Description |
|---|---|
| `get_pantry` | View all pantry items grouped by category |
| `add_ingredient` | Add or update an ingredient with amount, unit, category, and optional expiry |
| `remove_ingredient` | Remove an ingredient (used up or don't have it) |
| `use_ingredient` | Decrease an ingredient's quantity after cooking |
| `suggest_recipes` | Get recipe ideas based on what you have + your current craving/mood |
| `check_recipe_feasibility` | Check if you have everything needed for a specific recipe |
| `expiring_soon` | See what's expiring soon and get "use it up" recipe ideas |

---

## Design Choices

### Smart Onboarding with a Default Pantry

**Problem:** Starting a pantry tracker from scratch is tedious. Nobody wants to type in 30 staples before they can do anything useful.

**Solution:** On first run, the server pre-loads a curated default pantry of ~30 common staples (eggs, flour, butter, olive oil, etc.) and instructs Claude to present them all at once and ask *"Which of these do you NOT have?"* Claude then calls `remove_ingredient` for each missing item. This gets you to an accurate pantry in one conversational exchange.

This was a key UX decision: the server doesn't try to build a wizard UI — it just sets the right context in the tool response and lets Claude handle the conversation naturally.

### Structured Quantities

Each ingredient stores `amount` (number) and `unit` (string) as separate fields rather than a combined string like `"2 cups"`. This makes the `check_recipe_feasibility` and `use_ingredient` tools more precise and opens the door for unit conversion in a future version.

```json
{
  "flour": {
    "amount": 5,
    "unit": "lbs",
    "category": "dry goods",
    "expiry_date": null
  }
}
```

### Optional Expiry Dates

Expiry tracking is opt-in per item. Pantry staples like salt or olive oil don't need expiry dates — requiring them for everything would create friction. Perishables like milk or meat can have a date set. The `expiring_soon` tool filters to only items with a date set.

### Claude's Culinary Knowledge Over an External API

`suggest_recipes` does not call Spoonacular, Edamam, or any recipe API. Instead, it formats your pantry as a structured ingredient list and returns it with an instruction prompt that tells Claude to reason over it using its own knowledge. This has three advantages:

1. **No API key required** — works immediately, no setup
2. **More flexible** — Claude can handle vague cravings ("something cozy") that a search API can't
3. **Better explanations** — Claude can adapt recipes to your exact quantities and suggest substitutions

The tradeoff is that suggestions aren't tied to real recipes with exact measurements. For a pantry-awareness tool rather than a recipe database, this is the right call.

### Fuzzy Ingredient Matching

`check_recipe_feasibility` uses substring matching to handle common name mismatches (e.g., a recipe calling for `"all purpose flour"` matches the pantry key `"all-purpose flour"`). It's not perfect — a production version would use embeddings — but it handles the most common cases cleanly.

### Local JSON Storage

The pantry is stored in `pantry.json` in the project directory. No database, no cloud, no accounts. This keeps setup to a single `pip install` and makes the data easy to inspect and back up. The file path is configurable via the `PANTRY_FILE` environment variable.

---

## Installation

**Requirements:** Python 3.11+, Claude Code (or any MCP-compatible client)

```bash
# 1. Clone the repo
git clone https://github.com/yourusername/chefs-brain
cd chefs-brain

# 2. Install dependencies
pip install mcp

# 3. Test the server runs
python server.py
```

---

## Connecting to Claude Code

Add the server to your Claude Code MCP config. The config file lives at:
- **macOS:** `~/.claude/claude_desktop_config.json` (Claude desktop) or configure via `claude mcp add` in Claude Code

### Using `claude mcp add` (recommended for Claude Code)

```bash
claude mcp add chefs-brain python /absolute/path/to/chefs-brain/server.py
```

### Manual config (Claude desktop app)

Edit `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "chefs-brain": {
      "command": "python",
      "args": ["/absolute/path/to/chefs-brain/server.py"],
      "env": {
        "PANTRY_FILE": "/absolute/path/to/chefs-brain/pantry.json"
      }
    }
  }
}
```

Restart Claude after editing the config.

---

## Example Interactions

### First-time setup
```
You: "What's in my pantry?"
Claude: [calls get_pantry, sees first_run flag]
Claude: "Welcome to Chef's Brain! I've pre-loaded your pantry with common staples:

  Dairy: eggs (12), milk (1 gallon), butter (1 cup)...
  Dry Goods: flour (5 lbs), sugar (4 lbs)...
  ...

Which of these items do you NOT currently have? I'll remove them for you."

You: "I don't have heavy cream or parmesan."
Claude: [calls remove_ingredient("heavy cream"), remove_ingredient("parmesan")]
Claude: "Got it! I've removed those. Your pantry is ready."
```

### Recipe suggestions
```
You: "I want something chocolatey but I only have 30 minutes."
Claude: [calls suggest_recipes(craving="chocolatey", max_time_mins=30)]
Claude: "With what you have, here are 3 options:
  1. Chocolate Mug Cake (10 min, easy) — uses eggs, cocoa powder, butter, sugar, flour
  2. Chocolate Oat No-Bake Cookies (20 min, easy) — uses oats, cocoa, butter, honey
  3. Pan Brownies (30 min, medium) — uses flour, cocoa, eggs, butter, sugar, vanilla"
```

### Checking a specific recipe
```
You: "Can I make tiramisu?"
Claude: [calls check_recipe_feasibility("tiramisu", [...])]
Claude: "You're missing 2 ingredients: mascarpone cheese and espresso/coffee.
  You have everything else: eggs, sugar, vanilla extract."
```

### Expiry check
```
You: "Anything about to go bad?"
Claude: [calls expiring_soon(days=7)]
Claude: "Your eggs expire in 3 days! You could make a frittata or French toast to use them up."
```

---

## Project Structure

```
chefs-brain/
├── server.py        # MCP server — all tools live here
├── pantry.json      # Auto-created on first run (gitignored)
├── pyproject.toml   # Package metadata
└── README.md        # This file
```

---

## Potential Extensions

- **Unit conversion** — normalize amounts across units (e.g. "do I have enough butter: I have 1 cup, recipe needs 200g?")
- **Shopping list generation** — collect all missing items across multiple recipes into one list
- **Multiple clients** — connect to both Claude Code and a web front-end simultaneously via the same MCP server
- **Meal planning** — plan a week of meals optimized around what you have + what's expiring
- **Nutritional awareness** — tag ingredients with macros and suggest recipes that hit a target

---

## Why MCP?

MCP lets Claude access live, structured, personal data without needing that data baked into a prompt. The pantry state is always current, tools are composable (Claude can call `expiring_soon` and then `suggest_recipes` in sequence), and the server is client-agnostic — the same `server.py` could power Claude Code, Claude desktop, or any other MCP-compatible client.

For a pantry tracker specifically, this is much better than a standalone app: you get Claude's full culinary reasoning applied directly to your actual kitchen data.