Trek_CN/MCP.md

# MCP Integration

TREK includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that lets AI
assistants — such as Claude Desktop, Cursor, or any MCP-compatible client — read and modify your trip data through a
structured API.

> **Note:** MCP is an addon that must be enabled by your TREK administrator before it becomes available.

## Table of Contents

- [Setup](#setup)
  - [Option A: OAuth 2.1 (recommended)](#option-a-oauth-21-recommended)
  - [Option B: Static API Token (deprecated)](#option-b-static-api-token-deprecated)
- [Authentication](#authentication)
- [OAuth Scopes](#oauth-scopes)
- [Limitations & Important Notes](#limitations--important-notes)
- [Resources (read-only)](#resources-read-only)
- [Tools (read-write)](#tools-read-write)
  - [Compound Tools](#compound-tools)
- [Prompts](#prompts)
- [Example](#example)

---

## Setup

### 1. Enable the MCP addon (admin)

An administrator must first enable the MCP addon from the **Admin Panel > Addons** page. Until enabled, the `/mcp`
endpoint returns `404` and the MCP section does not appear in user settings.

### 2. Connect your MCP client

#### Option A: OAuth 2.1 (recommended)

MCP clients that support OAuth 2.1 (such as Claude Desktop via `mcp-remote`) authenticate automatically. No token
management required — just provide the server URL:

```json
{
  "mcpServers": {
    "trek": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-trek-instance.com/mcp"
      ]
    }
  }
}
```

> The path to `npx` may need to be adjusted for your system (e.g. `C:\PROGRA~1\nodejs\npx.cmd` on Windows).

**What happens automatically:**
1. The client fetches `/.well-known/oauth-authorization-server` to discover the TREK authorization server.
2. The client registers itself via [Dynamic Client Registration (RFC 7591)](https://www.rfc-editor.org/rfc/rfc7591).
3. Your browser opens TREK's consent screen, where you choose which scopes (permissions) to grant.
4. The client receives a short-lived access token and a rotating refresh token — no re-authorization needed.

> **Requirement:** The `APP_URL` environment variable must be set to your TREK instance's public URL for OAuth
> discovery to work correctly.

**For more control over scopes or to use confidential client mode**, pre-create an OAuth client in
**Settings > Integrations > MCP > OAuth Clients** before connecting. Clients created there have a client secret
(`trekcs_` prefix) and fixed scopes that you define up front.

#### Option B: Static API Token (deprecated)

> **Deprecated:** Static API tokens will stop working in a future version. Migrate to OAuth 2.1 above.

1. Go to **Settings > Integrations > MCP** and create an API token.
2. Click **Create New Token**, give it a name, and **copy the token immediately** — it is shown only once.
3. Add it to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "trek": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-trek-instance.com/mcp",
        "--header",
        "Authorization: Bearer trek_your_token_here"
      ]
    }
  }
}
```

Static tokens grant full access to all tools and resources (no scope restrictions). Sessions authenticated with a
static token will receive deprecation warnings in the AI client via server instructions and tool results.

Each user can create up to **10 static tokens**.

---

## Authentication

TREK's MCP server supports three authentication methods. OAuth 2.1 is the recommended path for all external clients.

| Method | Token prefix | Access level | TTL | Notes |
|--------|-------------|-------------|-----|-------|
| **OAuth 2.1** | `trekoa_` | Scoped (per-consent) | 1 hour | Recommended. Automatically refreshed via 30-day rolling refresh tokens (`trekrf_` prefix). Replay-detected rotation — replayed tokens cascade-revoke the entire chain. |
| **Static API token** | `trek_` | Full access | No expiry | **Deprecated.** Triggers deprecation warnings in AI clients. Will be removed in a future release. |
| **Web session JWT** | — | Full access | Session-based | Used internally by the TREK web UI. Not intended for external clients. |

All methods require the `Authorization: Bearer <token>` header (strict scheme enforcement — `Bearer` required).

---

## OAuth Scopes

When connecting via OAuth 2.1, you grant specific scopes during the consent step. TREK registers only the MCP tools
that match your granted scopes for that session.

| Scope | Permission | Group |
|-------|-----------|-------|
| `trips:read` | View trips & itineraries | Trips |
| `trips:write` | Edit trips & itineraries | Trips |
| `trips:delete` | Delete trips (irreversible) | Trips |
| `trips:share` | Manage share links | Trips |
| `places:read` | View places & map data | Places |
| `places:write` | Manage places | Places |
| `atlas:read` | View Atlas | Atlas |
| `atlas:write` | Manage Atlas | Atlas |
| `packing:read` | View packing lists | Packing |
| `packing:write` | Manage packing lists | Packing |
| `todos:read` | View to-do lists | To-dos |
| `todos:write` | Manage to-do lists | To-dos |
| `budget:read` | View budget | Budget |
| `budget:write` | Manage budget | Budget |
| `reservations:read` | View reservations | Reservations |
| `reservations:write` | Manage reservations | Reservations |
| `collab:read` | View collaboration | Collaboration |
| `collab:write` | Manage collaboration | Collaboration |
| `notifications:read` | View notifications | Notifications |
| `notifications:write` | Manage notifications | Notifications |
| `vacay:read` | View vacation plans | Vacation |
| `vacay:write` | Manage vacation plans | Vacation |
| `geo:read` | Maps & geocoding | Geo |
| `weather:read` | Weather forecasts | Weather |
| `journey:read` | View journeys | Journey |
| `journey:write` | Manage journeys | Journey |
| `journey:share` | Manage journey share links | Journey |

**Scope rules:**
- A `:write` scope implies `:read` access for the same group (e.g. `budget:write` also grants budget read access).
- Any `trips:*` scope (`trips:read`, `trips:write`, `trips:delete`, or `trips:share`) grants trip read access.
- Any `journey:*` scope (`journey:read`, `journey:write`, or `journey:share`) grants journey read access.
- `list_trips` and `get_trip_summary` are **always available** regardless of scopes — they are navigation tools.
- Static tokens and web session JWTs have full access to all tools (equivalent to all scopes).
- Addon-gated tools (Atlas, Collab, Vacay, Journey) require both the relevant scope **and** the addon to be enabled.

---

## Limitations & Important Notes

| Limitation                              | Details                                                                                                                                          |
|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| **Admin activation required**           | The MCP addon must be enabled by an admin before any user can access it.                                                                         |
| **Per-user scoping**                    | Each MCP session is scoped to the authenticated user. You can only access trips you own or are a member of.                                      |
| **No image uploads**                    | Cover images cannot be set through MCP. Use the web UI to upload trip covers.                                                                    |
| **Reservations are created as pending** | When the AI creates a reservation, it starts with `pending` status. You must confirm it manually or ask the AI to set the status to `confirmed`. |
| **Demo mode restrictions**              | If TREK is running in demo mode, all write operations through MCP are blocked.                                                                   |
| **Rate limiting**                       | 300 requests per minute per user (configurable via `MCP_RATE_LIMIT`). Exceeding this returns a `429` error.                                     |
| **Per-client rate limiting**            | Rate limits are tracked per user-client pair, so each OAuth client has its own independent rate limit window.                                    |
| **Session limits**                      | Maximum 20 concurrent MCP sessions per user (configurable via `MCP_MAX_SESSION_PER_USER`). Sessions expire after 1 hour of inactivity.          |
| **Token limits**                        | Maximum 10 static API tokens per user. Maximum 10 OAuth clients per user.                                                                        |
| **Token revocation**                    | Deleting a static token or revoking an OAuth session immediately terminates all active MCP sessions for that token/client.                       |
| **OAuth scope enforcement**             | Only tools matching your granted OAuth scopes are registered in the session. Calling an out-of-scope tool returns an error.                      |
| **Addon toggle invalidation**           | When an admin enables or disables an addon, all active MCP sessions are invalidated and must be re-established.                                  |
| **Real-time sync**                      | Changes made through MCP are broadcast to all connected clients in real-time via WebSocket, just like changes made through the web UI.           |
| **Addon-gated features**                | Some resources and tools are only available when the corresponding addon (Atlas, Collab, Vacay, Journey) is enabled by an admin.                 |

---

## Resources (read-only)

Resources provide read-only access to your TREK data. MCP clients can read these to understand the current state before
making changes.

### Core Resources

| Resource              | URI                                             | Description                                                                           |
|-----------------------|-------------------------------------------------|---------------------------------------------------------------------------------------|
| Trips                 | `trek://trips`                                  | All trips you own or are a member of                                                  |
| Trip Detail           | `trek://trips/{tripId}`                         | Single trip with metadata and member count                                            |
| Days                  | `trek://trips/{tripId}/days`                    | Days of a trip with their assigned places                                             |
| Places                | `trek://trips/{tripId}/places`                  | All places/POIs saved in a trip. Supports `?assignment=all\|unassigned\|assigned`     |
| Budget                | `trek://trips/{tripId}/budget`                  | Budget and expense items                                                              |
| Budget Per-Person     | `trek://trips/{tripId}/budget/per-person`       | Per-person totals and split breakdown                                                 |
| Budget Settlement     | `trek://trips/{tripId}/budget/settlement`       | Suggested transactions to settle who owes whom                                        |
| Packing               | `trek://trips/{tripId}/packing`                 | Packing checklist                                                                     |
| Packing Bags          | `trek://trips/{tripId}/packing/bags`            | Packing bags with their assigned members                                              |
| Reservations          | `trek://trips/{tripId}/reservations`            | Flights, hotels, restaurants, etc.                                                    |
| Day Notes             | `trek://trips/{tripId}/days/{dayId}/notes`      | Notes for a specific day                                                              |
| Accommodations        | `trek://trips/{tripId}/accommodations`          | Hotels/rentals with check-in/out details                                              |
| Members               | `trek://trips/{tripId}/members`                 | Owner and collaborators                                                               |
| Collab Notes          | `trek://trips/{tripId}/collab-notes`            | Shared collaborative notes                                                            |
| To-Dos                | `trek://trips/{tripId}/todos`                   | To-do items ordered by position                                                       |
| Categories            | `trek://categories`                             | Available place categories (for use when creating places)                             |
| Bucket List           | `trek://bucket-list`                            | Your personal travel bucket list                                                      |
| Visited Countries     | `trek://visited-countries`                      | Countries marked as visited in Atlas                                                  |
| Notifications         | `trek://notifications/in-app`                   | Your in-app notifications (most recent 50, unread first)                              |

### Addon-Gated Resources

These resources are only available when the corresponding addon is enabled by an admin.

| Resource              | URI                                             | Addon    | Description                                                         |
|-----------------------|-------------------------------------------------|----------|---------------------------------------------------------------------|
| Atlas Stats           | `trek://atlas/stats`                            | Atlas    | Visited country counts and continent breakdown                      |
| Atlas Regions         | `trek://atlas/regions`                          | Atlas    | Manually visited sub-country regions                                |
| Collab Polls          | `trek://trips/{tripId}/collab/polls`            | Collab   | All polls for a trip with vote counts per option                    |
| Collab Messages       | `trek://trips/{tripId}/collab/messages`         | Collab   | Most recent 100 chat messages for a trip                            |
| Vacay Plan            | `trek://vacay/plan`                             | Vacay    | Full snapshot of your active vacation plan (members, years, config) |
| Vacay Entries         | `trek://vacay/entries/{year}`                   | Vacay    | All vacation day entries for the active plan and a specific year    |
| Vacay Holidays        | `trek://vacay/holidays/{year}`                  | Vacay    | Public holidays for the plan's configured region and year           |
| Journeys              | `trek://journeys`                               | Journey  | All journeys owned or contributed to by the current user            |
| Journey Detail        | `trek://journeys/{journeyId}`                   | Journey  | Single journey with entries, contributors, and linked trips         |
| Journey Entries       | `trek://journeys/{journeyId}/entries`           | Journey  | All entries in a journey (date, text, mood, linked trip)            |
| Journey Contributors  | `trek://journeys/{journeyId}/contributors`      | Journey  | Contributors (owner and collaborators) of a journey                 |

---

## Tools (read-write)

TREK exposes tools organized by feature area. Use `get_trip_summary` as a starting point — it returns everything about a
trip in a single call.

### Trip Summary

| Tool               | Description                                                                                                                                                                                                           |
|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `get_trip_summary` | Full denormalized snapshot of a trip: metadata, members, days with assignments and notes, accommodations, budget, packing, reservations, collab notes, to-dos, and poll/message counts. Use this as your context loader. |

### Compound Tools

Compound tools collapse common multi-step workflows into a single atomic call. Each one wraps two sequential operations in a database transaction — if the second step fails, the first is rolled back automatically.

> **When to use:** Only use compound tools when the place or item does not yet exist. If it already exists, call the individual tools (`assign_place_to_day`, `create_accommodation`, `set_budget_item_members`) directly.

| Tool | Wraps | Description |
|---|---|---|
| `create_and_assign_place` | `create_place` + `assign_place_to_day` | Create a new place and immediately assign it to a specific day. Accepts all `create_place` fields (`place_notes` instead of `notes`) plus `dayId` and optional `assignment_notes`. Returns `{ place, assignment }`. |
| `create_place_accommodation` | `create_place` + `create_accommodation` | Create a new place and immediately book it as an accommodation for a date range. Accepts all `create_place` fields (`place_notes` instead of `notes`) plus `start_day_id`, `end_day_id`, `check_in`, `check_out`, `confirmation`, and `accommodation_notes`. Also auto-creates a linked hotel reservation. Returns `{ place, accommodation }`. |
| `create_budget_item_with_members` | `create_budget_item` + `set_budget_item_members` | Create a budget item and optionally set which members are splitting it. Accepts all `create_budget_item` fields plus an optional `userIds` array. If `userIds` is omitted or empty, behaves identically to `create_budget_item`. Returns `{ item }` with members populated. |

**Scope requirements** match the underlying tools: `places:write` for `create_and_assign_place`, `trips:write` for `create_place_accommodation`, `budget:write` for `create_budget_item_with_members` (Budget addon required).

---

### Trips

| Tool                 | Description                                                                                 |
|----------------------|---------------------------------------------------------------------------------------------|
| `list_trips`         | List all trips you own or are a member of. Supports `include_archived` flag.                |
| `create_trip`        | Create a new trip with title, dates, currency. Days are auto-generated from the date range. |
| `update_trip`        | Update a trip's title, description, dates, or currency.                                     |
| `delete_trip`        | Delete a trip. **Owner only.**                                                              |
| `list_trip_members`  | List the owner and all collaborators of a trip.                                             |
| `add_trip_member`    | Add a user to a trip by username or email. **Owner only.**                                  |
| `remove_trip_member` | Remove a collaborator from a trip. **Owner only.**                                          |
| `copy_trip`          | Duplicate a trip (days, places, itinerary, packing, budget, reservations). Packing items are reset to unchecked. |
| `export_trip_ics`    | Export the trip itinerary and reservations as iCalendar (`.ics`) text for calendar apps.   |
| `get_share_link`     | Get the current public share link for a trip and its permission flags.                      |
| `create_share_link`  | Create or update the public share link with configurable visibility flags (map, bookings, packing, budget, collab). |
| `delete_share_link`  | Revoke the public share link for a trip.                                                    |

### Places

> To create a place and assign it to a day in one call, use [`create_and_assign_place`](#compound-tools).

| Tool             | Description                                                                                      |
|------------------|--------------------------------------------------------------------------------------------------|
| `list_places`              | List places/POIs in a trip, optionally filtered by assignment status, category, tag, or search.  |
| `create_place`             | Add a place/POI with name, coordinates, address, category, notes, website, phone, and optional `google_place_id` / `osm_id` for opening hours. |
| `update_place`             | Update any field of an existing place including transport mode, timing, and price.               |
| `delete_place`             | Remove a place from a trip.                                                                      |
| `bulk_delete_places`       | Delete multiple places at once by ID. Removes all day assignments as well. **Cannot be undone.** |
| `import_places_from_url`   | Import all places from a publicly shared Google Maps or Naver Maps list URL.                     |
| `list_categories`          | List all available place categories with id, name, icon and color.                              |
| `search_place`             | Search for a real-world place by name or address. Returns `osm_id` and `google_place_id` for use in `create_place`. |

### Day Planning

| Tool                        | Description                                                                          |
|-----------------------------|--------------------------------------------------------------------------------------|
| `update_day`                | Set or clear a day's title (e.g. "Arrival in Paris", "Free day").                   |
| `create_day`                | Add a new day to a trip with optional date and notes.                                |
| `delete_day`                | Delete a day from a trip.                                                            |
| `assign_place_to_day`       | Pin a place to a specific day in the itinerary.                                      |
| `unassign_place`            | Remove a place assignment from a day.                                                |
| `reorder_day_assignments`   | Reorder places within a day by providing assignment IDs in the desired order.        |
| `update_assignment_time`    | Set start/end times for a place assignment (e.g. "09:00" – "11:30"). Pass `null` to clear. |
| `move_assignment`           | Move a place assignment to a different day.                                          |
| `get_assignment_participants`| Get the list of users participating in a specific place assignment.                 |
| `set_assignment_participants`| Set participants for a place assignment (replaces current list).                   |

### Accommodations

> To create a place and book it as an accommodation in one call, use [`create_place_accommodation`](#compound-tools).

| Tool                   | Description                                                                              |
|------------------------|------------------------------------------------------------------------------------------|
| `create_accommodation` | Add an accommodation (hotel, Airbnb, etc.) linked to a place and a check-in/out date range. |
| `update_accommodation` | Update fields on an existing accommodation (dates, times, confirmation, notes).          |
| `delete_accommodation` | Delete an accommodation record from a trip.                                              |

### Transport

Transport bookings (flights, trains, cars, cruises) support multi-stop `endpoints[]` — each endpoint has a `role` (`from`/`to`/`stop`), name, optional IATA `code` (for flights), coordinates, timezone, and local time. Use `search_airports` to resolve airport names to IATA codes before creating a flight.

| Tool                   | Description                                                                                                                                           |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `create_transport`     | Create a transport booking (`flight`, `train`, `car`, `cruise`) with optional endpoints, departure/arrival times, and confirmation details. Created as pending. |
| `update_transport`     | Update an existing transport booking. Pass `endpoints[]` to replace the full stop list. Use `status: "confirmed"` to confirm.                        |
| `delete_transport`     | Delete a transport booking from a trip.                                                                                                               |

### Reservations

For flights, trains, cars, and cruises, use the **Transport** tools above. Reservations cover all other booking types.

| Tool                       | Description                                                                                                                              |
|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------|
| `create_reservation`       | Create a pending reservation. Supports hotels, restaurants, events, tours, activities, and other types. Hotels can be linked to places and check-in/out days. |
| `update_reservation`       | Update any field including status (`pending` / `confirmed` / `cancelled`).                                                               |
| `delete_reservation`       | Delete a reservation and its linked accommodation record if applicable.                                                                  |
| `reorder_reservations`     | Update the display order of reservations (and transports) within a day.                                                                  |
| `link_hotel_accommodation` | Set or update a hotel reservation's check-in/out day links and associated place.                                                         |

### Budget

> To create a budget item and set its members in one call, use [`create_budget_item_with_members`](#compound-tools).

| Tool                       | Description                                                                           |
|----------------------------|---------------------------------------------------------------------------------------|
| `create_budget_item`       | Add an expense with name, category, and price.                                        |
| `update_budget_item`       | Update an expense's details, split (persons/days), or notes.                          |
| `delete_budget_item`       | Remove a budget item.                                                                 |
| `set_budget_item_members`  | Set which trip members are splitting a budget item (replaces current member list).    |
| `toggle_budget_member_paid`| Mark or unmark a member as having paid their share of a budget item.                  |

### Packing

| Tool                          | Description                                                                       |
|-------------------------------|-----------------------------------------------------------------------------------|
| `create_packing_item`         | Add an item to the packing checklist with optional category.                      |
| `update_packing_item`         | Rename an item or change its category.                                            |
| `toggle_packing_item`         | Check or uncheck a packing item.                                                  |
| `delete_packing_item`         | Remove a packing item.                                                            |
| `reorder_packing_items`       | Set the display order of packing items within a trip.                             |
| `bulk_import_packing`         | Import multiple packing items at once from a list (with optional quantity).       |
| `apply_packing_template`      | Apply a saved packing template to a trip (adds items from the template).          |
| `save_packing_template`       | Save the current packing list as a reusable template.                             |
| `list_packing_bags`           | List all packing bags for a trip.                                                 |
| `create_packing_bag`          | Create a new packing bag (e.g. "Carry-on", "Checked bag").                        |
| `update_packing_bag`          | Rename or recolor a packing bag.                                                  |
| `delete_packing_bag`          | Delete a packing bag (items are unassigned, not deleted).                         |
| `set_bag_members`             | Assign trip members to a packing bag.                                             |
| `get_packing_category_assignees` | Get which trip members are assigned to each packing category.                 |
| `set_packing_category_assignees` | Assign trip members to a packing category.                                    |

### Day Notes

| Tool              | Description                                                            |
|-------------------|------------------------------------------------------------------------|
| `create_day_note` | Add a note to a specific day with optional time label and emoji icon.  |
| `update_day_note` | Edit a day note's text, time, or icon.                                 |
| `delete_day_note` | Remove a note from a day.                                              |

### To-Dos

| Tool                          | Description                                                                                       |
|-------------------------------|---------------------------------------------------------------------------------------------------|
| `list_todos`                  | List all to-do items for a trip, ordered by position.                                             |
| `create_todo`                 | Create a to-do item with name, category, due date, description, assignee, and priority.           |
| `update_todo`                 | Update an existing to-do item. Pass `null` to clear nullable fields.                              |
| `toggle_todo`                 | Mark a to-do item as done or undone.                                                              |
| `delete_todo`                 | Delete a to-do item.                                                                              |
| `reorder_todos`               | Reorder to-do items within a trip by providing a new ordered list of IDs.                         |
| `get_todo_category_assignees` | Get the default assignees configured per to-do category for a trip.                               |
| `set_todo_category_assignees` | Set default assignees for a to-do category. Pass an empty array to clear.                         |

### Tags

| Tool         | Description                                                              |
|--------------|--------------------------------------------------------------------------|
| `list_tags`  | List all tags belonging to the current user.                             |
| `create_tag` | Create a new tag (user-scoped label for places) with optional hex color. |
| `update_tag` | Update the name or color of an existing tag.                             |
| `delete_tag` | Delete a tag (removes it from all places it was attached to).            |

### Notifications

| Tool                            | Description                                          |
|---------------------------------|------------------------------------------------------|
| `list_notifications`            | List in-app notifications with pagination and unread filter. |
| `get_unread_notification_count` | Get the count of unread in-app notifications.        |
| `mark_notification_read`        | Mark a single notification as read.                  |
| `mark_notification_unread`      | Mark a single notification as unread.                |
| `mark_all_notifications_read`   | Mark all notifications as read.                      |

### Maps & Weather

| Tool                  | Description                                                                                         |
|-----------------------|-----------------------------------------------------------------------------------------------------|
| `search_place`        | Search for a real-world place by name/address and get coordinates, `osm_id`, and `google_place_id`. |
| `get_place_details`   | Fetch detailed information (hours, photos, ratings) about a place by its Google Place ID.           |
| `reverse_geocode`     | Get a human-readable address for given coordinates.                                                 |
| `resolve_maps_url`    | Resolve a Google Maps share URL to coordinates and place name.                                      |
| `get_weather`         | Get weather forecast for a location and date.                                                       |
| `get_detailed_weather`| Get hourly/detailed weather forecast for a location and date.                                       |

### Airports

| Tool              | Description                                                                                                       |
|-------------------|-------------------------------------------------------------------------------------------------------------------|
| `search_airports` | Search for airports by name, city, or IATA code. Returns IATA code, name, city, country, coordinates, timezone.  |
| `get_airport`     | Look up a single airport by IATA code (e.g. `"ZRH"`, `"AMS"`, `"CDG"`).                                         |

### Collab Notes _(Collab addon required)_

| Tool                 | Description                                                                                     |
|----------------------|-------------------------------------------------------------------------------------------------|
| `create_collab_note` | Create a shared note visible to all trip members. Supports title, content, category, and color. |
| `update_collab_note` | Edit a collab note's content, category, color, or pin status.                                   |
| `delete_collab_note` | Delete a collab note.                                                                           |

### Collab Polls & Chat _(Collab addon required)_

| Tool                  | Description                                                                              |
|-----------------------|------------------------------------------------------------------------------------------|
| `list_collab_polls`   | List all polls for a trip.                                                               |
| `create_collab_poll`  | Create a new poll with a question, options, optional multiple choice, and deadline.      |
| `vote_collab_poll`    | Vote on a poll option (or remove vote if already voted).                                 |
| `close_collab_poll`   | Close a poll so no more votes can be cast.                                               |
| `delete_collab_poll`  | Delete a poll and all its votes.                                                         |
| `list_collab_messages`| List chat messages for a trip (most recent 100, supports pagination via `before`).       |
| `send_collab_message` | Send a chat message to a trip's collab channel, with optional reply threading.           |
| `delete_collab_message`| Delete a chat message (own messages only).                                              |
| `react_collab_message`| Toggle a reaction emoji on a chat message.                                               |

### Bucket List _(Atlas addon required)_

| Tool                      | Description                                                                                |
|---------------------------|--------------------------------------------------------------------------------------------|
| `create_bucket_list_item` | Add a destination to your personal bucket list with optional coordinates and country code. |
| `delete_bucket_list_item` | Remove an item from your bucket list.                                                      |

### Atlas _(Atlas addon required)_

| Tool                     | Description                                                                     |
|--------------------------|---------------------------------------------------------------------------------|
| `mark_country_visited`   | Mark a country as visited using its ISO 3166-1 alpha-2 code (e.g. "FR", "JP"). |
| `unmark_country_visited` | Remove a country from your visited list.                                        |

### Atlas Extended _(Atlas addon required)_

| Tool                       | Description                                                                  |
|----------------------------|------------------------------------------------------------------------------|
| `get_atlas_stats`          | Get atlas statistics — visited country counts, region counts, continent breakdown. |
| `list_visited_regions`     | List all manually visited sub-country regions for the current user.          |
| `mark_region_visited`      | Mark a sub-country region as visited (e.g. ISO code "US-CA").                |
| `unmark_region_visited`    | Remove a region from the visited list.                                       |
| `get_country_atlas_places` | Get places saved in the user's atlas for a specific country.                 |
| `update_bucket_list_item`  | Update a bucket list item (name, notes, coordinates, target date).           |

### Vacay _(Vacay addon required)_

| Tool                       | Description                                                                           |
|----------------------------|---------------------------------------------------------------------------------------|
| `get_vacay_plan`           | Get the current user's active vacation plan (own or joined).                          |
| `update_vacay_plan`        | Update vacation plan settings (weekend blocking, holidays, carry-over).               |
| `set_vacay_color`          | Set the current user's color in the vacation plan calendar.                           |
| `get_available_vacay_users`| List users who can be invited to the current vacation plan.                           |
| `send_vacay_invite`        | Invite a user to join the vacation plan by their user ID.                             |
| `accept_vacay_invite`      | Accept a pending invitation to join another user's vacation plan.                     |
| `decline_vacay_invite`     | Decline a pending vacation plan invitation.                                           |
| `cancel_vacay_invite`      | Cancel an outgoing invitation (owner cancels an invite they sent).                    |
| `dissolve_vacay_plan`      | Dissolve the shared plan — all members return to their own individual plan.           |
| `list_vacay_years`         | List calendar years tracked in the current vacation plan.                             |
| `add_vacay_year`           | Add a calendar year to the vacation plan.                                             |
| `delete_vacay_year`        | Remove a calendar year from the vacation plan.                                        |
| `get_vacay_entries`        | Get all vacation day entries for the active plan and a specific year.                 |
| `toggle_vacay_entry`       | Toggle a day on or off as a vacation day for the current user.                        |
| `toggle_company_holiday`   | Toggle a date as a company holiday for the whole plan.                                |
| `get_vacay_stats`          | Get vacation statistics for a specific year (days used, remaining, carried over).     |
| `update_vacay_stats`       | Update the vacation day allowance for a specific user and year.                       |
| `add_holiday_calendar`     | Add a public holiday calendar (by region code) to the vacation plan.                  |
| `update_holiday_calendar`  | Update label or color for a holiday calendar.                                         |
| `delete_holiday_calendar`  | Remove a holiday calendar from the vacation plan.                                     |
| `list_holiday_countries`   | List countries available for public holiday calendars.                                |
| `list_holidays`            | List public holidays for a country and year.                                          |

### Journey _(Journey addon required)_

| Tool                              | Description                                                                                                |
|-----------------------------------|------------------------------------------------------------------------------------------------------------|
| `list_journeys`                   | List all journeys owned or contributed to by the current user.                                             |
| `get_journey`                     | Get a full snapshot of a journey: metadata, entries, contributors, and linked trips.                       |
| `create_journey`                  | Create a new journey with title, optional subtitle, and an initial list of trip IDs.                       |
| `update_journey`                  | Update a journey's title, subtitle, or status.                                                             |
| `delete_journey`                  | Delete a journey.                                                                                          |
| `add_journey_trip`                | Link an existing trip to a journey.                                                                        |
| `remove_journey_trip`             | Remove a trip from a journey.                                                                              |
| `list_journey_entries`            | List all entries in a journey (date, text, mood, linked trip).                                             |
| `create_journey_entry`            | Add an entry to a journey with optional title, body text, date, linked trip, and sort order.               |
| `update_journey_entry`            | Edit a journey entry's title, body, date, or mood.                                                         |
| `delete_journey_entry`            | Remove an entry from a journey.                                                                            |
| `reorder_journey_entries`         | Reorder entries in a journey by providing the new ordered list of entry IDs.                               |
| `list_journey_contributors`       | List the contributors of a journey (owner and invited editors/viewers).                                    |
| `add_journey_contributor`         | Invite a user to a journey with `editor` or `viewer` role.                                                 |
| `update_journey_contributor_role` | Change a contributor's role between `editor` and `viewer`.                                                 |
| `remove_journey_contributor`      | Remove a contributor from a journey.                                                                       |
| `update_journey_preferences`      | Update display preferences for a journey (e.g. hide skeleton entries).                                     |
| `get_journey_suggestions`         | Get suggested trips to add to journeys (based on recent trip history).                                     |
| `list_journey_available_trips`    | List all trips available to the current user for linking to a journey.                                     |
| `get_journey_share_link`          | Get the current public share link for a journey.                                                           |
| `create_journey_share_link`       | Create or update the public share link for a journey.                                                      |
| `delete_journey_share_link`       | Revoke the public share link for a journey.                                                                |

---

## Prompts

MCP prompts are pre-built context loaders your AI client can invoke to get a structured starting point for common tasks.

| Prompt               | Description                                                                     |
|----------------------|---------------------------------------------------------------------------------|
| `trip-summary`       | Load a formatted summary of a trip (dates, members, days, budget, packing, reservations) before planning or modifying it. |
| `packing-list`       | Get a formatted packing checklist for a trip, grouped by category.              |
| `budget-overview`    | Get a formatted budget summary with totals by category and per-person cost.     |
| `token_auth_notice`  | Static token deprecation notice and migration guide. Only available in sessions authenticated with a legacy `trek_` token. |

---

## Example

Conversation with Claude: https://claude.ai/share/51572203-6a4d-40f8-a6bd-eba09d4b009d

Initial prompt (1st message):

```
I'd like to plan a week-long trip to Kyoto, Japan, arriving April 5 2027
and leaving April 11 2027. It's cherry blossom season so please keep that
in mind when picking spots.

Before writing anything to TREK, do some research: look up what's worth
visiting, figure out a logical day-by-day flow (group nearby spots together
to avoid unnecessary travel), find a well-reviewed hotel in a central
neighbourhood, and think about what kind of food and restaurant experiences
are worth including.

Once you have a solid plan, write the whole thing to TREK:
- Create the trip
- Add all the places you've researched with their real coordinates
- Build out the daily itinerary with sensible visiting times
- Book the hotel as a reservation and link it properly to the accommodation days
- Add any notable restaurant reservations
- Put together a realistic budget in EUR
- Build a packing list suited to April in Kyoto
- Leave a pinned collab note with practical tips (transport, etiquette, money, etc.)
- Add a day note for each day with any important heads-up (early start, crowd
  tips, booking requirements, etc.)
- Mark Japan as visited in my Atlas

Currency: CHF. Use get_trip_summary at the end and give me a quick recap
of everything that was added.
```

PDF of the generated trip: [./docs/TREK-Generated-by-MCP.pdf](./docs/TREK-Generated-by-MCP.pdf)

![trip](./docs/screenshot-trip-mcp.png)