fix(examples): improve updateModelContext with structured YAML frontmatter (#271)

* map-server: fix async/await in ontoolresult, remove unused getViewStorageKey

* fix(map-server): improve updateModelContext and fix initialization

- Use structured YAML frontmatter format for model context (like pdf-server)
- Add tool name, altitude, and cleaner data format
- Fix initialization deadlock: app.connect() was inside ontoolresult handler
  which could never fire until connected
- Fix view state persistence: widgetUUID now properly extracted from
  ontoolresult and used to restore persisted camera position
- Server now includes widgetUUID in tool result _meta for widget identification

* fix(pdf-server): use widgetUUID for page persistence

- Add widgetUUID to tool result _meta for widget identification
- Use widgetUUID instead of generated key (pdfUrl+toolId) for localStorage
- Enables reliable page restoration when revisiting PDF widgets

* fix(transcript-server): use structured YAML frontmatter for model context

- Add tool name, listening status, and unsent entry count in frontmatter
- Consistent format with pdf-server and map-server

* update names

* drop bogus altitude

* Update mcp-app.ts

examples/pdf-server/server.ts

@@ -21,6 +21,7 @@ import type {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
+import { randomUUID } from "crypto";
 
 import {
   buildPdfIndex,
@@ -175,6 +176,9 @@ The viewer supports zoom, navigation, text selection, and fullscreen mode.`,
           },
         ],
         structuredContent: result,
+        _meta: {
+          widgetUUID: randomUUID(),
+        },
       };
     },
   );

examples/pdf-server/src/mcp-app.ts

@@ -35,6 +35,7 @@ let totalPages = 0;
 let scale = 1.0;
 let pdfUrl = "";
 let pdfTitle: string | undefined;
+let widgetUUID: string | undefined;
 let currentRenderTask: { cancel: () => void } | null = null;
 
 // DOM Elements
@@ -402,20 +403,11 @@ async function renderPage() {
   }
 }
 
-// Page persistence
-function getStorageKey(): string | null {
-  if (!pdfUrl) return null;
-  const ctx = app.getHostContext();
-  const toolId = ctx?.toolInfo?.id ?? pdfUrl;
-  return `pdf:${pdfUrl}:${toolId}`;
-}
-
 function saveCurrentPage() {
-  const key = getStorageKey();
-  log.info("saveCurrentPage: key=", key, "page=", currentPage);
-  if (key) {
+  log.info("saveCurrentPage: key=", widgetUUID, "page=", currentPage);
+  if (widgetUUID) {
     try {
-      localStorage.setItem(key, String(currentPage));
+      localStorage.setItem(widgetUUID, String(currentPage));
       log.info("saveCurrentPage: saved successfully");
     } catch (err) {
       log.error("saveCurrentPage: error", err);
@@ -424,11 +416,10 @@ function saveCurrentPage() {
 }
 
 function loadSavedPage(): number | null {
-  const key = getStorageKey();
-  log.info("loadSavedPage: key=", key);
-  if (!key) return null;
+  log.info("loadSavedPage: key=", widgetUUID);
+  if (!widgetUUID) return null;
   try {
-    const saved = localStorage.getItem(key);
+    const saved = localStorage.getItem(widgetUUID);
     log.info("loadSavedPage: saved value=", saved);
     if (saved) {
       const page = parseInt(saved, 10);
@@ -715,6 +706,9 @@ app.ontoolresult = async (result) => {
   pdfUrl = parsed.url;
   pdfTitle = parsed.title;
   totalPages = parsed.pageCount;
+  widgetUUID = result._meta?.widgetUUID
+    ? String(result._meta.widgetUUID)
+    : undefined;
 
   // Restore saved page or use initial page
   const savedPage = loadSavedPage();