From f992511e75121a6aec668229c16fb42062a8b5b0 Mon Sep 17 00:00:00 2001
From: r3dbars <r3dbars@users.noreply.github.com>
Date: Tue, 7 Jul 2026 15:28:57 -0500
Subject: [PATCH] feat(mcp): add MCP Apps recent-meetings UI widget

Expose an interactive "recent meetings" widget from the Transcripted MCP
server via the MCP Apps extension (io.modelcontextprotocol/ui, SEP-1865):
a card list of the N most recent meetings, each with inline audio playback
and a raw-transcript view, rendered inside a rendering-capable agent client.

- show_recent_meetings tool returns a self-contained text/html;profile=mcp-app
  widget as an inline embedded resource + structuredContent + a text fallback,
  linked via _meta.ui.resourceUri and openai/outputTemplate.
- ui://transcripted/recent-meetings.html registered as a readable resource.
- Reuses the existing meeting/transcript/audio access; adds a UI layer, not
  new data plumbing. Audio is base64-inlined (size-capped) and plays from a
  data: URI under the MCP Apps default sandbox CSP.
- Fully local: no network, no CDN. Local audio/transcripts travel with the
  widget over the local stdio transport; nothing leaves the Mac.
- Theme-aware (light/dark). 11 new tests; full MCP suite green (170).

Renders inline today in ChatGPT, VS Code, Cursor, and Goose. Claude
Desktop/web is announced but unverified on some builds; the Claude Code CLI
shows the text fallback (no iframe surface). See docs/mcp-ui-recent-meetings.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Tools/TranscriptedMCP/README.md               |  12 +
 .../Sources/TranscriptedMCP/Main.swift        |   8 +-
 .../RecentMeetingsWidget.swift                | 361 ++++++++++++++++++
 .../RecentMeetingsWidgetBuilder.swift         | 228 +++++++++++
 .../TranscriptedMCP/ToolHandlers.swift        |  20 +
 .../TranscriptedMCP/UIResourceHandlers.swift  | 164 ++++++++
 .../RecentMeetingsWidgetTests.swift           | 243 ++++++++++++
 docs/mcp-ui-recent-meetings.md                | 110 ++++++
 8 files changed, 1145 insertions(+), 1 deletion(-)
 create mode 100644 Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidget.swift
 create mode 100644 Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidgetBuilder.swift
 create mode 100644 Tools/TranscriptedMCP/Sources/TranscriptedMCP/UIResourceHandlers.swift
 create mode 100644 Tools/TranscriptedMCP/Tests/TranscriptedMCPTests/RecentMeetingsWidgetTests.swift
 create mode 100644 docs/mcp-ui-recent-meetings.md

diff --git a/Tools/TranscriptedMCP/README.md b/Tools/TranscriptedMCP/README.md
index c94d0eaa..c0bc785c 100644
--- a/Tools/TranscriptedMCP/README.md
+++ b/Tools/TranscriptedMCP/README.md
@@ -13,6 +13,18 @@ For Claude Desktop users, the best setup is inside the app:
 That path installs the bundled helper, updates Claude Desktop's config, and
 runs a local self-test.
 
+## Interactive UI (MCP Apps)
+
+The server exposes one interactive widget via the MCP Apps extension
+(`io.modelcontextprotocol/ui`, SEP-1865): call `show_recent_meetings` to render a
+card list of recent meetings — each with inline audio playback and a raw-transcript
+view — that draws inside a rendering-capable client. It is fully self-contained
+(no network; local audio/transcripts travel over the local transport), and falls
+back to a plain-text list in clients that do not render inline UI (e.g. the Claude
+Code CLI). Renders inline today in ChatGPT, VS Code, Cursor, and Goose; see
+[`docs/mcp-ui-recent-meetings.md`](../../docs/mcp-ui-recent-meetings.md) for the
+per-client support matrix and how to try it.
+
 ## Source Build
 
 Use this only when developing the MCP server directly:
