# ☕ Coffee Shop MCP

A hands-on **Model Context Protocol (MCP)** project. An LLM (VS Code Copilot in Agent
mode) takes your coffee order and "makes" it by coordinating a **Barista** server and
four **machine** servers.

Built with the official MCP Python SDK's `FastMCP`.

---

## How it works

The LLM is the **orchestrator**. Servers are **dumb specialists** — none of them talk to
each other. The Barista returns a *recipe*, and the LLM walks that recipe across the
machines.

```mermaid
flowchart TD
    User([You]) --> LLM[VS Code Copilot<br/>orchestrator]
    LLM --> Barista[Barista server<br/>menu · orders · recipes]
    LLM --> Grinder[Grinder]
    LLM --> Brew[Brew unit]
    LLM --> Steamer[Steamer]
    LLM --> Dispenser[Dispenser]
```

---

## Order flow

```mermaid
sequenceDiagram
    participant U as You
    participant L as Copilot (LLM)
    participant B as Barista
    participant M as Machines

    U->>L: What's on the menu?
    L->>B: get_menu()
    B-->>L: 4 drinks
    U->>L: Large latte, extra shot
    L->>B: place_order(...)
    B-->>L: order id + recipe
    L->>M: grind → brew → steam → dispense
    L->>B: mark_order_ready()
    L-->>U: Your latte is ready ☕
```

---

## Menu

| Drink | Milk? | Notes |
|-----------|:----:|-------|
| Espresso | No | Base shot |
| Americano | No | Espresso + hot water |
| Latte | Yes | Steamed milk, light foam |
| Cappuccino | Yes | Steamed milk, thick foam |

## Machines

| Component | Job | Used by |
|-----------|-----|---------|
| Grinder | Beans → grounds | All |
| Brew unit | Pull the shot (+ Americano water) | All |
| Steamer | Texture milk | Latte, Cappuccino |
| Dispenser | Assemble the cup | All |

> Espresso skips the Steamer. Latte vs Cappuccino differ only in foam thickness.

---

## Project layout

```
coffee-shop-mcp/
├── .vscode/mcp.json
└── src/coffee_shop_mcp/
    ├── server.py       # Barista
    ├── grinder.py
    ├── brew_unit.py
    ├── steamer.py
    └── dispenser.py
```

---

## Setup

```powershell
uv venv
uv add "mcp[cli]"
```

Test one server in the browser Inspector:

```powershell
uv run mcp dev src/coffee_shop_mcp/server.py
```

---

## Run in VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "coffee-shop": { "type": "stdio", "command": "uv",
      "args": ["run", "python", "src/coffee_shop_mcp/server.py"] },
    "grinder":     { "type": "stdio", "command": "uv",
      "args": ["run", "python", "src/coffee_shop_mcp/grinder.py"] },
    "brew-unit":   { "type": "stdio", "command": "uv",
      "args": ["run", "python", "src/coffee_shop_mcp/brew_unit.py"] },
    "steamer":     { "type": "stdio", "command": "uv",
      "args": ["run", "python", "src/coffee_shop_mcp/steamer.py"] },
    "dispenser":   { "type": "stdio", "command": "uv",
      "args": ["run", "python", "src/coffee_shop_mcp/dispenser.py"] }
  }
}
```

1. Open the folder in VS Code, click **Start** on each server in `mcp.json`.
2. Open Copilot Chat → **Agent** mode.
3. Say: *"What's on the menu? Then make me a large latte and run it on the machines."*

---

## Notes

- **In-memory only** — orders reset when the server restarts.
- **Simulated hardware** — machines return text results, nothing physical happens.
- Idle servers get stopped/restarted by VS Code automatically — that's normal.

*A learning project. ☕*