diff --git a/MCP.md b/MCP.md index 2c0e3fe..74f0f2b 100644 --- a/MCP.md +++ b/MCP.md @@ -1,6 +1,8 @@ # 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. +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. @@ -18,7 +20,8 @@ TREK includes a built-in [Model Context Protocol](https://modelcontextprotocol.i ### 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 `403 Forbidden` and the MCP section does not appear in user settings. +An administrator must first enable the MCP addon from the **Admin Panel > Addons** page. Until enabled, the `/mcp` +endpoint returns `403 Forbidden` and the MCP section does not appear in user settings. ### 2. Create an API token @@ -32,7 +35,8 @@ Each user can create up to **10 tokens**. ### 3. Configure your MCP client -The Settings page shows a ready-to-copy client configuration snippet. For **Claude Desktop**, add the following to your `claude_desktop_config.json`: +The Settings page shows a ready-to-copy client configuration snippet. For **Claude Desktop**, add the following to your +`claude_desktop_config.json`: ```json { @@ -56,139 +60,180 @@ The Settings page shows a ready-to-copy client configuration snippet. For **Clau ## 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. | +| 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** | 60 requests per minute per user. Exceeding this returns a `429` error. | -| **Session limits** | Maximum 5 concurrent MCP sessions per user. Sessions expire after 1 hour of inactivity. | -| **Token limits** | Maximum 10 API tokens per user. | -| **Token revocation** | Deleting a token immediately terminates all active MCP sessions for that user. | -| **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. | +| **Demo mode restrictions** | If TREK is running in demo mode, all write operations through MCP are blocked. | +| **Rate limiting** | 60 requests per minute per user. Exceeding this returns a `429` error. | +| **Session limits** | Maximum 5 concurrent MCP sessions per user. Sessions expire after 1 hour of inactivity. | +| **Token limits** | Maximum 10 API tokens per user. | +| **Token revocation** | Deleting a token immediately terminates all active MCP sessions for that user. | +| **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. | --- ## 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. +Resources provide read-only access to your TREK data. MCP clients can read these to understand the current state before +making changes. -| 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 | -| Budget | `trek://trips/{tripId}/budget` | Budget and expense items | -| Packing | `trek://trips/{tripId}/packing` | Packing checklist | -| 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 | -| 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 | +| 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 | +| Budget | `trek://trips/{tripId}/budget` | Budget and expense items | +| Packing | `trek://trips/{tripId}/packing` | Packing checklist | +| 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 | +| 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 | --- ## Tools (read-write) -TREK exposes **34 tools** organized by feature area. Use `get_trip_summary` as a starting point — it returns everything about a trip in a single call. +TREK exposes **34 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 | -|---|---| +| Tool | Description | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `get_trip_summary` | Full denormalized snapshot of a trip: metadata, members, days with assignments and notes, accommodations, budget totals, packing stats, reservations, and collab notes. Use this as your context loader. | ### Trips -| Tool | Description | -|---|---| -| `list_trips` | List all trips you own or are a member of. Supports `include_archived` flag. | +| 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.** | +| `update_trip` | Update a trip's title, description, dates, or currency. | +| `delete_trip` | Delete a trip. **Owner only.** | ### Places -| Tool | Description | -|---|---| +| Tool | Description | +|----------------|-----------------------------------------------------------------------------------| | `create_place` | Add a place/POI with name, coordinates, address, category, notes, website, phone. | -| `update_place` | Update any field of an existing place. | -| `delete_place` | Remove a place from a trip. | +| `update_place` | Update any field of an existing place. | +| `delete_place` | Remove a place from a trip. | ### Day Planning -| Tool | Description | -|---|---| -| `assign_place_to_day` | Pin a place to a specific day in the itinerary. | -| `unassign_place` | Remove a place assignment from a day. | +| Tool | Description | +|---------------------------|-------------------------------------------------------------------------------| +| `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"). | -| `update_day` | Set or clear a day's title (e.g. "Arrival in Paris", "Free day"). | +| `update_assignment_time` | Set start/end times for a place assignment (e.g. "09:00" – "11:30"). | +| `update_day` | Set or clear a day's title (e.g. "Arrival in Paris", "Free day"). | ### Reservations -| Tool | Description | -|---|---| -| `create_reservation` | Create a pending reservation. Supports flights, hotels, restaurants, trains, cars, cruises, 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. | -| `link_hotel_accommodation` | Set or update a hotel reservation's check-in/out day links and associated place. | +| Tool | Description | +|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `create_reservation` | Create a pending reservation. Supports flights, hotels, restaurants, trains, cars, cruises, 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. | +| `link_hotel_accommodation` | Set or update a hotel reservation's check-in/out day links and associated place. | ### Budget -| Tool | Description | -|---|---| -| `create_budget_item` | Add an expense with name, category, and price. | +| 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. | +| `delete_budget_item` | Remove a budget item. | ### Packing -| Tool | Description | -|---|---| +| 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. | +| `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. | ### Day Notes -| Tool | Description | -|---|---| +| 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. | +| `update_day_note` | Edit a day note's text, time, or icon. | +| `delete_day_note` | Remove a note from a day. | ### Collab Notes -| Tool | Description | -|---|---| +| 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 and its associated files. | +| `update_collab_note` | Edit a collab note's content, category, color, or pin status. | +| `delete_collab_note` | Delete a collab note and its associated files. | ### Bucket List -| Tool | Description | -|---|---| +| 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. | +| `delete_bucket_list_item` | Remove an item from your bucket list. | ### Atlas -| 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. | +| 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. | --- -## Screenshots +## 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. +``` + +Database file: https://share.jubnl.ch/s/S7bBpj42mB + +Email: admin@admin.com \ +Password: admin123 + +PDF of the generated trip: [./docs/TREK-Generated-by-MCP.pdf](./docs/TREK-Generated-by-MCP.pdf) + +![trip](./docs/screenshot-trip-mcp.png) \ No newline at end of file diff --git a/docs/TREK-Generated-by-MCP.pdf b/docs/TREK-Generated-by-MCP.pdf new file mode 100644 index 0000000..70a0964 Binary files /dev/null and b/docs/TREK-Generated-by-MCP.pdf differ diff --git a/docs/screenshot-trip-mcp.png b/docs/screenshot-trip-mcp.png new file mode 100644 index 0000000..30a19e6 Binary files /dev/null and b/docs/screenshot-trip-mcp.png differ