diff --git a/Tools/TranscriptedMCP/Sources/TranscriptedMCP/Main.swift b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/Main.swift
index c9c88f34..2c84a35a 100644
--- a/Tools/TranscriptedMCP/Sources/TranscriptedMCP/Main.swift
+++ b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/Main.swift
@@ -69,10 +69,16 @@ struct TranscriptedMCP {
         let server = Server(
             name: "transcripted",
             version: serverVersion,
-            capabilities: .init(tools: .init(listChanged: false))
+            capabilities: .init(
+                resources: .init(subscribe: false, listChanged: false),
+                tools: .init(listChanged: false)
+            )
         )
 
         await registerToolHandlers(server: server, index: index, directories: directories)
+        await TranscriptedUIResources.register(
+            server: server, index: index, directories: directories, serverVersion: serverVersion
+        )
 
         log("MCP server ready, waiting for connections")
 
diff --git a/Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidget.swift b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidget.swift
new file mode 100644
index 00000000..19b06b59
--- /dev/null
+++ b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidget.swift
@@ -0,0 +1,361 @@
+import Foundation
+import TranscriptedCaptureKit
+
+// MARK: - Widget data model
+
+/// One meeting rendered as a card in the recent-meetings widget. This is the
+/// contract between the data builder (which reads the local capture library)
+/// and the self-contained HTML renderer. It is also the `structuredContent`
+/// shape a spec-compliant MCP Apps host receives via `ui/notifications/tool-result`,
+/// so a template that reads `window.openai.toolOutput` renders the same view as
+/// the data baked into the HTML.
+struct WidgetMeeting: Codable, Hashable {
+    /// Human title (frontmatter title, else a filename-derived label).
+    let title: String
+    /// `YYYY-MM-DD` local date.
+    let date: String
+    /// ISO-8601 datetime when known (used only for display/sort stability).
+    let datetime: String
+    /// Recording length in seconds.
+    let durationSeconds: Int
+    /// Speaker display names, in transcript order.
+    let speakers: [String]
+    /// Total word count across the transcript.
+    let wordCount: Int
+    /// The `read_meeting` filename (stem) — lets an agent drill in for more.
+    let filename: String
+    /// Full dialogue text (bounded by the same read cap the read tools use).
+    let transcript: String
+    /// Inline audio, when a preferred track exists and fits the size budget.
+    let audio: WidgetAudio?
+    /// Absolute local path to the audio directory, for the "open in Finder"
+    /// fallback when audio is absent or too large to inline. Never leaves the Mac.
+    let audioDirectory: String?
+    /// Why inline audio is unavailable, when it is (missing vs. over budget).
+    let audioNote: String?
+
+    enum CodingKeys: String, CodingKey {
+        case title, date, datetime
+        case durationSeconds = "duration_seconds"
+        case speakers
+        case wordCount = "word_count"
+        case filename, transcript, audio
+        case audioDirectory = "audio_directory"
+        case audioNote = "audio_note"
+    }
+}
+
+/// A base64 `data:` audio payload the widget plays with a plain `<audio>`
+/// element. `data:` media is allowed under the MCP Apps default sandbox CSP
+/// (`media-src 'self' data:`), so this plays with no network access — the audio
+/// bytes travel with the widget over the local stdio transport and never touch
+/// a remote host.
+struct WidgetAudio: Codable, Hashable {
+    /// `data:audio/<subtype>;base64,<...>`
+    let dataURI: String
+    /// e.g. `audio/mp4`.
+    let mimeType: String
+    /// Track label ("Mix", "System", "Mic", …).
+    let label: String
+    /// Raw (pre-base64) size in bytes, for display.
+    let sizeBytes: Int
+
+    enum CodingKeys: String, CodingKey {
+        case dataURI = "data_uri"
+        case mimeType = "mime_type"
+        case label
+        case sizeBytes = "size_bytes"
+    }
+}
+
+/// The full payload rendered by the widget and returned as `structuredContent`.
+struct RecentMeetingsWidgetModel: Codable, Hashable {
+    let serverName: String
+    let serverVersion: String
+    /// `YYYY-MM-DD` the payload was generated (display only).
+    let generatedDate: String
+    let meetings: [WidgetMeeting]
+
+    enum CodingKeys: String, CodingKey {
+        case serverName = "server_name"
+        case serverVersion = "server_version"
+        case generatedDate = "generated_date"
+        case meetings
+    }
+}
+
+// MARK: - Renderer
+
+enum RecentMeetingsWidget {
+    /// Stable `ui://` URI for the recent-meetings surface. The `text/html;profile=mcp-app`
+    /// resource and the tool's `_meta.ui.resourceUri` both point here.
+    static let resourceURI = "ui://transcripted/recent-meetings.html"
+    static let resourceMimeType = "text/html;profile=mcp-app"
+
+    /// Render a self-contained HTML document for the given model. Inline CSS/JS,
+    /// no external network, theme-aware (honors `prefers-color-scheme` and a
+    /// host-provided theme). The data is baked into a `<script type="application/json">`
+    /// block so the page renders identically standalone, from `resources/read`,
+    /// or inline in a tool result; when a spec-compliant host later pushes fresh
+    /// data via `ui/notifications/tool-result` or `window.openai.toolOutput`, the
+    /// widget re-renders from that instead.
+    static func html(for model: RecentMeetingsWidgetModel) -> String {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.withoutEscapingSlashes]
+        let jsonData = (try? encoder.encode(model)) ?? Data("{}".utf8)
+        var json = String(decoding: jsonData, as: UTF8.self)
+        // Neutralize any "</script" so the JSON cannot break out of the script tag.
+        json = json.replacingOccurrences(of: "</", with: "<\\/")
+
+        return """
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+        <meta charset="utf-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <title>Recent meetings — Transcripted</title>
+        <style>\(css)</style>
+        </head>
+        <body>
+        <main id="tx-root" aria-live="polite"></main>
+        <script id="tx-data" type="application/json">\(json)</script>
+        <script>\(js)</script>
+        </body>
+        </html>
+        """
+    }
+
+    // MARK: Inline CSS
+
+    private static let css = """
+        :root {
+          color-scheme: light dark;
+          --bg: transparent;
+          --card: #ffffff;
+          --card-border: #e6e6e9;
+          --text: #1a1a1e;
+          --muted: #6b6b76;
+          --accent: #2f6df6;
+          --accent-contrast: #ffffff;
+          --chip: #f1f2f5;
+          --pre-bg: #f7f7f9;
+          --shadow: 0 1px 2px rgba(0,0,0,.05), 0 1px 8px rgba(0,0,0,.04);
+        }
+        @media (prefers-color-scheme: dark) {
+          :root {
+            --card: #1c1c20;
+            --card-border: #313138;
+            --text: #ececf1;
+            --muted: #9a9aa6;
+            --accent: #5b8cff;
+            --accent-contrast: #0d0d10;
+            --chip: #2a2a31;
+            --pre-bg: #141417;
+            --shadow: 0 1px 2px rgba(0,0,0,.4), 0 1px 8px rgba(0,0,0,.3);
+          }
+        }
+        :root[data-theme="dark"] {
+          --card: #1c1c20; --card-border: #313138; --text: #ececf1; --muted: #9a9aa6;
+          --accent: #5b8cff; --accent-contrast: #0d0d10; --chip: #2a2a31; --pre-bg: #141417;
+          --shadow: 0 1px 2px rgba(0,0,0,.4), 0 1px 8px rgba(0,0,0,.3);
+        }
+        :root[data-theme="light"] {
+          --card: #ffffff; --card-border: #e6e6e9; --text: #1a1a1e; --muted: #6b6b76;
+          --accent: #2f6df6; --accent-contrast: #ffffff; --chip: #f1f2f5; --pre-bg: #f7f7f9;
+          --shadow: 0 1px 2px rgba(0,0,0,.05), 0 1px 8px rgba(0,0,0,.04);
+        }
+        * { box-sizing: border-box; }
+        body {
+          margin: 0;
+          background: var(--bg);
+          color: var(--text);
+          font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+          -webkit-font-smoothing: antialiased;
+        }
+        main { padding: 12px; max-width: 720px; margin: 0 auto; }
+        .head { display: flex; align-items: baseline; justify-content: space-between; margin: 2px 4px 12px; gap: 8px; }
+        .head h1 { font-size: 15px; font-weight: 650; margin: 0; letter-spacing: -.01em; }
+        .head .sub { font-size: 12px; color: var(--muted); }
+        .card {
+          background: var(--card);
+          border: 1px solid var(--card-border);
+          border-radius: 12px;
+          padding: 12px 14px;
+          margin-bottom: 10px;
+          box-shadow: var(--shadow);
+        }
+        .card h2 { font-size: 14px; font-weight: 620; margin: 0 0 4px; letter-spacing: -.01em; }
+        .meta { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 8px; }
+        .chip {
+          font-size: 11px; color: var(--muted); background: var(--chip);
+          padding: 2px 8px; border-radius: 999px; white-space: nowrap;
+        }
+        .actions { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; }
+        button {
+          font: inherit; font-size: 12.5px; font-weight: 550;
+          border: 1px solid var(--card-border); background: var(--card); color: var(--text);
+          padding: 5px 11px; border-radius: 8px; cursor: pointer; line-height: 1.2;
+        }
+        button:hover { border-color: var(--accent); }
+        button.play { background: var(--accent); color: var(--accent-contrast); border-color: transparent; }
+        button:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+        .note { font-size: 12px; color: var(--muted); }
+        .note code { background: var(--chip); padding: 1px 5px; border-radius: 5px; font-size: 11px; }
+        audio { width: 100%; margin-top: 10px; display: block; }
+        .transcript { margin-top: 10px; }
+        .transcript pre {
+          background: var(--pre-bg); border: 1px solid var(--card-border); border-radius: 8px;
+          padding: 10px 12px; margin: 0; max-height: 320px; overflow: auto;
+          white-space: pre-wrap; word-break: break-word; font-size: 12.5px; line-height: 1.55;
+          font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        }
+        .empty { color: var(--muted); text-align: center; padding: 28px 12px; }
+        [hidden] { display: none !important; }
+        """
+
+    // MARK: Inline JS
+
+    private static let js = #"""
+        (function () {
+          "use strict";
+          var root = document.getElementById("tx-root");
+
+          function fmtDuration(s) {
+            s = Math.max(0, Math.round(s || 0));
+            var h = Math.floor(s / 3600), m = Math.floor((s % 3600) / 60), sec = s % 60;
+            function p(n) { return (n < 10 ? "0" : "") + n; }
+            return h > 0 ? h + ":" + p(m) + ":" + p(sec) : m + ":" + p(sec);
+          }
+          function fmtBytes(b) {
+            if (!b) return "";
+            if (b >= 1048576) return (b / 1048576).toFixed(1) + " MB";
+            if (b >= 1024) return Math.round(b / 1024) + " KB";
+            return b + " B";
+          }
+          function fmtDate(d) {
+            if (!d) return "";
+            var parts = String(d).split("-");
+            if (parts.length !== 3) return d;
+            var months = ["Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec"];
+            var mo = months[parseInt(parts[1], 10) - 1] || parts[1];
+            return mo + " " + parseInt(parts[2], 10) + ", " + parts[0];
+          }
+          function el(tag, cls, text) {
+            var e = document.createElement(tag);
+            if (cls) e.className = cls;
+            if (text != null) e.textContent = text;
+            return e;
+          }
+
+          function renderCard(m) {
+            var card = el("div", "card");
+            card.appendChild(el("h2", null, m.title || m.filename || "Untitled meeting"));
+
+            var meta = el("div", "meta");
+            [fmtDate(m.date), fmtDuration(m.duration_seconds),
+             (m.speakers && m.speakers.length ? m.speakers.join(", ") : null),
+             (m.word_count ? m.word_count.toLocaleString() + " words" : null)
+            ].forEach(function (v) { if (v) meta.appendChild(el("span", "chip", v)); });
+            card.appendChild(meta);
+
+            var actions = el("div", "actions");
+
+            // Play control
+            if (m.audio && m.audio.data_uri) {
+              var playBtn = el("button", "play", "▶ Play" + (m.audio.label ? " (" + m.audio.label + ")" : ""));
+              var audio = null;
+              playBtn.addEventListener("click", function () {
+                if (!audio) {
+                  audio = document.createElement("audio");
+                  audio.controls = true;
+                  audio.preload = "none";
+                  audio.src = m.audio.data_uri;
+                  card.appendChild(audio);
+                }
+                audio.hidden = false;
+                audio.play().catch(function () { /* gesture/autoplay policy: controls remain usable */ });
+                playBtn.textContent = "⏸ Playing" + (m.audio.label ? " (" + m.audio.label + ")" : "");
+                playBtn.disabled = false;
+              });
+              actions.appendChild(playBtn);
+            } else if (m.audio_directory) {
+              var noAudio = el("span", "note");
+              noAudio.appendChild(document.createTextNode((m.audio_note || "Audio not embedded") + " — "));
+              var code = el("code", null, m.audio_directory);
+              noAudio.appendChild(code);
+              actions.appendChild(noAudio);
+            }
+
+            // Transcript toggle
+            if (m.transcript) {
+              var tBtn = el("button", null, "View raw transcript");
+              var wrap = el("div", "transcript");
+              wrap.hidden = true;
+              var pre = el("pre");
+              pre.textContent = m.transcript;
+              wrap.appendChild(pre);
+              tBtn.addEventListener("click", function () {
+                wrap.hidden = !wrap.hidden;
+                tBtn.textContent = wrap.hidden ? "View raw transcript" : "Hide transcript";
+              });
+              actions.appendChild(tBtn);
+              card.appendChild(actions);
+              card.appendChild(wrap);
+            } else {
+              card.appendChild(actions);
+            }
+            return card;
+          }
+
+          function render(model) {
+            root.textContent = "";
+            var meetings = (model && model.meetings) || [];
+            var head = el("div", "head");
+            head.appendChild(el("h1", null, "Recent meetings"));
+            head.appendChild(el("span", "sub", meetings.length + (meetings.length === 1 ? " meeting" : " meetings")));
+            root.appendChild(head);
+            if (!meetings.length) {
+              root.appendChild(el("div", "empty", "No recent meetings found."));
+              return;
+            }
+            meetings.forEach(function (m) { root.appendChild(renderCard(m)); });
+          }
+
+          function applyTheme(theme) {
+            if (theme === "dark" || theme === "light") {
+              document.documentElement.setAttribute("data-theme", theme);
+            }
+          }
+
+          // 1) Baked data — the default, works standalone and self-contained.
+          var baked = {};
+          try {
+            var node = document.getElementById("tx-data");
+            baked = node ? JSON.parse(node.textContent) : {};
+          } catch (e) { baked = {}; }
+          render(baked);
+
+          // 2) Progressive enhancement for spec-compliant MCP Apps hosts:
+          //    prefer live tool output / theme when the host provides it.
+          try {
+            if (window.openai) {
+              if (window.openai.theme) applyTheme(window.openai.theme);
+              if (window.openai.toolOutput && window.openai.toolOutput.meetings) {
+                render(window.openai.toolOutput);
+              }
+            }
+          } catch (e) { /* ignore */ }
+
+          window.addEventListener("message", function (event) {
+            var d = event && event.data;
+            if (!d) return;
+            var method = d.method || (d.type);
+            if (method && String(method).indexOf("tool-result") !== -1) {
+              var payload = (d.params && (d.params.structuredContent || d.params.result)) || d.payload || d.structuredContent;
+              if (payload && payload.meetings) render(payload);
+            }
+            if (d.params && d.params.theme) applyTheme(d.params.theme);
+          });
+        })();
+        """#
+}
diff --git a/Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidgetBuilder.swift b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidgetBuilder.swift
new file mode 100644
index 00000000..3d47ad0c
--- /dev/null
+++ b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/RecentMeetingsWidgetBuilder.swift
@@ -0,0 +1,228 @@
+import Foundation
+import TranscriptedCaptureKit
+
+/// Builds the recent-meetings widget model from the local capture library. This
+/// reuses the same meeting/transcript/audio access the read tools use — it adds
+/// a UI layer on top of the existing data surface, it does not re-plumb data.
+///
+/// Everything served here is local: transcripts are read from the capture
+/// Markdown, audio bytes from the sibling `audio/<stem>_audio/` bundle. The bytes
+/// are base64-inlined into the widget and travel over the local stdio transport;
+/// nothing is fetched from or sent to a remote host.
+enum RecentMeetingsWidgetBuilder {
+    /// Per-meeting inline audio ceiling. Above this the card shows the audio
+    /// folder path instead of embedding — keeps a single widget response bounded.
+    /// Inlining is deliberately capped: base64 audio travels in the tool result,
+    /// and some hosts limit message size. Longer recordings fall back to the
+    /// local path (the future scaling path is lazy fetch over the postMessage
+    /// bridge, documented in docs/mcp-ui-recent-meetings.md).
+    static let defaultMaxAudioBytesPerMeeting = 4 * 1024 * 1024
+    /// Whole-widget inline audio ceiling across all cards.
+    static let defaultMaxAudioBytesTotal = 8 * 1024 * 1024
+
+    /// Preferred playback stems, best-listening first — mirrors the app's
+    /// `MeetingAudioArchiveResolver` ordering so the widget plays the same track
+    /// the app would.
+    private static let preferredStems = ["playback", "recording", "system_audio", "microphone"]
+    private static let audioExtensions = ["m4a", "wav", "aiff", "aif", "mp3", "caf", "flac"]
+
+    static func build(
+        index: TranscriptIndex,
+        meetingDirs: [URL],
+        count: Int,
+        generatedDate: String,
+        serverName: String,
+        serverVersion: String,
+        maxAudioBytesPerMeeting: Int = defaultMaxAudioBytesPerMeeting,
+        maxAudioBytesTotal: Int = defaultMaxAudioBytesTotal
+    ) throws -> RecentMeetingsWidgetModel {
+        let summaries = try index.listMeetings(count: count)
+        var meetings: [WidgetMeeting] = []
+        var audioBudget = maxAudioBytesTotal
+
+        for summary in summaries {
+            guard let mdURL = resolveMeetingFile(named: summary.filename, in: meetingDirs) else {
+                meetings.append(placeholder(from: summary))
+                continue
+            }
+            let content = CaptureMarkdown.readBoundedContents(of: mdURL) ?? ""
+            let title = CaptureMarkdown.extractTitle(from: content) ?? summary.title ?? summary.filename
+            let transcript = transcriptText(from: content)
+            let speakerNames = summary.speakers.map(\.name)
+
+            let audioDir = audioDirectory(for: mdURL)
+            let (audio, note) = resolveAudio(
+                in: audioDir, perMeetingCap: maxAudioBytesPerMeeting, remainingBudget: audioBudget
+            )
+            if let audio { audioBudget -= audio.sizeBytes }
+
+            meetings.append(WidgetMeeting(
+                title: title,
+                date: summary.date,
+                datetime: summary.datetime,
+                durationSeconds: summary.durationSeconds,
+                speakers: speakerNames,
+                wordCount: summary.wordCount,
+                filename: summary.filename,
+                transcript: transcript,
+                audio: audio,
+                audioDirectory: FileManager.default.fileExists(atPath: audioDir.path) ? audioDir.path : nil,
+                audioNote: note
+            ))
+        }
+
+        return RecentMeetingsWidgetModel(
+            serverName: serverName,
+            serverVersion: serverVersion,
+            generatedDate: generatedDate,
+            meetings: meetings
+        )
+    }
+
+    /// Resolve a meeting Markdown file across the configured meeting directories,
+    /// applying the shared traversal/symlink guard.
+    private static func resolveMeetingFile(named name: String, in dirs: [URL]) -> URL? {
+        for dir in dirs {
+            if case .valid(let url) = PathSecurity.resolveReadableFile(named: name, appendingExtension: "md", in: dir) {
+                return url
+            }
+        }
+        return nil
+    }
+
+    // MARK: - Transcript
+
+    /// Speaker-labeled dialogue, bounded by the same read cap the read tools use
+    /// so one long meeting can't blow out the widget payload.
+    static func transcriptText(from content: String) -> String {
+        guard let parsed = CaptureMarkdownParser.parseMeeting(from: content),
+              !parsed.utterances.isEmpty else {
+            // Fall back to the raw dialogue block for files the parser can't window.
+            return boundedDialogue(from: content)
+        }
+        let names = Dictionary(uniqueKeysWithValues: parsed.speakers.map { ($0.id, $0.name) })
+        var out = ""
+        for utterance in parsed.utterances {
+            let speaker = names[utterance.speakerId] ?? utterance.speakerId
+            let line = "\(speaker): \(utterance.text)\n"
+            if out.count + line.count > maxUnpaginatedReadCharacters {
+                out += "\n… transcript truncated. Use read_meeting \"\(parsed.datetime)\" for the full text."
+                break
+            }
+            out += line
+        }
+        return out.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private static func boundedDialogue(from content: String) -> String {
+        let markers = ["## Full Transcript\n", "## Transcript\n"]
+        guard let range = markers.compactMap({ content.range(of: $0) }).first else { return "" }
+        let body = String(content[range.upperBound...])
+            .components(separatedBy: "\n")
+            .filter { !$0.isEmpty && !$0.hasPrefix("*Generated by") && $0 != "---" }
+            .joined(separator: "\n")
+        if body.count > maxUnpaginatedReadCharacters {
+            return String(body.prefix(maxUnpaginatedReadCharacters)) + "\n… transcript truncated."
+        }
+        return body
+    }
+
+    // MARK: - Audio
+
+    /// `<meetingDir>/audio/<stem>_audio/` — the same layout the app writes via
+    /// `MeetingArtifactRenamer.audioDirectoryURL`.
+    static func audioDirectory(for transcriptURL: URL) -> URL {
+        transcriptURL
+            .deletingLastPathComponent()
+            .appendingPathComponent("audio", isDirectory: true)
+            .appendingPathComponent("\(transcriptURL.deletingPathExtension().lastPathComponent)_audio", isDirectory: true)
+    }
+
+    /// Resolve the preferred playback file and, if it fits the caps, base64-inline
+    /// it. Returns `(nil, note)` when audio is missing or too large, so the card
+    /// can fall back to the folder path.
+    private static func resolveAudio(
+        in audioDir: URL,
+        perMeetingCap: Int,
+        remainingBudget: Int
+    ) -> (WidgetAudio?, String?) {
+        var isDir: ObjCBool = false
+        guard FileManager.default.fileExists(atPath: audioDir.path, isDirectory: &isDir), isDir.boolValue else {
+            return (nil, "No recording found")
+        }
+        guard let fileURL = preferredAudioFile(in: audioDir) else {
+            return (nil, "No recording found")
+        }
+        // The audio dir is derived from an already-validated transcript URL; confirm
+        // the chosen file is a real regular file under it (no symlink escape).
+        guard case .valid(let safeURL) = PathSecurity.validateExistingFile(fileURL, under: audioDir) else {
+            return (nil, "Recording unavailable")
+        }
+
+        let size = (try? safeURL.resourceValues(forKeys: [.fileSizeKey]).fileSize) ?? 0
+        let cap = min(perMeetingCap, remainingBudget)
+        if size > cap {
+            let mb = String(format: "%.1f", Double(size) / 1_048_576)
+            return (nil, "Recording (\(mb) MB) too large to embed")
+        }
+        guard let data = try? Data(contentsOf: safeURL), !data.isEmpty else {
+            return (nil, "Recording unavailable")
+        }
+
+        let stem = safeURL.deletingPathExtension().lastPathComponent
+        let mime = mimeType(forExtension: safeURL.pathExtension)
+        let uri = "data:\(mime);base64,\(data.base64EncodedString())"
+        return (WidgetAudio(dataURI: uri, mimeType: mime, label: label(forStem: stem), sizeBytes: data.count), nil)
+    }
+
+    private static func preferredAudioFile(in audioDir: URL) -> URL? {
+        let files = (try? FileManager.default.contentsOfDirectory(
+            at: audioDir, includingPropertiesForKeys: nil, options: [.skipsHiddenFiles]
+        )) ?? []
+        let audioFiles = files.filter { audioExtensions.contains($0.pathExtension.lowercased()) }
+        guard !audioFiles.isEmpty else { return nil }
+        for stem in preferredStems {
+            if let match = audioFiles.first(where: { $0.deletingPathExtension().lastPathComponent == stem }) {
+                return match
+            }
+        }
+        return audioFiles.sorted { $0.lastPathComponent < $1.lastPathComponent }.first
+    }
+
+    private static func mimeType(forExtension ext: String) -> String {
+        switch ext.lowercased() {
+        case "m4a", "mp4", "caf": return "audio/mp4"
+        case "wav": return "audio/wav"
+        case "aiff", "aif": return "audio/aiff"
+        case "mp3": return "audio/mpeg"
+        case "flac": return "audio/flac"
+        default: return "audio/mp4"
+        }
+    }
+
+    private static func label(forStem stem: String) -> String {
+        switch stem {
+        case "playback": return "Mix"
+        case "recording": return "Recording"
+        case "system_audio": return "System"
+        case "microphone": return "Mic"
+        default: return "Audio"
+        }
+    }
+
+    private static func placeholder(from summary: MeetingSummary) -> WidgetMeeting {
+        WidgetMeeting(
+            title: summary.title ?? summary.filename,
+            date: summary.date,
+            datetime: summary.datetime,
+            durationSeconds: summary.durationSeconds,
+            speakers: summary.speakers.map(\.name),
+            wordCount: summary.wordCount,
+            filename: summary.filename,
+            transcript: "",
+            audio: nil,
+            audioDirectory: nil,
+            audioNote: "Meeting file unavailable"
+        )
+    }
+}
diff --git a/Tools/TranscriptedMCP/Sources/TranscriptedMCP/ToolHandlers.swift b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/ToolHandlers.swift
index 1c5090e5..840b173b 100644
--- a/Tools/TranscriptedMCP/Sources/TranscriptedMCP/ToolHandlers.swift
+++ b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/ToolHandlers.swift
@@ -537,6 +537,21 @@ func registerToolHandlers(server: Server, index: TranscriptIndex, directories: T
                 ]),
                 annotations: .init(readOnlyHint: true)
             ),
+            Tool(
+                name: "show_recent_meetings",
+                description: "Render an interactive card list of the most recent meetings — each with audio playback and a raw-transcript view — as an MCP Apps (SEP-1865) UI widget that draws inline in rendering-capable clients. Clients that don't paint inline UI get a plain-text meeting list as a fallback. All audio and transcripts are local; nothing leaves this Mac.",
+                inputSchema: .object([
+                    "type": .string("object"),
+                    "properties": .object([
+                        "count": .object([
+                            "type": .string("integer"),
+                            "description": .string("Number of recent meetings to show (default: 5, max: 15)")
+                        ]),
+                    ]),
+                ]),
+                annotations: .init(readOnlyHint: true),
+                _meta: TranscriptedUIResources.toolMeta
+            ),
         ])
     }
 
@@ -577,6 +592,11 @@ func registerToolHandlers(server: Server, index: TranscriptIndex, directories: T
                 return try handleSearchMeetings(params: params, index: index, meetingDirs: directories.meetingDirs)
             case "status":
                 return try handleStatus(index: index, directories: directories)
+            case "show_recent_meetings":
+                let count = min(max(params.arguments?["count"]?.intValue ?? TranscriptedUIResources.defaultRecentCount, 1), 15)
+                return try TranscriptedUIResources.showRecentMeetingsResult(
+                    count: count, index: index, directories: directories, serverVersion: TranscriptedMCP.serverVersion
+                )
             default:
                 return textResult("Unknown tool: \(params.name)", isError: true)
             }
diff --git a/Tools/TranscriptedMCP/Sources/TranscriptedMCP/UIResourceHandlers.swift b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/UIResourceHandlers.swift
new file mode 100644
index 00000000..4eae3e3c
--- /dev/null
+++ b/Tools/TranscriptedMCP/Sources/TranscriptedMCP/UIResourceHandlers.swift
@@ -0,0 +1,164 @@
+import Foundation
+import MCP
+
+/// MCP Apps (SEP-1865, `io.modelcontextprotocol/ui`, spec 2026-01-26) surface for
+/// Transcripted: a `ui://` HTML resource that renders a "recent meetings" widget
+/// inline in a rendering-capable agent client, plus the `show_recent_meetings`
+/// tool that returns it.
+///
+/// Design notes:
+///   * The resource MIME is `text/html;profile=mcp-app` per the extension.
+///   * The tool links to the resource via `_meta.ui.resourceUri` (official) and
+///     `_meta["openai/outputTemplate"]` (OpenAI Apps SDK alias for ChatGPT).
+///   * The tool result also carries the fully data-baked HTML as an inline
+///     embedded resource (the mcp-ui `rawHtml` pattern) plus `structuredContent`,
+///     so the widget renders whether the host inlines the embedded resource,
+///     reads the template and pushes `structuredContent`, or is inspected
+///     standalone. Nothing here reaches the network.
+enum TranscriptedUIResources {
+    static let recentMeetingsResourceName = "recent_meetings"
+    static let defaultRecentCount = 5
+
+    /// Register `resources/list`, `resources/read`, and `resources/templates/list`
+    /// handlers that expose the recent-meetings widget.
+    static func register(
+        server: Server,
+        index: TranscriptIndex,
+        directories: TranscriptedDataDirectories,
+        serverVersion: String
+    ) async {
+        await server.withMethodHandler(ListResources.self) { _ in
+            .init(resources: [recentMeetingsResource])
+        }
+
+        await server.withMethodHandler(ListResourceTemplates.self) { _ in
+            .init(templates: [])
+        }
+
+        await server.withMethodHandler(ReadResource.self) { params in
+            guard params.uri == RecentMeetingsWidget.resourceURI else {
+                throw MCPError.invalidParams("Unknown resource: \(params.uri)")
+            }
+            let html = try renderRecentMeetingsHTML(
+                index: index, directories: directories, serverVersion: serverVersion
+            )
+            return .init(contents: [
+                .text(html, uri: RecentMeetingsWidget.resourceURI, mimeType: RecentMeetingsWidget.resourceMimeType)
+            ])
+        }
+    }
+
+    /// The resource descriptor returned by `resources/list`. The `_meta.ui` block
+    /// carries the MCP Apps hints (sandbox CSP is the permissive default; the
+    /// widget needs `media-src data:` for inline audio, which the default allows).
+    static var recentMeetingsResource: Resource {
+        Resource(
+            name: recentMeetingsResourceName,
+            uri: RecentMeetingsWidget.resourceURI,
+            title: "Recent meetings",
+            description: "Interactive card list of your most recent meetings, each with audio playback and a raw-transcript view. Renders inline in MCP Apps-capable clients.",
+            mimeType: RecentMeetingsWidget.resourceMimeType,
+            _meta: Metadata(additionalFields: [
+                "ui": .object([
+                    "preferredSize": .object(["width": .int(720), "height": .int(560)]),
+                    "prefersBorder": .bool(true)
+                ])
+            ])
+        )
+    }
+
+    /// `_meta` for the `show_recent_meetings` tool definition, linking the tool to
+    /// its UI resource for both the official extension and the OpenAI Apps SDK.
+    static var toolMeta: Metadata {
+        Metadata(additionalFields: [
+            "ui": .object([
+                "resourceUri": .string(RecentMeetingsWidget.resourceURI),
+                "visibility": .array([.string("model"), .string("app")])
+            ]),
+            "openai/outputTemplate": .string(RecentMeetingsWidget.resourceURI)
+        ])
+    }
+
+    /// Build the tool result for `show_recent_meetings`: a text fallback (what a
+    /// non-rendering client like the Claude Code CLI shows), the data-baked widget
+    /// HTML as an inline embedded resource, and `structuredContent` for hosts that
+    /// push tool output into the rendered template.
+    static func showRecentMeetingsResult(
+        count: Int,
+        index: TranscriptIndex,
+        directories: TranscriptedDataDirectories,
+        serverVersion: String
+    ) throws -> CallTool.Result {
+        let model = try RecentMeetingsWidgetBuilder.build(
+            index: index,
+            meetingDirs: directories.meetingDirs,
+            count: count,
+            generatedDate: DateFormatter.localYYYYMMDDString(from: Date()),
+            serverName: "transcripted",
+            serverVersion: serverVersion
+        )
+        let html = RecentMeetingsWidget.html(for: model)
+
+        let summary = textFallback(for: model)
+        let embedded = Resource.Content.text(
+            html, uri: RecentMeetingsWidget.resourceURI, mimeType: RecentMeetingsWidget.resourceMimeType
+        )
+
+        return try CallTool.Result(
+            content: [
+                .text(text: summary, annotations: nil, _meta: nil),
+                .resource(resource: embedded, annotations: nil, _meta: nil)
+            ],
+            structuredContent: model,
+            isError: false,
+            _meta: Metadata(additionalFields: [
+                "ui": .object(["resourceUri": .string(RecentMeetingsWidget.resourceURI)])
+            ])
+        )
+    }
+
+    static func renderRecentMeetingsHTML(
+        index: TranscriptIndex,
+        directories: TranscriptedDataDirectories,
+        serverVersion: String
+    ) throws -> String {
+        let model = try RecentMeetingsWidgetBuilder.build(
+            index: index,
+            meetingDirs: directories.meetingDirs,
+            count: defaultRecentCount,
+            generatedDate: DateFormatter.localYYYYMMDDString(from: Date()),
+            serverName: "transcripted",
+            serverVersion: serverVersion
+        )
+        return RecentMeetingsWidget.html(for: model)
+    }
+
+    /// Plain-text rendering of the widget model for clients that don't paint
+    /// inline HTML (terminals, or hosts that haven't shipped MCP Apps rendering).
+    static func textFallback(for model: RecentMeetingsWidgetModel) -> String {
+        guard !model.meetings.isEmpty else {
+            return "No recent meetings found."
+        }
+        var lines = ["Recent meetings (\(model.meetings.count)):"]
+        for meeting in model.meetings {
+            let mins = meeting.durationSeconds / 60
+            let secs = meeting.durationSeconds % 60
+            let duration = String(format: "%d:%02d", mins, secs)
+            let speakers = meeting.speakers.isEmpty ? "" : " · \(meeting.speakers.joined(separator: ", "))"
+            let audio = meeting.audio != nil ? " · ▶ audio" : ""
+            lines.append("• \(meeting.title) — \(meeting.date), \(duration)\(speakers)\(audio)")
+        }
+        lines.append("")
+        lines.append("Open the interactive widget in an MCP Apps-capable client to play audio and read transcripts inline.")
+        return lines.joined(separator: "\n")
+    }
+}
+
+extension DateFormatter {
+    static func localYYYYMMDDString(from date: Date) -> String {
+        let f = DateFormatter()
+        f.dateFormat = "yyyy-MM-dd"
+        f.locale = Locale(identifier: "en_US_POSIX")
+        return f.string(from: date)
+    }
+}
diff --git a/Tools/TranscriptedMCP/Tests/TranscriptedMCPTests/RecentMeetingsWidgetTests.swift b/Tools/TranscriptedMCP/Tests/TranscriptedMCPTests/RecentMeetingsWidgetTests.swift
new file mode 100644
index 00000000..4f3e2bf1
--- /dev/null
+++ b/Tools/TranscriptedMCP/Tests/TranscriptedMCPTests/RecentMeetingsWidgetTests.swift
@@ -0,0 +1,243 @@
+import MCP
+import XCTest
+@testable import transcripted_mcp
+
+/// Covers the MCP Apps (SEP-1865) recent-meetings widget: the data builder that
+/// reads the local capture library, the self-contained HTML renderer, and the
+/// `show_recent_meetings` tool result / `ui://` resource wire shape.
+final class RecentMeetingsWidgetTests: XCTestCase {
+    var index: TranscriptIndex!
+    var tempDir: URL!
+
+    override func setUp() {
+        super.setUp()
+        tempDir = makeTempDir()
+        index = try! TranscriptIndex(indexDir: tempDir)
+    }
+
+    override func tearDown() {
+        index = nil
+        removeTempDir(tempDir)
+        super.tearDown()
+    }
+
+    // MARK: - Fixtures
+
+    /// Write a `<stem>_audio/<track>.<ext>` file next to a fixture meeting,
+    /// mirroring the app's `audio/<stem>_audio/` layout.
+    @discardableResult
+    private func writeAudio(stem: String, track: String, ext: String, bytes: Int) throws -> URL {
+        let dir = tempDir
+            .appendingPathComponent("audio", isDirectory: true)
+            .appendingPathComponent("\(stem)_audio", isDirectory: true)
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        let url = dir.appendingPathComponent("\(track).\(ext)")
+        try Data(repeating: 0xAB, count: bytes).write(to: url)
+        return url
+    }
+
+    private func model(count: Int = 5, perMeetingCap: Int? = nil, totalCap: Int? = nil) throws -> RecentMeetingsWidgetModel {
+        try RecentMeetingsWidgetBuilder.build(
+            index: index,
+            meetingDirs: [tempDir],
+            count: count,
+            generatedDate: "2026-07-07",
+            serverName: "transcripted",
+            serverVersion: "test",
+            maxAudioBytesPerMeeting: perMeetingCap ?? RecentMeetingsWidgetBuilder.defaultMaxAudioBytesPerMeeting,
+            maxAudioBytesTotal: totalCap ?? RecentMeetingsWidgetBuilder.defaultMaxAudioBytesTotal
+        )
+    }
+
+    // MARK: - Builder
+
+    func testBuildEmbedsTranscriptAndAudioForRecentMeeting() throws {
+        try writeFixture(
+            makeFixtureJSON(title: "Roadmap Sync", date: "2026-03-26T16:04:11-0500"),
+            filename: "Call_2026-03-26_16-04-11", to: tempDir
+        )
+        try writeAudio(stem: "Call_2026-03-26_16-04-11", track: "playback", ext: "m4a", bytes: 2048)
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        let m = try model()
+        XCTAssertEqual(m.meetings.count, 1)
+        let meeting = m.meetings[0]
+        XCTAssertEqual(meeting.title, "Roadmap Sync")
+        XCTAssertFalse(meeting.transcript.isEmpty, "transcript should be embedded")
+        XCTAssertTrue(meeting.transcript.contains("roadmap") || meeting.transcript.contains("Good morning"),
+                      "transcript should carry dialogue text")
+
+        let audio = try XCTUnwrap(meeting.audio, "preferred audio track should be embedded")
+        XCTAssertEqual(audio.mimeType, "audio/mp4")
+        XCTAssertEqual(audio.label, "Mix", "playback stem maps to the Mix label")
+        XCTAssertTrue(audio.dataURI.hasPrefix("data:audio/mp4;base64,"))
+        XCTAssertNil(meeting.audioNote)
+    }
+
+    func testBuildPrefersMixOverMicWhenBothPresent() throws {
+        try writeFixture(makeFixtureJSON(date: "2026-03-26T16:04:11-0500"),
+                         filename: "Call_2026-03-26_16-04-11", to: tempDir)
+        try writeAudio(stem: "Call_2026-03-26_16-04-11", track: "microphone", ext: "m4a", bytes: 1024)
+        try writeAudio(stem: "Call_2026-03-26_16-04-11", track: "playback", ext: "m4a", bytes: 1024)
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        let audio = try XCTUnwrap(try model().meetings[0].audio)
+        XCTAssertEqual(audio.label, "Mix", "playback (Mix) is preferred over microphone")
+    }
+
+    func testBuildFallsBackToPathWhenAudioTooLarge() throws {
+        try writeFixture(makeFixtureJSON(date: "2026-03-26T16:04:11-0500"),
+                         filename: "Call_2026-03-26_16-04-11", to: tempDir)
+        try writeAudio(stem: "Call_2026-03-26_16-04-11", track: "playback", ext: "m4a", bytes: 5_000_000)
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        let meeting = try model(perMeetingCap: 1_000_000).meetings[0]
+        XCTAssertNil(meeting.audio, "oversized audio is not inlined")
+        XCTAssertNotNil(meeting.audioNote)
+        XCTAssertTrue(meeting.audioNote?.contains("too large") == true)
+        XCTAssertNotNil(meeting.audioDirectory, "path fallback is provided")
+    }
+
+    func testBuildTotalBudgetStopsInliningAcrossMeetings() throws {
+        for i in 0..<3 {
+            let stem = "Call_2026-03-2\(i)_10-00-00"
+            try writeFixture(makeFixtureJSON(date: "2026-03-2\(i)T10:00:00-0500"), filename: stem, to: tempDir)
+            try writeAudio(stem: stem, track: "playback", ext: "m4a", bytes: 700_000)
+        }
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        // Budget fits one 700KB track, not all three.
+        let embedded = try model(perMeetingCap: 1_000_000, totalCap: 1_000_000).meetings.filter { $0.audio != nil }
+        XCTAssertEqual(embedded.count, 1, "total budget caps inline audio across cards")
+    }
+
+    func testBuildHandlesMeetingWithNoAudio() throws {
+        try writeFixture(makeFixtureJSON(date: "2026-03-26T16:04:11-0500"),
+                         filename: "Call_2026-03-26_16-04-11", to: tempDir)
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        let meeting = try model().meetings[0]
+        XCTAssertNil(meeting.audio)
+        XCTAssertNil(meeting.audioDirectory, "no audio directory exists")
+        XCTAssertEqual(meeting.audioNote, "No recording found")
+        XCTAssertFalse(meeting.transcript.isEmpty)
+    }
+
+    // MARK: - HTML renderer
+
+    func testHTMLIsSelfContainedAndThemeAware() throws {
+        try writeFixture(makeFixtureJSON(title: "Roadmap Sync", date: "2026-03-26T16:04:11-0500"),
+                         filename: "Call_2026-03-26_16-04-11", to: tempDir)
+        try writeAudio(stem: "Call_2026-03-26_16-04-11", track: "playback", ext: "m4a", bytes: 2048)
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        let html = RecentMeetingsWidget.html(for: try model())
+
+        // Self-contained: no external network references of any kind.
+        XCTAssertFalse(html.contains("http://"), "no external http references")
+        XCTAssertFalse(html.contains("https://"), "no external https references")
+        XCTAssertFalse(html.contains("//cdn"), "no CDN references")
+        XCTAssertFalse(html.range(of: #"src\s*=\s*["']https?:"#, options: .regularExpression) != nil)
+
+        // Theme-aware in both directions.
+        XCTAssertTrue(html.contains("prefers-color-scheme: dark"))
+        XCTAssertTrue(html.contains(#"[data-theme="dark"]"#))
+        XCTAssertTrue(html.contains(#"[data-theme="light"]"#))
+
+        // Data is baked in and the audio data URI rides along.
+        XCTAssertTrue(html.contains(#"id="tx-data""#))
+        XCTAssertTrue(html.contains("data:audio/mp4;base64,"))
+        XCTAssertTrue(html.contains("Roadmap Sync"))
+    }
+
+    func testHTMLNeutralizesScriptClose() throws {
+        // A malicious/odd title must not be able to close the data <script> tag.
+        try writeFixture(makeFixtureJSON(title: "Evil </script><img> Meeting", date: "2026-03-26T16:04:11-0500"),
+                         filename: "Call_2026-03-26_16-04-11", to: tempDir)
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        let html = RecentMeetingsWidget.html(for: try model())
+        // The JSON payload escapes "</" so the data block cannot be broken out of.
+        XCTAssertFalse(html.contains("</script><img>"), "script-close sequence must be neutralized in the data block")
+        XCTAssertTrue(html.contains(#"<\/script>"#))
+    }
+
+    // MARK: - Resource + tool wire shape (MCP Apps / SEP-1865)
+
+    func testResourceDescriptorShape() {
+        let resource = TranscriptedUIResources.recentMeetingsResource
+        XCTAssertEqual(resource.uri, "ui://transcripted/recent-meetings.html")
+        XCTAssertEqual(resource.mimeType, "text/html;profile=mcp-app")
+        XCTAssertNotNil(resource._meta?["ui"], "resource carries MCP Apps ui metadata")
+    }
+
+    func testToolMetaLinksToUIResource() {
+        let meta = TranscriptedUIResources.toolMeta
+        // Official extension linkage.
+        if case .object(let ui)? = meta["ui"] {
+            XCTAssertEqual(ui["resourceUri"], .string("ui://transcripted/recent-meetings.html"))
+        } else {
+            XCTFail("tool _meta.ui.resourceUri missing")
+        }
+        // OpenAI Apps SDK alias for ChatGPT.
+        XCTAssertEqual(meta["openai/outputTemplate"], .string("ui://transcripted/recent-meetings.html"))
+    }
+
+    func testShowRecentMeetingsResultShape() throws {
+        try writeFixture(makeFixtureJSON(title: "Roadmap Sync", date: "2026-03-26T16:04:11-0500"),
+                         filename: "Call_2026-03-26_16-04-11", to: tempDir)
+        try writeAudio(stem: "Call_2026-03-26_16-04-11", track: "playback", ext: "m4a", bytes: 2048)
+        try index.reconcile(meetingsDir: tempDir, dictationsDir: tempDir)
+
+        let directories = TranscriptedDataDirectories(
+            meetingDirs: [tempDir], dictationDirs: [tempDir], indexDir: tempDir
+        )
+        let result = try TranscriptedUIResources.showRecentMeetingsResult(
+            count: 5, index: index, directories: directories, serverVersion: "test"
+        )
+
+        XCTAssertEqual(result.isError, false)
+
+        // Text fallback for non-rendering clients (e.g. the Claude Code CLI).
+        let text = result.content.compactMap { c -> String? in
+            if case .text(let t, _, _) = c { return t }
+            return nil
+        }.first
+        XCTAssertNotNil(text)
+        XCTAssertTrue(text?.contains("Roadmap Sync") == true)
+
+        // Inline embedded UI resource carries the widget HTML at the ui:// URI.
+        let embedded = result.content.compactMap { c -> Resource.Content? in
+            if case .resource(let r, _, _) = c { return r }
+            return nil
+        }.first
+        let res = try XCTUnwrap(embedded, "tool result should carry an embedded ui resource")
+        XCTAssertEqual(res.uri, "ui://transcripted/recent-meetings.html")
+        XCTAssertEqual(res.mimeType, "text/html;profile=mcp-app")
+        XCTAssertTrue(res.text?.contains("<!DOCTYPE html>") == true)
+        XCTAssertTrue(res.text?.contains("data:audio/mp4;base64,") == true)
+
+        // structuredContent so a spec host can push tool output into the template.
+        XCTAssertNotNil(result.structuredContent)
+
+        // Result _meta links back to the resource.
+        XCTAssertNotNil(result._meta?["ui"])
+    }
+
+    func testTextFallbackListsMeetings() throws {
+        let m = RecentMeetingsWidgetModel(
+            serverName: "transcripted", serverVersion: "test", generatedDate: "2026-07-07",
+            meetings: [
+                WidgetMeeting(title: "Roadmap Sync", date: "2026-03-26", datetime: "2026-03-26T16:04:11",
+                              durationSeconds: 1800, speakers: ["You", "Jenny"], wordCount: 1200,
+                              filename: "Call_2026-03-26_16-04-11", transcript: "hi",
+                              audio: WidgetAudio(dataURI: "data:audio/mp4;base64,AA==", mimeType: "audio/mp4", label: "Mix", sizeBytes: 2),
+                              audioDirectory: nil, audioNote: nil)
+            ]
+        )
+        let text = TranscriptedUIResources.textFallback(for: m)
+        XCTAssertTrue(text.contains("Roadmap Sync"))
+        XCTAssertTrue(text.contains("30:00"))
+        XCTAssertTrue(text.contains("▶ audio"))
+    }
+}
diff --git a/docs/mcp-ui-recent-meetings.md b/docs/mcp-ui-recent-meetings.md
new file mode 100644
index 00000000..ed98816a
--- /dev/null
+++ b/docs/mcp-ui-recent-meetings.md
@@ -0,0 +1,110 @@
+# MCP Apps: the recent-meetings widget
+
+Transcripted's MCP server now ships one **interactive UI surface**: a "recent
+meetings" widget that renders inline inside a rendering-capable agent client, as
+a card list you can play and read from — not just a wall of text.
+
+This is the first, minimal slice of the
+[MCP Apps design](plans/mcp-host-apps-design.md) (Interpretation 2). It reuses the
+existing read-only data surface; it adds a UI layer, not new data plumbing.
+
+## What it does
+
+Call the `show_recent_meetings` tool (optional `count`, default 5, max 15). It
+returns a self-contained HTML widget: one card per recent meeting with
+
+- title, date, duration, speakers, and word count,
+- a **▶ Play** control that plays the meeting audio inline, and
+- a **View raw transcript** toggle that expands the full transcript.
+
+Light and dark themes are both handled. In a client that does not render inline
+UI, the same tool returns a plain-text meeting list as a fallback.
+
+## Privacy: nothing leaves this Mac
+
+This is the reason MCP Apps is the right first move for Transcripted. The widget
+is **fully self-contained** — inline CSS/JS, no CDN, no external fonts, no
+network calls of any kind. Audio and transcripts are read from the local capture
+library and travel *with* the widget over the local stdio transport to the local
+client. There is no remote host in the loop. This matches the app's "your content
+never leaves this Mac" posture exactly; the local MCP server serves local bytes to
+the local agent.
+
+Concretely, the widget's sandbox runs under the MCP Apps default CSP
+(`default-src 'none'; media-src 'self' data:; connect-src 'none'; …`), so it
+*cannot* reach the network even if it wanted to. Audio plays from a
+`data:audio/mp4;base64,…` URI, which the default policy allows.
+
+## The wire shape (MCP Apps / SEP-1865)
+
+Built against the official **MCP Apps** extension (`io.modelcontextprotocol/ui`,
+spec `2026-01-26`), the standardized successor to the community `mcp-ui` project:
+
+- A `ui://transcripted/recent-meetings.html` resource, MIME
+  `text/html;profile=mcp-app`, is registered and served via `resources/read`.
+- The `show_recent_meetings` tool links to it via `_meta.ui.resourceUri`, and
+  also sets `_meta["openai/outputTemplate"]` (the OpenAI Apps SDK alias) so it
+  works in ChatGPT.
+- The tool result carries three things so it renders across host families:
+  1. a **text** summary (fallback for non-rendering clients),
+  2. the data-baked widget HTML as an **inline embedded resource** (the `mcp-ui`
+     `rawHtml` pattern), and
+  3. `structuredContent` (the meeting model), so a host that renders the template
+     and pushes tool output via `ui/notifications/tool-result` / `window.openai.toolOutput`
+     renders the same view.
+
+The widget prefers live host data when present and falls back to the baked-in
+data otherwise, so it renders identically standalone, from `resources/read`, or
+inline.
+
+## Renders today in… (be honest)
+
+MCP Apps shipped 2026-01-26 and host support is uneven. Grounded in the spec and
+client docs as of mid-2026:
+
+| Client | Renders this widget inline? |
+|---|---|
+| **ChatGPT** (OpenAI Apps SDK) | **Yes** — most mature inline-widget host. |
+| **VS Code** (Copilot MCP) | **Yes** (shipped at launch). |
+| **Cursor** (≥ 2.6) | **Yes** (known bug: strips `_meta` from tool-result; the baked-in data path still renders). |
+| **Goose** | **Yes**. |
+| **Claude Desktop / claude.ai** | **Announced yes, but verify** — a credible open report ([ext-apps#671](https://github.com/modelcontextprotocol/ext-apps/issues/671)) shows some builds negotiate the extension and fetch the resource but paint no iframe. Test on your build. |
+| **Claude Code (CLI)** | **No** — it's a terminal; it consumes the tool but shows the **text fallback**, not inline UI. |
+
+So: **renders inline today in ChatGPT, VS Code, Cursor, and Goose. Needs client
+support to render in Claude Desktop/web (announced, contested). Does not render
+inline in the Claude Code CLI** (by design — no iframe surface); there you get the
+text list.
+
+## How to try it
+
+In a rendering-capable client (ChatGPT via the Apps SDK, VS Code, Cursor ≥ 2.6,
+or Goose), connect the Transcripted MCP server, then ask the agent to
+"show my recent meetings" (or call `show_recent_meetings` directly). The widget
+draws inline; click **▶ Play** to hear a meeting and **View raw transcript** to
+read it.
+
+To sanity-check the widget itself without a client, drive the server over stdio
+and open the HTML it returns:
+
+```bash
+cd Tools/TranscriptedMCP && swift build
+# initialize → tools/call show_recent_meetings, then write the embedded
+# resource's `text` to recent-meetings.html and open it in any browser.
+```
+
+The card list, audio playback, and transcript toggle all work standalone — that
+is the proof the widget is correct even where a client hasn't shipped MCP Apps
+rendering yet.
+
+## Known limitations (minimal slice)
+
+- **Inline audio is size-capped** (per-meeting and per-widget budgets in
+  `RecentMeetingsWidgetBuilder`). Audio bytes ride inside the tool result, and
+  some hosts limit message size, so longer recordings fall back to showing their
+  local `audio/<stem>_audio/` path instead of an inline player. The natural next
+  step is lazy fetch: a play click calls a `get_meeting_audio` tool over the
+  postMessage bridge and streams the track on demand — scales past the inline
+  budget, but needs a host that forwards widget→server tool calls.
+- One widget (recent meetings). The transcript browser and person card sketched
+  in the design doc are follow-ups.