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.

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:

npm install -g mcp-server-value-picker

Run the server:

# 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):

npx mcp-server-value-picker

Local Development

For modifying the example or contributing:

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

Full Specification Coverage

Full Specification

Files

Implementation Details

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 */ });

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

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

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

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 */ }
};

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