Document the trip journal link tools, the city walk check-off tool, metadata-document clients and the AI Assistant on the MCP pages

2026-11-05 04:04:07 +00:00 · 2026-10-24 23:17:35 +02:00
parent b64dd700a8
commit 016567dd9a
5 changed files with 29 additions and 3 deletions
@@ -246,6 +246,17 @@ Requires `journey:read` or `journey:write` scope.

 Every book write is one save of the whole book against its version: nothing is written when any part is refused, and every member's open Studio is told the book changed, the asking one included.

+### Trip journal link _(Journey addon required)_
+
+A trip can show one of your journals as its own. Requires `journey:read` to look and `journey:write` to change, and you must be allowed to edit the trip.
+
+| Tool | Description |
+|---|---|
+| `get_trip_journal` | The journal a trip shows as its own, if any: its id and title, your access to it, and whether you may link, unlink or change who it is open to. Open the journal itself with `get_journey`. |
+| `link_trip_journal` | Show one of your own journals in a trip, replacing the one it showed. The trip members you list get into the journal as viewers or editors and see it in their own journal list; members left out do not. The journal has to be yours, and the trip permission to link journals applies. |
+| `set_trip_journal_members` | Change which trip members the linked journal is open to, and as viewer or editor. The list replaces the one before, and anyone left out loses the access the link gave them. Only the journal's owner can do this. |
+| `unlink_trip_journal` | Take the linked journal off a trip. The journal stays; members the link let in lose that access, while its owner and direct contributors keep theirs. |
+
 ### Dawarich _(Dawarich addon required)_

 Each tool asks for the scope of what it writes, so the scopes differ per tool. The connection itself (address, API key, test, disconnect) has no MCP tool. See [Dawarich](Dawarich).
@@ -290,6 +301,7 @@ The saved tours of a trip, as the Tours list and the tour detail show them, how
 | `find_tours_for_day` | The tours put on one day of a trip, with the same facts as `list_tours` | `trips:read` |
 | `get_city_walk_progress` | How far a city walk got on one day it is on: every station in order with its key, its status that day (planned, visited or skipped, as checked off in the day plan), importance, protection, stay and opening hours, what is still open, and the walking time of the whole walk. Visits belong to that day only. Reading changes nothing | `trips:read` |
 | `get_city_walk_remaining_time` | What is left of a city walk on one day it is on, counted from the last station checked off as visited (or the start): the walking time still ahead along the saved line, the stays still open and the open stations, kept apart from the walking time of the whole walk. Says what it counts from and that no live position is known; an upper bound while a station ahead is skipped; unknown, with the reason, without a line, a walking time or a clear order of visits. Reading changes nothing | `trips:read` |
+| `set_city_walk_visit` | Check off a station of a city walk on one day it is on, the way the travellers tap it in the day plan: visited, skipped, or planned to take a mark back. Use it when the travellers say where they are or what they did. `stationKey` is the key of the station from `get_city_walk_progress` or `get_tour_plan`. The mark belongs to that day only. The answer gives the status before and after and the walk as it now stands. Needs the right to edit the trip days. The route does not change | `trips:write` |
 | `export_tour_gpx` | One saved tour as a GPX file: its whole saved line as one track, with the heights it carries and none it lacks, and a file name. A tour without a line cannot be exported | `trips:read` |
 | `search_tour_pois` | Places along the saved line of a hike, run, ride, bike tour, paddle tour, ski and winter tour or city walk within a corridor (viewpoints, peaks, shelters, drinking water, food, toilets, picnic, campsites, sights, slipways, boat rental, bike repair, for a bike tour e-bike charging points, for a ski and winter tour coffee shops and places to eat as well, and for a city walk museums and galleries, parks and gardens, coffee shops, places to eat and markets): source (TREK places index or OpenStreetMap), kind, address, website, phone, opening hours as the source has them (a hint, never a promise), the distance straight across to the line (not a detour) and how far along the line; up to 60, the nearest to the line when more match, listed from the start. An e-bike charging point is one OpenStreetMap tags for bicycles (`bicycle=designated` or `yes`, never a charger for cars alone) and carries `charging`: bicycle, sockets, capacity, fee and access as OpenStreetMap states them, empty where it says nothing; whether it works or is free today is not known. When sights are asked for, the best known places near the line (by the page views of their Wikidata item) are searched too, so a famous square no category names is found as a sight, and the highlights among them carry `highlight: true` and come first. A place OpenStreetMap has no name for comes with an empty name. `unavailable` names the categories no source could be searched for right now, so their places are missing rather than absent. `retry_after_s`, when present beside `unavailable`, is how many seconds until asking again makes sense, because the OpenStreetMap mirrors failed and are only probed now and then. Says when stretches could not be searched, only the first part of a long line was, or more places matched. A tour saved with its points only (`route_pending`) has no line to search along yet. Nothing is added | `trips:read` |
 | `list_tour_library` | The saved tours of every trip the user can open, to choose one to take over into another trip: name, type, distance, ascent, descent, planned times and the trip each is in. Narrowed by a part of the name, a type or a trip; the trip being planned can be left out. Up to 100 tours, `truncated` says there were more | `trips:read` |
