# MCP App Test Value Picker Server

A debug tool for **platform developers** building MCP Apps hosts. Use this MCP server to verify that your platform correctly implements the `ui/update-model-context` and `ui/message` protocols defined in the [MCP Apps Specification](https://github.com/modelcontextprotocol/ext-apps/tree/main/specification).

## Why Use This?

When building an MCP Apps host, you need to verify that:

1. **Context injection works** — Values selected in the UI iframe reach the AI model via `ui/update-model-context`
2. **Message sending works** — The UI can trigger follow-up messages via `ui/message`
3. **The complete flow works** — View → Host → Model communication is functioning end-to-end

This tool provides a simple "blind selection" test: the user picks a value in the UI, and the AI must correctly identify what was selected. If the AI knows the value, your platform is working. If not, something is broken in your `ui/update-model-context` implementation.

---

## Installation

### Via npm (Recommended)

Install from [npmjs.com/package/mcp-server-value-picker](https://www.npmjs.com/package/mcp-server-value-picker):

```bash
npm install -g mcp-server-value-picker
```

Run the server:

```bash
# Auto-detects transport mode
mcp-server-value-picker

# Force STDIO mode (for Claude Desktop)
mcp-server-value-picker --stdio

# Force HTTP mode
mcp-server-value-picker --http
```

Or run directly with npx (no install required):

```bash
npx mcp-server-value-picker
```

### Local Development

For modifying the example or contributing:

```bash
npm install
npm run build
npm start
```

Default HTTP endpoint: `http://localhost:3456/mcp`

---

## How the Test Works

1. Connect this MCP server to your platform
2. The AI calls the `pick_value` tool, which displays 10 selectable values in the UI
3. User clicks a value card
4. The UI sends `ui/update-model-context` with the selection details
5. The UI sends `ui/message` asking "I have picked a value, can you tell me what it is?"
6. **If your platform works**: The AI responds with the correct value
7. **If something is broken**: The AI won't know what was selected

### Expected Model Response

The tool description explicitly tells the AI this is a debug test. A correct response looks like:

> "You selected **Alpha Protocol** (id: alpha)."

If the AI elaborates extensively on the value meanings, the test still passed (context injection worked), but the AI didn't follow the debug instructions.

---

## What This Tests

### Platform Requirements Verified

| Your Platform Must...               | Protocol Message                 | Verified By                  |
| ----------------------------------- | -------------------------------- | ---------------------------- |
| Inject UI context into model        | `ui/update-model-context`      | AI knows selected value      |
| Forward UI messages to conversation | `ui/message`                   | AI receives follow-up prompt |
| Deliver tool results to UI          | `ui/notifications/tool-result` | UI renders value cards       |
| Pass tool arguments to UI           | `ui/notifications/tool-input`  | UI receives empty args       |
| Handle teardown gracefully          | `ui/resource-teardown`         | No errors on close           |

### Full Specification Coverage

[Full Specification](https://github.com/modelcontextprotocol/ext-apps/tree/main/specification)

| Feature                                              | Spec Section         |
| ---------------------------------------------------- | -------------------- |
| `text/html;profile=mcp-app` MIME type              | UI Resource Format   |
| `ui://` URI scheme                                 | UI Resource Format   |
| `_meta.ui.resourceUri` linkage                     | Resource Discovery   |
| `ui/initialize` / `ui/notifications/initialized` | Lifecycle            |
| `ui/notifications/tool-input`                      | Data Passing         |
| `ui/notifications/tool-result`                     | Data Passing         |
| `ui/notifications/tool-cancelled`                  | Notifications        |
| `ui/resource-teardown`                             | Cleanup              |
| `ui/update-model-context`                          | Requests             |
| `ui/message`                                       | Requests             |
| `ui/notifications/host-context-changed`            | Notifications        |
| `HostContext.theme`                                | Theming              |
| `HostContext.styles.variables`                     | Theming              |
| `HostContext.styles.css.fonts`                     | Custom Fonts         |
| `HostContext.safeAreaInsets`                       | Container Dimensions |
| `content` + `structuredContent` dual model       | Data Passing         |

---

## Files

| File                | Purpose                                                |
| ------------------- | ------------------------------------------------------ |
| `server.ts`       | MCP server with `pick_value` tool and UI resource    |
| `src/mcp-app.ts`  | View implementation (`App` class, handlers, context) |
| `src/mcp-app.css` | View styling with CSS variable fallbacks               |
| `mcp-app.html`    | HTML template with color-scheme meta tag               |
| `main.ts`         | Entry point with STDIO/HTTP transport selection        |

---

## Implementation Details

<details>
<summary>Server-side implementation</summary>

### Tool Registration with UI Metadata

```typescript
registerAppTool(server, "pick_value", {
  title: "Pick a Value",
  description: "DEBUG/TEST TOOL: Tests MCP Apps communication between UI and model...",
  inputSchema: {},
  _meta: { ui: { resourceUri: "ui://pick-value/mcp-app.html" } },
}, async () => { /* handler */ });
```

### Dual Content Model

```typescript
return {
  content: [{
    type: "text",
    text: `[MCP Apps Test] This is a debug tool...`,
  }],
  structuredContent: {
    values: VALUES,  // UI-only, not sent to model
  },
};
```

</details>

<details>
<summary>View-side implementation</summary>

### Context Update

```typescript
await app.updateModelContext({
  content: [{
    type: "text",
    text: `The user selected "${value.label}" (id: ${value.id}).`,
  }],
});
```

### Message Sending

```typescript
await app.sendMessage({
  role: "user",
  content: [{
    type: "text",
    text: `I have picked a value, can you tell me what it is?`,
  }],
});
```

### Host Context Handling

```typescript
app.onhostcontextchanged = (ctx) => {
  if (ctx.theme) applyDocumentTheme(ctx.theme);
  if (ctx.styles?.variables) applyHostStyleVariables(ctx.styles.variables);
  if (ctx.styles?.css?.fonts) applyHostFonts(ctx.styles.css.fonts);
  if (ctx.safeAreaInsets) { /* apply padding */ }
};
```

</details>

By Sebastian Whincop - https://github.com/MacJedi42