From e4f1a56c76aecd2d83a134bee71f51676e03793d Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Thu, 29 Jan 2026 10:04:05 -0600 Subject: [PATCH] Add server-side persistence guidance to view state pattern Clarifies when to use `localStorage` vs server-side storage for view state: - Scope section intro to "recoverable" view state (easy to recreate) - Add guidance for state representing user effort (bookmarks, annotations, custom configurations) to use app-only tools instead - Note that `viewUUID` should also be passed to app-only tools for scoping - Clarify that example links are specifically for `localStorage` approach Co-Authored-By: Claude Opus 4.5 --- docs/patterns.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/patterns.md b/docs/patterns.md index 9ac20cf..efdf6e9 100644 --- a/docs/patterns.md +++ b/docs/patterns.md @@ -499,7 +499,7 @@ await app.sendMessage({ ## Persisting view state -To persist view state across conversation reloads (e.g., current page in a PDF viewer, camera position in a map), use [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) with a stable identifier provided by the server. +For recoverable view state (e.g., current page in a PDF viewer, camera position in a map), use [`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) with a stable identifier provided by the server. **Server-side**: Tool handler generates a unique `viewUUID` and returns it in `CallToolResult._meta.viewUUID`: @@ -561,8 +561,10 @@ app.ontoolresult = (result) => { // e.g., saveState({ currentPage: 5 }); ``` +For state that represents user effort (e.g., saved bookmarks, annotations, custom configurations), consider persisting it server-side using [app-only tools](#tools-that-are-private-to-apps) instead. Pass the `viewUUID` to the app-only tool to scope the saved data to that view instance. + > [!NOTE] -> For full examples that implement this pattern, see: [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server) (persists current page) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (persists camera position). +> For full examples using `localStorage`, see: [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/pdf-server) (persists current page) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (persists camera position). ## Pausing computation-heavy views when offscreen