@@ -14,12 +14,24 @@ Once connected, an AI assistant can work with your TREK data in a single convers
 - Send collab messages and notes to other trip members
 - Mark countries and regions as visited in Atlas
 - Log vacation days in Vacay
- Write journey entries across multiple trips
+- Write journey entries across multiple trips, and show a journal inside a trip
+- Plan, edit and check off tours: hikes, bike, paddle, ski and winter tours, rides and city walks
+- Plan road trips: route, hazards, charging stops and places along the way
+- Import flights from AirTrail and visits and routes from Dawarich
+- Import places from links and tracks from GPX files
+- Switch calendar feeds and trip invite links on or off
+- Keep school holiday regions up to date for Vacay
 - Upload documents to a trip, read them and link them to bookings, places or expenses
 - Look up how a TREK feature works in the bundled help

 Changes made through MCP are broadcast to all connected clients in real-time — exactly like changes made in the web UI.

+Many of these tools belong to an addon and only appear while an administrator has enabled it. See [MCP-Addon-Tools](MCP-Addon-Tools).
+
+### MCP and the built-in AI Assistant
+
+The **AI Assistant** addon is a chat inside TREK itself. It works on the same tools as an external MCP client and the same permission checks apply, but it does not connect through `/mcp`: its AI provider is set up inside TREK, not through OAuth clients. Changes it suggests wait for your confirmation. MCP is the way to let a different AI app, such as Claude.ai or Cursor, use TREK.
+
 ## Authentication options

 | Use case | Method |
@@ -56,7 +56,7 @@ TREK defines 35 scopes across 17 groups.
 - `list_trips` and `get_trip_summary` are always available regardless of scope — they are navigation tools.
 - `plugins:use` grants no data access of its own. It lets a client call tools published by plugins your administrator installed and approved, and each plugin acts with the permissions the administrator granted it — which can reach further than the scopes on your token. The admin's `mcp:tools` grant is the real boundary, not this scope. No client preset selects it for you: a client has to ask for it by name.
 - Static tokens and web session JWTs have full access equivalent to all scopes, `plugins:use` included.
- Addon-gated tools (Packing, To-dos, Budget, Collections, Atlas, Collab, Vacay, Journey, Road trip, Dawarich, Document sync and AirTrail) require both the relevant scope **and** the corresponding addon to be enabled by an admin. The to-do tools ride the **Packing** addon (listed as **Lists** under **Admin → Addons**), not an addon of their own. The Road trip tools sit on `trips:*` and `places:write`, the Dawarich tools on `journey:*`, `places:write` and `atlas:write`, the Document sync tools on `files:*` under the **Documents** addon, and the AirTrail tools on `reservations:*`; without the addon, a client holding those scopes does not see them.
+- Addon-gated tools (Packing, To-dos, Budget, Collections, Atlas, Collab, Vacay, Journey, Tours, Road trip, Dawarich, Document sync and AirTrail) require both the relevant scope **and** the corresponding addon to be enabled by an admin. The to-do tools ride the **Packing** addon (listed as **Lists** under **Admin → Addons**), not an addon of their own. The Tours tools sit on `trips:*` (and on `collections:*` for tours kept in a collection), the Road trip tools on `trips:*` and `places:write`, the Dawarich tools on `journey:*`, `places:write` and `atlas:write`, the Document sync tools on `files:*` under the **Documents** addon, and the AirTrail tools on `reservations:*`; without the addon, a client holding those scopes does not see them.

 ## Choosing the right scopes

@@ -19,6 +19,8 @@ Claude.ai (web) supports native MCP connections — no JSON config file required
 3. Give the client a name, adjust scopes if needed, and save. Copy the client ID and client secret (`trekcs_` prefix) — the secret is shown only once.
 4. In Claude.ai, open the MCP settings and add a new server using your TREK URL (`https://<your-trek-instance>/mcp`). Claude.ai will open your browser to complete the OAuth consent flow.

+**Without a pre-created client.** Claude.ai can also identify itself by a metadata URL instead of a registered client. TREK fetches that small JSON document, checks it and shows the consent screen with the line **Verified domain**, naming the host the document came from. Only after you approve does TREK keep the client, and a client nobody uses is cleaned up again later. You do not have to do anything for this; it works when you add the server in Claude.ai and skip the steps above.
+
 ### Claude Desktop

 Claude Desktop supports native MCP connections — no JSON config file required:
@@ -4,7 +4,7 @@ TREK exposes **tools** (read and write actions) and **resources** (read-only `tr

 Every built-in tool checks its arguments against its published schema before anything runs. An argument the tool does not declare (a misspelt field such as `stopType` for `stop_type`) is refused with `Unrecognized key`, so the AI sees the mistake and can retry rather than reporting a change that never happened. Plugin-contributed tools follow the schema their manifest declares.

-For addon-gated tools (Packing, To-Dos, Atlas, Collab, Collections, Vacay, Journey, Dawarich, Document sync, Road trip) and their resources, see [MCP-Addon-Tools](MCP-Addon-Tools).
+For addon-gated tools (Packing, To-Dos, Atlas, Collab, Collections, Vacay, Journey including the link between a trip and a journal, Dawarich, Document sync, Tours, Road trip) and their resources, see [MCP-Addon-Tools](MCP-Addon-Tools).

 ## Tools