diff --git a/documentation/docs/getting-started/using-extensions.md b/documentation/docs/getting-started/using-extensions.md index 757baeb61cd1..a04e5b882f25 100644 --- a/documentation/docs/getting-started/using-extensions.md +++ b/documentation/docs/getting-started/using-extensions.md @@ -668,4 +668,8 @@ goose session --with-streamable-http-extension "https://example.com/streamable" goose extensions are implemented with MCP, a standard protocol that allows AI models and agents to securely connect with local or remote resources. Learn how to build your own [extension as an MCP server](https://modelcontextprotocol.io/quickstart/server). +**Tutorials:** +- [Building Custom Extensions](/docs/tutorials/custom-extensions) - Create a Python-based MCP extension +- [Building MCP Apps](/docs/tutorials/building-mcp-apps) - Create interactive UI apps + [extensions-directory]: /extensions diff --git a/documentation/docs/guides/interactive-chat/_category_.json b/documentation/docs/guides/interactive-chat/_category_.json index 77f153aa42e0..5ee84698773c 100644 --- a/documentation/docs/guides/interactive-chat/_category_.json +++ b/documentation/docs/guides/interactive-chat/_category_.json @@ -1,5 +1,5 @@ { - "label": "Rich Interactive Chat", + "label": "MCP Apps and MCP-UI", "position": 55, "link": { "type": "doc", diff --git a/documentation/docs/guides/interactive-chat/index.mdx b/documentation/docs/guides/interactive-chat/index.mdx index 522df73ad22d..911003b36e2a 100644 --- a/documentation/docs/guides/interactive-chat/index.mdx +++ b/documentation/docs/guides/interactive-chat/index.mdx @@ -1,14 +1,14 @@ --- -title: Rich Interactive Chat +title: Rich Interactive Chat with MCP Apps and MCP-UI hide_title: true -description: Transform text-based responses into graphical components and interactive elements +description: Build interactive UI applications that render inside goose Desktop using MCP Apps and MCP-UI --- import Card from '@site/src/components/Card'; import styles from '@site/src/components/Card/styles.module.css'; import VideoCarousel from '@site/src/components/VideoCarousel'; -

Rich Interactive Chat with MCP-UI

+

Rich Interactive Chat with MCP Apps and MCP-UI

goose Desktop supports extensions that transform text-only responses into graphical, interactive experiences. Instead of reading through lists and descriptions, you can click, explore, and interact with UI components directly in your conversations.

@@ -27,6 +27,11 @@ import VideoCarousel from '@site/src/components/VideoCarousel';

๐Ÿ“š Documentation & Guides

+

๐Ÿ“ Featured Blog Posts

+ -
\ No newline at end of file +
diff --git a/documentation/docs/guides/interactive-chat/mcp-ui.md b/documentation/docs/guides/interactive-chat/mcp-ui.md index 8086b1f84a3f..65db00bf3878 100644 --- a/documentation/docs/guides/interactive-chat/mcp-ui.md +++ b/documentation/docs/guides/interactive-chat/mcp-ui.md @@ -1,8 +1,8 @@ --- sidebar_position: 1 -title: MCP-UI Extensions -sidebar_label: MCP-UI Extensions -description: Learn how goose can render graphical and interactive UI components from MCP-UI-enabled extensions +title: Using MCP Apps and MCP-UI +sidebar_label: Using MCP Apps and MCP-UI +description: Learn how goose renders interactive UI components from MCP Apps and MCP-UI extensions --- import Tabs from '@theme/Tabs'; @@ -11,7 +11,13 @@ import GooseDesktopInstaller from '@site/src/components/GooseDesktopInstaller'; import CLIExtensionInstructions from '@site/src/components/CLIExtensionInstructions'; import { PanelLeft } from 'lucide-react'; -Extensions built on MCP-UI allow goose Desktop to provide interactive and engaging user experiences. Imagine using a graphical, clickable UI instead of reading text responses and typing all your prompts: +# Using MCP Apps and MCP-UI + +Extensions built with MCP Apps or MCP-UI allow goose Desktop to provide interactive and engaging user experiences. Imagine using a graphical, clickable UI instead of reading text responses and typing all your prompts. These extensions return content that goose can render as embedded UI elements for rich, dynamic, and streamlined interactions. + +:::info MCP Apps is the official specification +[MCP Apps](/docs/tutorials/building-mcp-apps) is now the official MCP specification for interactive UIs. MCP-UI extensions still work in goose, but MCP Apps is the recommended path for new extensions. +:::
-
-MCP-UI-enabled extensions return content that goose can render as embedded UI elements for rich, dynamic, and streamlined interactions. - ## Try It Out -See how interactive responses work in goose. - -### Add Enabled Extension - -For this exercise, we'll add an MCP-UI-enabled extension that connects to [MCP-UI Demos](https://mcp-aharvard.netlify.app/) provided by Andrew Harvard. +See how interactive responses work in goose. For this exercise, we'll add an extension that connects to [MCP-UI Demos](https://mcp-aharvard.netlify.app/) provided by Andrew Harvard. @@ -52,7 +51,7 @@ For this exercise, we'll add an MCP-UI-enabled extension that connects to [MCP-U -### Interact in Chat - In goose Desktop, ask: - `Help me select seats for my flight` @@ -71,15 +68,14 @@ Instead of just text, you'll see an interactive response with: - Real-time, clickable selection capabilities - A booking confirmation with flight details -Ask questions to try out other demos: +Try out other demos: - `Plan my next trip based on my mood` - `What's the weather in Philadelphia?` -Stay tuned as more extensions build with MCP-UI! - ## For Extension Developers -Want to add interactivity to your own extensions? MCP-UI extends the Model Context Protocol to allow MCP servers to return content that agents can render as UI components instead of text-only responses. Learn more: -- [MCP-UI: Bringing the Browser into the Agent](/blog/2025/08/11/mcp-ui-post-browser-world) -- [MCP-UI Documentation](https://mcpui.dev/guide/introduction) +Add interactivity to your own extensions: + +- [Building MCP Apps](/docs/tutorials/building-mcp-apps) - Step-by-step tutorial (recommended) +- [MCP-UI Documentation](https://mcpui.dev/guide/introduction) - MCP-UI specification diff --git a/documentation/docs/tutorials/building-mcp-apps.md b/documentation/docs/tutorials/building-mcp-apps.md new file mode 100644 index 000000000000..0afb17a8c183 --- /dev/null +++ b/documentation/docs/tutorials/building-mcp-apps.md @@ -0,0 +1,530 @@ +--- +title: Building MCP Apps +description: Create interactive UI applications that render inside goose Desktop +--- + +import { PanelLeft } from 'lucide-react'; + +# Building MCP Apps for goose + +MCP Apps let MCP servers return interactive UIs that render directly inside the goose chat interface, rather than responding with text alone. This allows users to express intent through interaction, which is useful for workflows that require input, iteration, or visual feedback. + +:::warning Experimental +MCP Apps support in goose is experimental and based on a draft specification. The implementation is minimal and may change, and does not yet support advanced capabilities or persistent app windows. +::: + +In this tutorial, you will build an MCP App using JavaScript and Node.js. The app includes an interactive counter, stays in sync with the host theme, and sends messages back to the chat, showing how user intent flows from UI to agent. + +:::info Prerequisites +- Node.js 18+ installed +- goose Desktop application +::: + +--- + +## Step 1: Initialize Your Project + +Create a new directory and initialize a Node.js project: + +```bash +mkdir mcp-app-demo +cd mcp-app-demo +npm init -y +``` + +Install the MCP SDK: + +```bash +npm install @modelcontextprotocol/sdk +``` + +Update your `package.json` to use ES modules by adding `"type": "module"`: + +```json5 +{ + "name": "mcp-app-demo", + "version": "1.0.0", + // highlight-next-line + "type": "module", + "main": "server.js", + "scripts": { + "start": "node server.js" + }, + "dependencies": { + "@modelcontextprotocol/sdk": "^1.0.0" + } +} +``` + +--- + +## Step 2: Create the MCP Server + +Create `server.js` - this is the MCP server that loads and serves your HTML: + +```javascript +#!/usr/bin/env node + +import { readFileSync } from "fs"; +import { fileURLToPath } from "url"; +import { dirname, join } from "path"; +import { Server } from "@modelcontextprotocol/sdk/server/index.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { + CallToolRequestSchema, + ListToolsRequestSchema, + ListResourcesRequestSchema, + ReadResourceRequestSchema, +} from "@modelcontextprotocol/sdk/types.js"; + +// Load HTML from file +const __dirname = dirname(fileURLToPath(import.meta.url)); +const APP_HTML = readFileSync(join(__dirname, "index.html"), "utf-8"); + +// Create the MCP server +const server = new Server( + { + name: "mcp-app-demo", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + resources: {}, + }, + } +); + +// List available tools +server.setRequestHandler(ListToolsRequestSchema, async () => { + return { + tools: [ + { + name: "show_demo_app", + description: "Shows an interactive demo MCP App UI in the chat", + inputSchema: { + type: "object", + properties: {}, + required: [], + }, + }, + ], + }; +}); + +// Handle tool calls +server.setRequestHandler(CallToolRequestSchema, async (request) => { + const { name } = request.params; + + if (name === "show_demo_app") { + return { + content: [ + { + type: "text", + text: "The demo app is now displayed!", + }, + ], + // This metadata tells goose to render the MCP App + _meta: { + "ui/resourceUri": "ui://mcp-app-demo/main", + }, + }; + } + + throw new Error(`Unknown tool: ${name}`); +}); + +// List available resources +server.setRequestHandler(ListResourcesRequestSchema, async () => { + return { + resources: [ + { + uri: "ui://mcp-app-demo/main", + name: "MCP App Demo", + description: "An interactive demo", + mimeType: "text/html;profile=mcp-app", + }, + ], + }; +}); + +// Read resource content - returns the HTML +server.setRequestHandler(ReadResourceRequestSchema, async (request) => { + const { uri } = request.params; + + if (uri === "ui://mcp-app-demo/main") { + return { + contents: [ + { + uri: "ui://mcp-app-demo/main", + mimeType: "text/html;profile=mcp-app", + text: APP_HTML, + _meta: { + ui: { + csp: { + connectDomains: [], + resourceDomains: [], + }, + prefersBorder: true, + }, + }, + }, + ], + }; + } + + throw new Error(`Resource not found: ${uri}`); +}); + +// Start the server +async function main() { + const transport = new StdioServerTransport(); + await server.connect(transport); + console.error("MCP App Demo server running on stdio"); +} + +main().catch(console.error); +``` + +--- + +## Step 3: Create the App HTML + +Create `index.html` - this is your interactive UI: + +
+index.html + +```html + + + + + + MCP App Demo + + + +
+

๐ŸŽฎ MCP App Demo

+

An interactive UI running inside goose

+ +
+
0
+
Counter Value
+
+ + + +
+
+ +
+

๐Ÿ’ฌ Send a message to goose

+
+ + +
+
+
+ +
+ How this works:

+ This UI is served as an MCP resource with the ui:// scheme. + It communicates with goose via JSON-RPC messages through the sandbox bridge. +

+ โ€ข Counter uses local state
+ โ€ข "Send" calls ui/message to append text to chat
+ โ€ข Theme syncs with goose's theme setting +
+
+ + + + +``` + +
+ +--- + +## Step 4: Add to goose Desktop + +1. Click the button in the top-left to open the sidebar +2. Click `Extensions` +3. Click `Add custom extension` +4. Fill in the details: + - **Type**: `Standard IO` + - **ID**: `mcp-app-demo` + - **Name**: `MCP App Demo` + - **Command**: `node /full/path/to/mcp-app-demo/server.js` +5. Click `Add` + +For more options, see [Adding Extensions](/docs/getting-started/using-extensions#adding-extensions). + +--- + +## Step 5: Test Your App + +1. Restart goose to load the new extension +2. Prompt goose: "Show me the demo app" +3. goose will call the `show_demo_app` tool +4. Your interactive app will render in the chat! + +Try: +- Clicking the counter buttons +- Typing a message and clicking "Send" +- Switching goose between light/dark mode + +--- + +## How It Works + +``` +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Your MCP App โ”‚ HTML/JS in sandboxed iframe +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ postMessage +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ goose Desktop โ”‚ Renders UI, routes messages +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ + โ”‚ MCP Protocol +โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” +โ”‚ Your MCP Server โ”‚ Serves HTML via resources +โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ +``` + +Your server returns a `ui://` resource URI, goose fetches the HTML and renders it in an iframe. The app communicates back via `postMessage`โ€”requesting theme info, sending messages to chat, or resizing itself. + +MCP Apps run sandboxed with CSP restrictions. See the [MCP Apps Specification](https://github.com/modelcontextprotocol/ext-apps) for details on security and the full protocol. + + diff --git a/documentation/docs/tutorials/custom-extensions.md b/documentation/docs/tutorials/custom-extensions.md index a117a6840b31..4c4ea7637f7d 100644 --- a/documentation/docs/tutorials/custom-extensions.md +++ b/documentation/docs/tutorials/custom-extensions.md @@ -308,25 +308,22 @@ goose supports advanced MCP features that can enhance your extensions. **Learn More:** See the [MCP Specification](https://modelcontextprotocol.io/specification/draft/client/sampling) for technical details. -### MCP-UI: Interactive Extensions +### MCP Apps: Interactive Extensions -**[MCP-UI Extensions](/docs/guides/interactive-chat/mcp-ui)** enable rich, interactive user interfaces instead of text-only responses, transforming static MCP servers into dynamic, engaging experiences. +**[MCP Apps](/docs/tutorials/building-mcp-apps)** enable rich, interactive user interfaces instead of text-only responses. **Key Benefits:** -- Your MCP server can return interactive UI components alongside or instead of text -- Components render securely in isolated environments within goose Desktop -- Real-time user interactions trigger callbacks to your MCP server -- Standardized protocol ensures consistent behavior across different clients +- Return interactive UI components from your MCP server tools +- Components render securely in isolated sandboxes within goose Desktop +- Real-time user interactions trigger callbacks to your server -**Getting Started:** -- Use MCP-UI SDKs in multiple programming languages to create `UIResource` objects in your MCP server -- Return UI components from tools or resources using the standardized specification -- goose Desktop automatically renders MCP-UI components when detected -- Components support multiple rendering approaches for flexible styling +**Use Cases:** Interactive forms, data visualizations, booking interfaces, configuration wizards -**Use Cases:** Interactive forms, seat selection maps, data visualization dashboards, booking interfaces, configuration wizards +**Learn More:** [Building MCP Apps Tutorial](/docs/tutorials/building-mcp-apps) -**Learn More:** See the [MCP-UI Specification](https://mcpui.dev/guide/introduction) for technical details and implementation examples. +:::note +goose also supports [MCP-UI](/docs/guides/interactive-chat/mcp-ui), but MCP Apps is the recommended path for new extensions. +::: [mcp-docs]: https://modelcontextprotocol.io/ [mcp-python]: https://github.com/modelcontextprotocol/python-sdk