fix(ui): templates called non-existent app.callTool; correct #386 doc claims

The generated form/progress/tree-view/kanban templates emitted
`app.callTool('tool', args)` (positional — no such SDK method) and
`app.sendMessage('<string>')`, both of which throw at runtime, so template
interactivity never worked. Verified against the @modelcontextprotocol/ext-apps
v1.7.4 App.d.ts: the API is `callServerTool({ name, arguments })` and
`sendMessage({ role, content })`; there is no `callTool`.

- lib/ui-templates.sh: 5 callServerTool sites (+.catch on the 3 fire-and-forget
  tree/kanban calls to avoid unhandled rejections); 6 sendMessage sites to the
  {role, content} object form. Generated JS validated with `node --check`.
- test/unit/ui_templates.bats: per-template assertions — interactive templates
  use `app.callServerTool({` and never `app.callTool(`; receive-only templates
  (data-table, diff-viewer) make no tool call; sendMessage uses the object form.
- Docs: this breakage was misattributed to "Claude Desktop bug #386". #386 was
  closed COMPLETED — the real cause was the same wrong call signature. Corrected
  README(.in), docs/concepts/mcp-apps.md, docs/guides/ui-resources.md, and
  docs/reference/ui-templates.md (Experimental→Beta for interactive templates,
  with an honest "API-correct, not yet host-verified" caveat). The separate
  progress-streaming claim is kept as host-dependent/unverified.

685 unit tests pass; test/lint.sh clean; README render up to date.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: yaniv-golan

CHANGELOG.md

@@ -24,6 +24,7 @@ MCP Apps (SEP-1865) sync with the current ext-apps draft spec.
 
 ### Fixed
 
+- **UI templates called a non-existent SDK method.** The generated `form`, `progress`, `tree-view`, and `kanban` templates emitted `app.callTool('tool', args)` (positional, no such method) and `app.sendMessage('<string>')`, which threw at runtime — so interactivity never worked. Fixed to the correct MCP Apps SDK API: `app.callServerTool({ name, arguments })` (with `.catch` on fire-and-forget calls) and `app.sendMessage({ role, content })`. This breakage had been misattributed to "Claude Desktop bug #386" in the docs; #386 was actually the same incorrect call signature (closed COMPLETED). Docs (`docs/concepts/mcp-apps.md`, `docs/guides/ui-resources.md`, `docs/reference/ui-templates.md`, `README`) corrected accordingly; receive-only templates (`data-table`, `diff-viewer`) were unaffected.
 - **`SPEC-COMPLIANCE.md`** now reports MCP Apps support as introduced in v1.1.0 (was incorrectly labeled 0.8.0).
 
 ### Changed

README.md

@@ -82,7 +82,7 @@ mcp-bash targets the **2025-11-25** MCP specification with negotiated downgrades
 | Utilities | ✅ Full | Progress, cancellation, logging, completion |
 | Elicitation | ✅ Full | Form, URL, enum, multi-choice modes |
 | Roots | ✅ Full | Server→client request, listChanged |
