mcp-server-value-picker 1.0.5 → 1.0.6

package/README.md

@@ -1,320 +1,180 @@
 # Value Picker Server
 
-A **debug/test MCP server** for validating that values selected in an MCP App UI are correctly passed to the AI model via `ui/update-model-context`. This package tests the complete View ↔ Host ↔ Model communication flow defined in [SEP-1865](../../specification/2026-01-26/apps.mdx).
+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 [SEP-1865](../../specification/2026-01-26/apps.mdx).
 
-The tool explicitly tells the AI model that this is a test — the model should simply confirm which value it received, not analyze or elaborate on the selection.
+## Why Use This?
 
-## Purpose
+When building an MCP Apps host, you need to verify that:
 
-This example validates MCP Apps protocol features across all three layers:
+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
 
-- **Server**: Tool registration, UI resource serving, `structuredContent` data passing
-- **Host**: Context injection, message proxying, lifecycle notifications
-- **View**: Theme handling, safe areas, tool result rendering, model context updates
+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.
 
 ---
 
-## Server-Side Features Tested
-
-### Tool Registration with UI Metadata
-
-Uses `registerAppTool()` to associate a tool with a UI resource via `_meta.ui.resourceUri`:
-
-```typescript
-// From server.ts
-registerAppTool(server, "pick_value", {
-  title: "Pick a Value",
-  description: "DEBUG/TEST TOOL: Tests MCP Apps communication between UI and model. The user picks a value in the UI, and you must confirm whether you received it. This validates that ui/update-model-context is working correctly. Do not treat this as a real decision — just report what value you received.",
-  inputSchema: {},
-  outputSchema: z.object({
-    values: z.array(z.object({
-      id: z.string(),
-      label: z.string(),
-      description: z.string(),
-    })),
-  }),
-  _meta: { ui: { resourceUri: "ui://pick-value/mcp-app.html" } },
-}, async () => { /* handler */ });
-```
-
-**Spec Reference** ([Resource Discovery](../../specification/2026-01-26/apps.mdx#resource-discovery)):
-```typescript
-interface Tool {
-  _meta?: {
-    ui?: {
-      resourceUri?: string;  // URI of UI resource for rendering
-      visibility?: Array<"model" | "app">;
-    };
-  };
-}
-```
-
-### UI Resource Registration
-
-Uses `registerAppResource()` to serve HTML content with the required MIME type:
-
-```typescript
-// From server.ts
-registerAppResource(server, resourceUri, resourceUri,
-  { mimeType: RESOURCE_MIME_TYPE },  // "text/html;profile=mcp-app"
-  async () => ({
-    contents: [{ uri: resourceUri, mimeType: RESOURCE_MIME_TYPE, text: html }],
-  })
-);
-```
-
-**Spec Reference** ([UI Resource Format](../../specification/2026-01-26/apps.mdx#ui-resource-format)):
-> `mimeType` MUST be `text/html;profile=mcp-app`
-
-### Dual Content Model (`content` + `structuredContent`)
-
-Tool returns both model-facing text and UI-facing structured data:
-
-```typescript
-// From server.ts
-return {
-  content: [{
-    type: "text",
-    text: `[MCP Apps Test] This is a debug tool for testing value communication...
-Your job: Simply report back the value you received. This tests whether the MCP Apps context injection is working. Do not provide detailed analysis of the values — just confirm what was selected.`,
-  }],
-  structuredContent: {
-    values: VALUES,  // Array of {id, label, description}
-    instruction: "Wait for the user to select a value via the UI.",
-  },
-};
-```
-
-**Spec Reference** ([Data Passing](../../specification/2026-01-26/apps.mdx#data-passing)):
-> - `content`: Text representation for model context and text-only hosts
-> - `structuredContent`: Structured data optimized for UI rendering (not added to model context)
-
-### Transport Modes
-
-Supports both STDIO and Streamable HTTP transports with auto-detection:
-
-```typescript
-// From main.ts
-function resolveTransport(): "stdio" | "http" {
-  if (process.argv.includes("--stdio")) return "stdio";
-  if (process.argv.includes("--http")) return "http";
-  return process.stdin.isTTY ? "http" : "stdio";
-}
-```
-
----
-
-## View-Side Features Tested
-
-### App Initialization & Connection
+## Installation
 
-Uses the `App` class with `PostMessageTransport` to connect to the Host:
+### Via npm (Recommended)
 
-```typescript
-// From src/mcp-app.ts
-const app = new App({ name: "Value Picker", version: "1.0.0" });
-await app.connect();
-```
+Install from [npmjs.com/package/mcp-server-value-picker](https://www.npmjs.com/package/mcp-server-value-picker):
 
-**Spec Reference** ([Transport Layer](../../specification/2026-01-26/apps.mdx#transport-layer)):
-```typescript
-const transport = new MessageTransport(window.parent);
-const client = new Client({ name: "ui-view", version: "1.0.0" });
-await client.connect(transport);
+```bash
+npm install -g mcp-server-value-picker
 ```
 
-### Host Context Handling
-
-Retrieves and responds to host context after connection:
+Run the server:
 
-```typescript
-// From src/mcp-app.ts
-app.connect().then(() => {
-  const ctx = app.getHostContext();
-  if (ctx) handleHostContextChanged(ctx);
-});
+```bash
+# Auto-detects transport mode
+mcp-server-value-picker
 
-app.onhostcontextchanged = handleHostContextChanged;
-```
+# Force STDIO mode (for Claude Desktop)
+mcp-server-value-picker --stdio
 
-**Spec Reference** ([Host Context in McpUiInitializeResult](../../specification/2026-01-26/apps.mdx#host-context-in-mcpuiinitializeresult)):
-```typescript
-interface HostContext {
-  theme?: "light" | "dark";
-  styles?: { variables?: Record<string, string>; css?: { fonts?: string } };
-  safeAreaInsets?: { top: number; right: number; bottom: number; left: number };
-  // ... other fields
-}
+# Force HTTP mode
+mcp-server-value-picker --http
 ```
 
-### Theme Application
-
-Applies the host's color scheme preference:
+Or run directly with npx (no install required):
 
-```typescript
-// From src/mcp-app.ts
-if (ctx.theme) {
-  applyDocumentTheme(ctx.theme);
-}
+```bash
+npx mcp-server-value-picker
 ```
 
-**Spec Reference** ([Theming](../../specification/2026-01-26/apps.mdx#theming)):
-> Views can use the `applyDocumentTheme` utility to easily respond to Host Context `theme` changes
-
-### CSS Variable Injection
-
-Applies host-provided CSS custom properties for visual cohesion:
+### Local Development
 
-```typescript
-// From src/mcp-app.ts
-if (ctx.styles?.variables) {
-  applyHostStyleVariables(ctx.styles.variables);
-}
-```
+For modifying the example or contributing:
 
-**Spec Reference** ([Theming - Current Standardized Variables](../../specification/2026-01-26/apps.mdx#current-standardized-variables)):
-```typescript
-type McpUiStyleVariableKey =
-  | "--color-background-primary"
-  | "--color-text-primary"
-  | "--font-sans"
-  // ... 80+ standardized variables
+```bash
+npm install
+npm run build
+npm start
 ```
 
-### Custom Font Loading
+Default HTTP endpoint: `http://localhost:3456/mcp`
 
-Injects host-provided font CSS (e.g., `@font-face` or `@import`):
+---
 
-```typescript
-// From src/mcp-app.ts
-if (ctx.styles?.css?.fonts) {
-  applyHostFonts(ctx.styles.css.fonts);
-}
-```
+## How the Test Works
 
-**Spec Reference** ([Custom Fonts](../../specification/2026-01-26/apps.mdx#custom-fonts)):
-> Hosts can provide custom fonts via `styles.css.fonts`
+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
 
-### Safe Area Insets
+### Expected Model Response
 
-Respects host-provided padding for notches, toolbars, etc.:
+The tool description explicitly tells the AI this is a debug test. A correct response looks like:
 
-```typescript
-// From src/mcp-app.ts
-if (ctx.safeAreaInsets) {
-  mainEl.style.paddingTop = `${ctx.safeAreaInsets.top}px`;
-  mainEl.style.paddingRight = `${ctx.safeAreaInsets.right}px`;
-  mainEl.style.paddingBottom = `${ctx.safeAreaInsets.bottom}px`;
-  mainEl.style.paddingLeft = `${ctx.safeAreaInsets.left}px`;
-}
-```
+> "You selected **Alpha Protocol** (id: alpha)."
 
-### Tool Result Handler
+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.
 
-Receives structured data via `ui/notifications/tool-result`:
+---
 
-```typescript
-// From src/mcp-app.ts
-app.ontoolresult = (result) => {
-  const structured = result.structuredContent as { values?: Value[] } | undefined;
-  if (structured?.values) {
-    renderValues(structured.values);
-  }
-};
-```
+## 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         |
 
-**Spec Reference** ([ui/notifications/tool-result](../../specification/2026-01-26/apps.mdx#notifications-host--view)):
-```typescript
-{
-  jsonrpc: "2.0",
-  method: "ui/notifications/tool-result",
-  params: CallToolResult  // { content, structuredContent, _meta }
-}
-```
+---
 
-### Tool Input Handler
+## Files
 
-Receives tool call arguments (empty in this case):
+| 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        |
 
-```typescript
-// From src/mcp-app.ts
-app.ontoolinput = (params) => {
-  console.info("Received tool input:", params);
-};
-```
+---
 
-**Spec Reference** ([ui/notifications/tool-input](../../specification/2026-01-26/apps.mdx#notifications-host--view)):
-```typescript
-{
-  jsonrpc: "2.0",
-  method: "ui/notifications/tool-input",
-  params: { arguments: Record<string, unknown> }
-}
-```
+## Implementation Details
 
-### Tool Cancellation Handler
+<details>
+<summary>Server-side implementation</summary>
 
-Handles cancelled tool execution:
+### Tool Registration with UI Metadata
 
 ```typescript
-// From src/mcp-app.ts
-app.ontoolcancelled = (params) => {
-  statusEl.textContent = "Tool call was cancelled";
-};
+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 */ });
 ```
 
-**Spec Reference** ([ui/notifications/tool-cancelled](../../specification/2026-01-26/apps.mdx#notifications-host--view)):
-> Host MUST send this notification if the tool execution was cancelled, for any reason
-
-### Teardown Handler
-
-Gracefully handles resource teardown:
+### Dual Content Model
 
 ```typescript
-// From src/mcp-app.ts
-app.onteardown = async () => {
-  console.info("Value Picker app is being torn down");
-  return {};
+return {
+  content: [{
+    type: "text",
+    text: `[MCP Apps Test] This is a debug tool...`,
+  }],
+  structuredContent: {
+    values: VALUES,  // UI-only, not sent to model
+  },
 };
 ```
 
-**Spec Reference** ([ui/resource-teardown](../../specification/2026-01-26/apps.mdx#notifications-host--view)):
-> Host MUST send this notification before tearing down the UI resource
+</details>
 
-### Update Model Context
+<details>
+<summary>View-side implementation</summary>
 
-Injects the user's selection into the model's context:
+### Context Update
 
 ```typescript
-// From src/mcp-app.ts
 await app.updateModelContext({
   content: [{
     type: "text",
-    text: `The user selected "${value.label}" (id: ${value.id}). Description: ${value.description}.`,
+    text: `The user selected "${value.label}" (id: ${value.id}).`,
   }],
 });
 ```
 
-**Spec Reference** ([ui/update-model-context](../../specification/2026-01-26/apps.mdx#requests-view--host)):
-```typescript
-{
-  jsonrpc: "2.0",
-  method: "ui/update-model-context",
-  params: {
-    content?: ContentBlock[],
-    structuredContent?: Record<string, unknown>
-  }
-}
-```
-
-> The View MAY send this request to update the Host's model context. This context will be used in future turns.
-
-### Send User Message
-
-Triggers an AI response after selection:
+### Message Sending
 
 ```typescript
-// From src/mcp-app.ts
 await app.sendMessage({
   role: "user",
   content: [{
@@ -324,127 +184,15 @@ await app.sendMessage({
 });
 ```
 
-**Spec Reference** ([ui/message](../../specification/2026-01-26/apps.mdx#requests-view--host)):
-```typescript
-{
-  jsonrpc: "2.0",
-  method: "ui/message",
-  params: {
-    role: "user",
-    content: { type: "text", text: string }
-  }
-}
-```
-
-> Host SHOULD add the message to the conversation context, preserving the specified role.
-
----
-
-## Test Pattern: "Blind Selection"
-
-This example implements a "blind selection" test pattern to validate context injection:
-
-1. User clicks a value card in the UI
-2. View sends `ui/update-model-context` with the selection details
-3. View sends `ui/message` with "I have picked a value, can you tell me what it is?"
-4. The AI must read the context to respond with the correct value
-
-This proves that `updateModelContext` successfully injects data that the model can access, without the user message containing the answer.
-
-### Expected Model Behavior
-
-The tool description explicitly tells the model this is a debug/test tool. The model should:
-
-- **Do**: Simply confirm which value it received (e.g., "You selected Alpha Protocol")
-- **Don't**: Provide detailed analysis, recommendations, or elaborate on the value meanings
-
-If the model goes into detail about the values, the test still passes (context injection worked), but the model didn't follow the debug instructions.
-
----
-
-## Installation
-
-### Via npm (Recommended)
-
-Install the published package 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
-# Run (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
-# Install dependencies
-npm install
-
-# Build UI and server
-npm run build
-
-# Run (auto-detects transport mode)
-npm start
-
-# Force STDIO mode
-npm start -- --stdio
+### Host Context Handling
 
-# Force HTTP mode
-npm start -- --http
+```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 */ }
+};
 ```
 
-Default HTTP endpoint: `http://localhost:3456/mcp`
-
----
-
-## 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 |
-
----
-
-## Specification Coverage
-
-| Feature | Spec Section | Tested |
-|---------|--------------|--------|
-| `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 | ✓ |
+</details>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-server-value-picker",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "type": "module",
   "description": "Debug/test MCP App: Validates that values selected in UI are correctly passed to the AI model via ui/update-model-context",
   "main": "dist/server.js",