# MCP Apps Playground

A demo MCP server showcasing interactive UI capabilities using the [MCP Apps Extension (SEP-1865)](https://github.com/modelcontextprotocol/ext-apps).

## Features

- 🔧 **MCP Tools** - `hello_world`, `list_sort`, `flame_graph`, and `feature_flags` tools with Zod schema validation
- 📱 **Apps Extension** - HTML UI via `ui://` resources with `text/html;profile=mcp-app`
- 📦 **structuredContent** - Data passed to UI via `ui/notifications/tool-input`
- 💬 **Bidirectional** - UIs can send messages back to chat via `ui/message`
- 🚀 **Dual Transport** - stdio (default) and HTTP/SSE

## Tools

### `list_sort` — Interactive List Reordering

**Before:** Agent receives list data from an MCP tool → proposes a sorted order based on its analysis → user reads text output and requests adjustments → multiple back-and-forth messages to align with actual preferences.

**With MCP Apps:** Agent displays a drag-and-drop interface alongside its suggested order. User applies domain knowledge to reorder items visually, or clicks "Ask AI to Sort" for the agent's reasoning—true collaboration where both contribute.

> 🖱️ Drag-and-drop reordering · 🤖 "Ask AI to Sort" · ↩️ Reset · 💾 Save to chat

---

### `flame_graph` — Performance Profiler Visualization

**Before:** Agent receives CPU profile data from an MCP tool → analyzes the JSON and identifies bottlenecks → user sees only the agent's text summary → no way to validate hypotheses or apply domain-specific context.

**With MCP Apps:** Agent renders an interactive flame graph and can annotate suspected hot paths. User explores the visualization with their own domain knowledge—confirming or rejecting the agent's hypotheses, drilling into areas the agent might have overlooked.

> 🔍 Click-to-zoom hierarchy · 💬 Hover tooltips · 🧭 Breadcrumb nav · 📊 Send frame to chat

---

### `feature_flags` — Feature Flag Selector

**Before:** Agent fetches flag configuration from an MCP tool → summarizes which flags exist and their status → user cross-references with deployment context → asks agent to generate integration code separately.

**With MCP Apps:** Agent displays a searchable flag picker with live environment status. User selects flags based on their release priorities, switches between prod/staging/dev views, and generates SDK code—agent provides data, user drives decisions.

> 🌍 Environment tabs · 🔎 Search & filter · ☑️ Multi-select · 📝 Generate SDK code

## Quick Start

```bash
# Install dependencies
npm install

# Build
npm run build

# Run with stdio transport (for Claude Desktop, Cursor, VS Code)
npm run dev

# Or run with HTTP transport (for web-based clients)
npm run dev:http

# Test with MCP Inspector
npm run inspector        # stdio
npm run inspector:http   # HTTP (start server first)
```

## Project Structure

```
src/
├── index.ts           # Main server (stdio transport)
├── http-server.ts     # HTTP transport variant
└── ui/
    ├── hello-world.ts # Greeting UI template
    ├── list-sort.ts   # Interactive list sorting UI
    ├── flame-graph.ts # Performance flame graph visualization
    └── feature-flags.ts # Feature flag selector UI
```

## MCP Configuration

### VS Code

Use the included `.vscode/mcp.json`:

```json
{
  "servers": {
    "mcp-apps-playground": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"]
    }
  }
}
```

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "mcp-apps-playground": {
      "command": "node",
      "args": ["/path/to/mcp-apps-playground/dist/index.js"]
    }
  }
}
```

## How It Works

### 1. UI Resource Declaration

UI resources are declared with `ui://` scheme and `text/html;profile=mcp-app` MIME type:

```typescript
server.resource(
  "greeting-ui",
  "ui://mcp-apps-playground/greeting",
  {
    description: "Interactive greeting UI panel",
    mimeType: "text/html;profile=mcp-app",
  },
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: "text/html;profile=mcp-app",
      text: HELLO_WORLD_UI(),
    }],
  })
);
```

### 2. Tool with UI Annotation

Tools use `_meta.ui.resourceUri` to link to a UI resource. Data is passed via `structuredContent`:

```typescript
server.registerTool(
  "hello_world",
  {
    description: "Display a Hello World greeting",
    inputSchema: {
      name: z.string().describe("Name to greet"),
    },
    _meta: {
      ui: {
        resourceUri: "ui://mcp-apps-playground/greeting",
        visibility: ["model", "app"],
      },
    },
  },
  async ({ name }) => ({
    content: [{ type: "text", text: `Hello, ${name}!` }],
    structuredContent: { name, greeting: `Hello, ${name}!` },
  })
);
```

### 3. UI Communication

UIs communicate with the MCP host via postMessage JSON-RPC:

```javascript
// Initialize handshake (required)
const result = await sendRequest('ui/initialize', {
  protocolVersion: '2025-06-18',
  capabilities: {},
});
sendNotification('ui/notifications/initialized', {});

// Listen for tool data
window.addEventListener('message', (e) => {
  if (e.data.method === 'ui/notifications/tool-input') {
    const { arguments: args } = e.data.params;
    // Update UI with args
  }
});

// Send message to chat
await sendRequest('ui/message', {
  content: [{ type: 'text', text: 'User selected: ...' }]
});
```

## Resources

- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [MCP Apps Extension](https://github.com/modelcontextprotocol/ext-apps)
- [MCP Specification](https://spec.modelcontextprotocol.io)
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)

## License

MIT