-| MCP Apps (UI) | ⚠️ Partial | `ui://` resources, templates; interactivity blocked by [host bug](https://github.com/modelcontextprotocol/ext-apps/issues/386) |
+| MCP Apps (UI) | ✅ Full | `ui://` resources, templates, capability negotiation; renders natively in Claude, VS Code, Goose, and ChatGPT |
 
 **Not yet implemented:** Audio content, sampling. Tasks (async job/poll) and server-identity discovery are HTTP-oriented and not applicable to stdio.
 

README.md.in

@@ -82,7 +82,7 @@ mcp-bash targets the **2025-11-25** MCP specification with negotiated downgrades
 | Utilities | ✅ Full | Progress, cancellation, logging, completion |
 | Elicitation | ✅ Full | Form, URL, enum, multi-choice modes |
 | Roots | ✅ Full | Server→client request, listChanged |
-| MCP Apps (UI) | ⚠️ Partial | `ui://` resources, templates; interactivity blocked by [host bug](https://github.com/modelcontextprotocol/ext-apps/issues/386) |
+| MCP Apps (UI) | ✅ Full | `ui://` resources, templates, capability negotiation; renders natively in Claude, VS Code, Goose, and ChatGPT |
 
 **Not yet implemented:** Audio content, sampling. Tasks (async job/poll) and server-identity discovery are HTTP-oriented and not applicable to stdio.
 

docs/concepts/mcp-apps.md

@@ -315,18 +315,17 @@ Need an external-URL or Remote DOM UI for a specific host? Open an issue describ
 
 The draft notes that app-delegated long-running tool calls **may** use core MCP Tasks (`tasks/*`) so a poll can survive iframe teardown. mcp-bash does **not** implement core MCP Tasks — tools return synchronous results only. App-delegated long-running work is a separate (non-UI) roadmap item; there is currently no UI-specific Tasks behavior to configure.
 
-## Known Limitations
-
-Current Claude Desktop limitations (as of Jan 2026):
+## Capabilities & caveats
 
 | Feature | Status | Notes |
 |---------|--------|-------|
-| Tool result display | ✅ Works | `ontoolresult` receives final result |
-| Real-time progress | ❌ Blocked | `notifications/progress` not forwarded to UIs |
-| UI-initiated tool calls | ❌ Blocked | `callServerTool()` rejected ([bug #386](https://github.com/modelcontextprotocol/ext-apps/issues/386)) |
-| UI resource polling | ❌ Blocked | `resources/read` rejected (same bug) |
+| Tool result display | ✅ Works | `ontoolresult` receives the final result |
+| UI-initiated tool calls | ✅ Works | `app.callServerTool({ name, arguments })` — use the **object** form |
+| UI resource reads | ✅ Works | `app.readResource(...)` |
+| Real-time progress streaming | ⚠️ Host-dependent / unverified | UIs get `ontoolinput` (start) + `ontoolresult` (end); mid-call `notifications/progress` forwarding varies by host |
+| Interactivity verified in a host | ⚠️ Not yet | mcp-bash emits correct SDK calls; not yet confirmed end-to-end in Claude/ChatGPT |
 
-UIs are currently **receive-only** - they can display tool results but cannot initiate requests.
+> **History:** UI-initiated calls were previously documented as "blocked by Claude Desktop bug #386." That was a **misattribution** — [#386](https://github.com/modelcontextprotocol/ext-apps/issues/386) was an incorrect `callServerTool` call signature (positional instead of `{ name, arguments }`), closed *COMPLETED*. mcp-bash's own templates had the same bug (calling a non-existent `app.callTool`), now fixed.
 
 ## References
 

docs/guides/ui-resources.md

@@ -534,17 +534,13 @@ See `test/unit/ui_*.bats` for examples.
 3. Ensure `app.ontoolresult` handler is set BEFORE calling `app.connect()`
 4. Delete `.registry/tools.json` cache to regenerate tool definitions
 
-## Known Limitations
+## Notes & caveats
 
-Due to current Claude Desktop implementation limitations:
+- **UI-initiated requests work.** A UI can call server tools and read resources via the MCP Apps SDK: `app.callServerTool({ name, arguments })` and `app.readResource(...)`. (An earlier version of this guide claimed these were "blocked by a Claude Desktop bug" #386 — that was a **misattribution**; #386 was an incorrect `callServerTool` call signature, now closed *COMPLETED*. Use the object form `{ name, arguments }`, not positional arguments.)
 
-- **Real-time progress updates**: UIs cannot receive `notifications/progress` during tool execution. The UI only receives `ontoolinput` when the tool starts and `ontoolresult` when it completes.
+- **Real-time progress streaming is host-dependent and unverified here.** UIs reliably receive `ontoolinput` (start) and `ontoolresult` (end); whether `notifications/progress` is forwarded to the UI mid-call depends on the host. If you need progress, show an indeterminate spinner until `ontoolresult`.
 
-- **UI-initiated requests**: The MCP Apps SDK methods `callServerTool()` and `resources/read` are blocked by a [Claude Desktop bug](https://github.com/modelcontextprotocol/ext-apps/issues/386). UIs cannot poll for data or call other tools.
-
-**Workarounds**:
-- Use indeterminate progress (spinner) while waiting for results
-- For multi-step operations, break into separate tool calls
+- **End-to-end host verification:** mcp-bash emits the correct MCP Apps SDK calls, but interactivity has not been verified inside a host (Claude/ChatGPT) from this repo — treat interactive flows as beta.
 
 ## Examples
 

docs/reference/ui-templates.md

@@ -8,24 +8,22 @@ mcp-bash provides built-in templates for common UI patterns. Templates generate
 
 | Template | Status | Description |
 |----------|--------|-------------|
-| `data-table` | ✅ Ready | Tabular data display |
-| `form` | ⚠️ Experimental | Input forms - submit blocked by [#386](https://github.com/modelcontextprotocol/ext-apps/issues/386) |
-| `progress` | ⚠️ Experimental | Progress indicators - updates not forwarded to UIs |
-| `diff-viewer` | ⚠️ Experimental | Side-by-side diff comparison |
-| `tree-view` | ⚠️ Experimental | Hierarchical tree structures - selection blocked by [#386](https://github.com/modelcontextprotocol/ext-apps/issues/386) |
-| `kanban` | ⚠️ Experimental | Kanban board - drag-drop blocked by [#386](https://github.com/modelcontextprotocol/ext-apps/issues/386) |
+| `data-table` | ✅ Ready | Tabular data display (receive-only) |
+| `diff-viewer` | ✅ Ready | Side-by-side diff comparison (receive-only) |
+| `form` | 🧪 Beta | Input forms that submit to a server tool |
+| `progress` | 🧪 Beta | Progress indicators with a cancel action |
+| `tree-view` | 🧪 Beta | Hierarchical tree; selection calls a server tool |
+| `kanban` | 🧪 Beta | Kanban board; card-click / drag-drop call a server tool |
 
-### Why are templates experimental?
+### Interactivity status
 
-Claude Desktop currently has limitations that prevent full interactivity:
+Interactive templates (`form`, `progress`, `tree-view`, `kanban`) call server tools through the MCP Apps SDK.
 
-1. **`callServerTool()` blocked** ([issue #386](https://github.com/modelcontextprotocol/ext-apps/issues/386)): UIs cannot call server tools, so form submission, tree selection, and kanban drag-drop don't work.
+Earlier versions emitted a **non-existent** `app.callTool(...)` method (and `app.sendMessage('<string>')`), which threw at runtime. That breakage was **misattributed** to a Claude Desktop host bug ([#386](https://github.com/modelcontextprotocol/ext-apps/issues/386) — now closed *COMPLETED*; the actual root cause was an incorrect SDK call signature). The templates now use the correct API: `app.callServerTool({ name, arguments })` and `app.sendMessage({ role, content })`.
 
-2. **Progress notifications not forwarded**: UIs only receive `ontoolinput` (start) and `ontoolresult` (end) - no real-time progress updates.
+**Why "Beta", not "Ready":** the generated code is now API-correct (verified with `node --check` and unit tests), but interactivity has **not** been verified end-to-end inside a host (Claude/ChatGPT). Receive-only templates (`data-table`, `diff-viewer`) need no tool calls and are Ready.
 
-**What works today**: Display-only UIs that render tool results (like `data-table`).
-
-**What doesn't work**: Any UI that needs to send data back to the server.
+**Separately (still unverified): real-time progress.** UIs receive `ontoolinput` (start) and `ontoolresult` (end); whether `notifications/progress` is forwarded to UIs mid-call is host-dependent and not confirmed here.
 
 ## Using Templates
 
@@ -47,7 +45,7 @@ When `template` is specified and no `index.html` exists, the template generates
 
 ## Form Template
 
-> ⚠️ **Experimental**: Form submission requires `callServerTool()` which is currently blocked by [Claude Desktop bug #386](https://github.com/modelcontextprotocol/ext-apps/issues/386). Forms will render but Submit won't work.
+> 🧪 **Beta**: Form submit calls the server tool via `app.callServerTool({ name, arguments })`. The generated code is API-correct (unit-tested), but interactivity is not yet verified end-to-end in a host.
 
 Interactive forms that submit to server tools.
 
@@ -186,7 +184,7 @@ The table expects tool results in this format:
 
 ## Progress Template
 
-> ⚠️ **Experimental**: Real-time progress updates require `notifications/progress` which Claude Desktop does not forward to UIs. This template can only show indeterminate loading states.
+> 🧪 **Beta**: The cancel action calls a server tool via `app.callServerTool(...)` (API-correct). Real-time progress *streaming* depends on whether the host forwards `notifications/progress` to UIs mid-call, which is host-dependent and unverified here; the UI reliably receives the final `ontoolresult`.
 
 Shows operation progress with optional cancellation.
 
@@ -234,7 +232,7 @@ Shows operation progress with optional cancellation.
 
 ## Diff Viewer Template
 
-> ⚠️ **Experimental**: Display works but any interactive features (navigation, actions) are blocked by [#386](https://github.com/modelcontextprotocol/ext-apps/issues/386).
+> ✅ **Ready**: The diff viewer is receive-only (renders a diff from the tool result); it makes no server tool calls.
 
 Two-panel diff view with syntax highlighting.
 
@@ -290,7 +288,7 @@ Alternative format:
 
 ## Tree View Template
 
-> ⚠️ **Experimental**: Display and expand/collapse work (client-side), but `onSelectTool` is blocked by [#386](https://github.com/modelcontextprotocol/ext-apps/issues/386).
+> 🧪 **Beta**: Display and expand/collapse are client-side; node selection calls `onSelectTool` via `app.callServerTool(...)` (API-correct), not yet host-verified end-to-end.
 
 Hierarchical tree structure with expand/collapse.
 
@@ -355,7 +353,7 @@ Hierarchical tree structure with expand/collapse.
 
 ## Kanban Template
 
-> ⚠️ **Experimental**: Display works but `onMoveTool` and `onCardClickTool` are blocked by [#386](https://github.com/modelcontextprotocol/ext-apps/issues/386). Drag-drop will animate but changes won't persist.
+> 🧪 **Beta**: Card-click and drag-drop call `onCardClickTool` / `onMoveTool` via `app.callServerTool(...)` (API-correct). Persistence depends on your tool applying the move server-side; not yet host-verified end-to-end.
 
 Column-based kanban board with drag-drop support.
 

lib/ui-templates.sh

@@ -390,9 +390,9 @@ mcp_ui_template_form() {
       const finalArgs = { ...submitArgs, ...data };
 
       try {
-        const result = await app.callTool('${submit_tool}', finalArgs);
+        const result = await app.callServerTool({ name: '${submit_tool}', arguments: finalArgs });
         showMessage('Form submitted successfully');
-        app.sendMessage('Form submitted: ' + JSON.stringify(data));
+        app.sendMessage({ role: 'user', content: { type: 'text', text: 'Form submitted: ' + JSON.stringify(data) } });
       } catch (err) {
         showMessage('Error: ' + (err.message || 'Unknown error'), true);
       } finally {
@@ -403,7 +403,7 @@ mcp_ui_template_form() {
 
     if (cancelBtn) {
       cancelBtn.addEventListener('click', () => {
-        app.sendMessage('Form cancelled');
+        app.sendMessage({ role: 'user', content: { type: 'text', text: 'Form cancelled' } });
       });
     }
   </script>
@@ -596,8 +596,8 @@ mcp_ui_template_progress() {
         const confirmMsg = '${cancel_confirm}';
         if (confirm(confirmMsg)) {
           try {
-            await app.callTool('${cancel_tool}', {});
-            app.sendMessage('Operation cancelled');
+            await app.callServerTool({ name: '${cancel_tool}', arguments: {} });
+            app.sendMessage({ role: 'user', content: { type: 'text', text: 'Operation cancelled' } });
           } catch (err) {
             console.error('Cancel failed:', err);
           }
@@ -1173,9 +1173,9 @@ TREE_STYLES
 
             const nodeId = content.dataset.nodeId;
             if (onSelectTool) {
-              app.callTool(onSelectTool, { nodeId });
+              app.callServerTool({ name: onSelectTool, arguments: { nodeId } }).catch(e => console.error(e));
             }
-            app.sendMessage('Selected: ' + nodeId);
+            app.sendMessage({ role: 'user', content: { type: 'text', text: 'Selected: ' + nodeId } });
           }
         });
       });
@@ -1447,9 +1447,9 @@ KANBAN_STYLES
         card.addEventListener('click', () => {
           const cardId = card.dataset.cardId;
           if (onCardClickTool) {
-            app.callTool(onCardClickTool, { cardId });
+            app.callServerTool({ name: onCardClickTool, arguments: { cardId } }).catch(e => console.error(e));
           }
-          app.sendMessage('Card clicked: ' + cardId);
+          app.sendMessage({ role: 'user', content: { type: 'text', text: 'Card clicked: ' + cardId } });
         });
 
         // Drag events
@@ -1499,9 +1499,9 @@ KANBAN_STYLES
 
                 // Notify server
                 if (onMoveTool) {
-                  app.callTool(onMoveTool, { cardId, fromColumn: oldColumn, toColumn: newColumn });
+                  app.callServerTool({ name: onMoveTool, arguments: { cardId, fromColumn: oldColumn, toColumn: newColumn } }).catch(e => console.error(e));
                 }
-                app.sendMessage('Moved card ' + cardId + ' to ' + newColumn);
+                app.sendMessage({ role: 'user', content: { type: 'text', text: 'Moved card ' + cardId + ' to ' + newColumn } });
 
                 // Re-render
                 renderBoard(cardsData);

test/unit/ui_templates.bats

@@ -205,3 +205,44 @@ setup() {
 	[[ "${output}" == *'draggable = true'* ]]
 	[[ "${output}" == *'move-card'* ]]
 }
+
+# --- MCP Apps SDK correctness (ext-apps): the SDK exposes callServerTool({name,
+# arguments}); there is no callTool. sendMessage takes {role, content}. These
+# guard against the regression where templates emitted app.callTool(...) /
+# app.sendMessage('string') (which threw at runtime). ---
+
+@test "sdk: interactive templates use app.callServerTool (not app.callTool)" {
+	local form='{"title":"T","fields":[{"name":"x","type":"text"}],"submitTool":"do-it"}'
+	local progress='{"title":"P","cancelTool":"abort"}'
+	local tree='{"title":"Files","onSelectTool":"sel"}'
+	local kanban='{"title":"Board","columns":[{"id":"a","title":"A"}],"onMoveTool":"mv","onCardClickTool":"clk"}'
+
+	run mcp_ui_template_form "${form}"
+	assert_output --partial 'app.callServerTool({'
+	refute_output --partial 'app.callTool('
+
+	run mcp_ui_template_progress "${progress}"
+	assert_output --partial 'app.callServerTool({'
+	refute_output --partial 'app.callTool('
+
+	run mcp_ui_template_tree_view "${tree}"
+	assert_output --partial 'app.callServerTool({'
+	refute_output --partial 'app.callTool('
+
+	run mcp_ui_template_kanban "${kanban}"
+	assert_output --partial 'app.callServerTool({'
+	refute_output --partial 'app.callTool('
+}
+
+@test "sdk: receive-only templates contain no app.callTool" {
+	run mcp_ui_template_data_table '{"title":"R","columns":[{"key":"k","label":"K"}]}'
+	refute_output --partial 'app.callTool('
+	run mcp_ui_template_diff_viewer '{"title":"D","viewMode":"split"}'
+	refute_output --partial 'app.callTool('
+}
+
+@test "sdk: sendMessage uses object form {role, content} not a string" {
+	run mcp_ui_template_form '{"title":"T","fields":[{"name":"x","type":"text"}],"submitTool":"t"}'
+	assert_output --partial 'app.sendMessage({ role:'
+	refute_output --partial "app.sendMessage('"
+}