# Trip Planner — two agents, one enforced boundary

A trip planner built on the **Model Context Protocol**. You name a place and a
number of days; a planner agent researches it and builds a real day-by-day
itinerary in SQLite.

The interesting part isn't that it plans trips. It's **how the two agents are
kept apart**.

## The boundary

```
Local Scout  ──▶  tavily-mcp          can search the web, cannot touch the trip
Planner      ──▶  itinerary_server    can write the trip, has no internet
```

The Planner has no search tool. Its *only* route to the outside world is calling
`research_place` — which is the Scout, attached to it as an ordinary tool via
`.as_tool()`. The Scout, in turn, has no itinerary tools, so it structurally
cannot write to the trip no matter what it decides to do.

Neither restriction is a prompt. Each agent is handed a different set of MCP
servers, and that's the whole enforcement mechanism. Prompts can be talked
around; a tool that isn't in the list cannot be called.

## Guard rails live in the server

`add_activity` rejects a day outside the trip's length:

```
> add_activity(trip_id=1, day=99, title="...")
Rejected: Day 99 is outside this 3-day trip - use a day from 1 to 3
```

That check is in [`db.py`](db.py), not in the instructions. The agent gets a
real error back and has to correct itself — which it does.

## Setup

```bash
uv sync
cp .env.example .env      # add your keys
```

Two keys are needed: `OPENAI_API_KEY` (or another provider via `PLANNER_MODEL`)
and `TAVILY_API_KEY` for the Scout's search. `npx` must be on your PATH — the
Tavily MCP server runs through it.

## Run it

```bash
uv run main.py              # create a trip, plan it, print it
uv run main.py --list       # list existing trips
uv run main.py --show 1     # re-print one itinerary
```

Point it at a different model with one env var:

```bash
PLANNER_MODEL=gpt-4o-mini
```

## What a run looks like

Two days in Porto, planned from scratch:

```
=== Trip 2: Porto, Portugal (2 days) ===

Day 1
  - São Bento Railway Station
      Iconic tiled station hall and an easy first stop in the historic centre.
      Allow 15–20 minutes. No booking needed.
  - Sé do Porto (Porto Cathedral)
      Main old-city cathedral and a strong historic anchor. Allow 30–45 minutes.
  - Ribeira
      Porto's classic riverfront old quarter. Allow 1–2 hours.
  - Palácio da Bolsa
      Ornate 19th-century interiors; one of the best paid visits in the centre.
      Book ahead for guided tours.
  - Torre dos Clérigos
      The classic bell tower and city panorama. Booking ahead helps at busy times.

Day 2
  - Dom Luís I Bridge
  - Port wine cellars in Vila Nova de Gaia
  - Jardim do Morro
  - Jardins do Palácio de Cristal
```

Day 1 is the historic centre, Day 2 is Gaia and the west side — grouped so a day
doesn't zig-zag across the city.

## The MCP server

| Tool | What it does |
| --- | --- |
| `get_itinerary(trip_id)` | The trip, its days, and every activity grouped by day |
| `add_activity(trip_id, day, title, details)` | Adds one activity — rejects out-of-range days |
| `remove_activity(activity_id)` | Removes one by id |

It speaks stdio, so the agent launches it as a subprocess. The Scout's server,
`tavily-mcp`, is filtered down to just `tavily_search` — hiding crawl, map and
extract keeps its tool list small and its behaviour predictable.

## Layout

```
db.py                 SQLite schema and access — trips, activities, guard rails
itinerary_server.py   MCP server: the only way the trip gets written
planner.py            Scout on Tavily, wrapped via .as_tool(); Planner on itinerary
main.py               CLI
```

Four files, about 330 lines.

## Notes

- The project sets `link-mode = "copy"` and passes `UV_LINK_MODE=copy` to every
  spawned MCP server, so it works on a cloud-synced drive (OneDrive, Dropbox),
  where `uv`'s default hardlinking fails with `os error 396`.
- `main.py` reconfigures stdout to UTF-8 — accented place names would otherwise
  print as mojibake in the Windows console.

## Verified

Both parts were tested for real, not assumed:

- The MCP server over stdio: tool listing, an itinerary read, and the day guard
  rail correctly rejecting `day=99` on a 3-day trip.
- A full end-to-end run on a 2-day Porto trip — the Scout searched, the Planner
  wrote nine activities, grouped geographically, with booking notes on the two
  that need them.