![banner](./assets/image/banner.jpg)

# 🍽️ **booking-mcp**

`booking-mcp` is a Model Context Protocol server for managing restaurant reservations, served over Streamable HTTP. It exposes tools to book a table, check availability, and cancel a reservation; resources to read the reservation book; and a prompt for drafting confirmations. When booking, the server gathers the guest's contact details from the user through elicitation.


## 📋 **Requirements**

* Python 3.13
* [uv](https://docs.astral.sh/uv/)


## 🚀 **Usage**

### 📦 **Setup**

Create the virtual environment, install the SDK (`mcp[cli,rich]`) and dependencies, and install the package in editable mode:

```bash
uv sync
```

### 🖥️ **Server**

Start the server, which serves Streamable HTTP at `http://127.0.0.1:8000/mcp`:

```bash
uv run booking-mcp
```

### 🚶 **Walkthrough**

A standalone interactive client that runs in process, so nothing else needs to be running. It gives you a menu of actions and lets you answer the elicitation prompts yourself.

```bash
uv run python scripts/walkthrough.py
```

> [!TIP]
>
> Reservations persist to `var/bookings.json` by default. Set `BOOKING_DB_PATH` to store them elsewhere:
>
> ```bash
> BOOKING_DB_PATH=/tmp/demo.json uv run python scripts/walkthrough.py
> ```


## 🧩 **MCP Surface**

| Kind     | Name                                 | Notes                                        |
| -------- | ------------------------------------ | -------------------------------------------- |
| Tool     | `book_table(date, time, party_size)` | elicits name, phone, and notes from the user |
| Tool     | `cancel_booking(id)`                 | marks a reservation cancelled                |
| Tool     | `check_availability(date, time)`     | remaining tables for a slot                  |
| Resource | `bookings://all`                     | every reservation, as JSON                   |
| Resource | `bookings://{id}`                    | one reservation, as JSON                     |
| Resource | `availability://{date}`              | capacity for each slot on a date, as JSON    |
| Prompt   | `confirmation_message(id)`           | drafts a guest confirmation message          |


## 📁 **Layout**

```
booking-mcp/
├── src/booking_mcp/
│   ├── app.py               # the shared MCPServer instance
│   ├── config.py            # storage path + capacity limits
│   ├── models.py            # Reservation domain model
│   ├── store.py             # JSON file repository
│   ├── server.py            # entrypoint: registers features, runs the server
│   └── features/
│       ├── reservations.py  # book/cancel + reservation resources + prompt
│       └── availability.py  # availability tool + resource
├── scripts/
│   └── walkthrough.py       # manual interactive client
└── var/                     # runtime state, gitignored (holds bookings.json)
```