mcp-server-value-picker 1.0.3 → 1.0.4

package/README.md

@@ -0,0 +1,450 @@
+# 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).
+
+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.
+
+## Purpose
+
+This example validates MCP Apps protocol features across all three layers:
+
+- **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
+
+---
+
+## 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
+
+Uses the `App` class with `PostMessageTransport` to connect to the Host:
+
+```typescript
+// From src/mcp-app.ts
+const app = new App({ name: "Value Picker", version: "1.0.0" });
+await app.connect();
+```
+
+**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);
+```
+
+### Host Context Handling
+
+Retrieves and responds to host context after connection:
+
+```typescript
+// From src/mcp-app.ts
+app.connect().then(() => {
+  const ctx = app.getHostContext();
+  if (ctx) handleHostContextChanged(ctx);
+});
+
+app.onhostcontextchanged = handleHostContextChanged;
+```
+
+**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
+}
+```
+
+### Theme Application
+
+Applies the host's color scheme preference:
+
+```typescript
+// From src/mcp-app.ts
+if (ctx.theme) {
+  applyDocumentTheme(ctx.theme);
+}
+```
+
+**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:
+
+```typescript
+// From src/mcp-app.ts
+if (ctx.styles?.variables) {
+  applyHostStyleVariables(ctx.styles.variables);
+}
+```
+
+**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
+```
+
+### Custom Font Loading
+
+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);
+}
+```
+
+**Spec Reference** ([Custom Fonts](../../specification/2026-01-26/apps.mdx#custom-fonts)):
+> Hosts can provide custom fonts via `styles.css.fonts`
+
+### Safe Area Insets
+
+Respects host-provided padding for notches, toolbars, etc.:
+
+```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`;
+}
+```
+
+### Tool Result Handler
+
+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);
+  }
+};
+```
+
+**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
+
+Receives tool call arguments (empty in this case):
+
+```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> }
+}
+```
+
+### Tool Cancellation Handler
+
+Handles cancelled tool execution:
+
+```typescript
+// From src/mcp-app.ts
+app.ontoolcancelled = (params) => {
+  statusEl.textContent = "Tool call was cancelled";
+};
+```
+
+**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:
+
+```typescript
+// From src/mcp-app.ts
+app.onteardown = async () => {
+  console.info("Value Picker app is being torn down");
+  return {};
+};
+```
+
+**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
+
+### Update Model Context
+
+Injects the user's selection into the model's context:
+
+```typescript
+// From src/mcp-app.ts
+await app.updateModelContext({
+  content: [{
+    type: "text",
+    text: `The user selected "${value.label}" (id: ${value.id}). Description: ${value.description}.`,
+  }],
+});
+```
+
+**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:
+
+```typescript
+// From src/mcp-app.ts
+await app.sendMessage({
+  role: "user",
+  content: [{
+    type: "text",
+    text: `I have picked a value, can you tell me what it is?`,
+  }],
+});
+```
+
+**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
+
+# Force HTTP mode
+npm start -- --http
+```
+
+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 | ✓ |

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "mcp-server-value-picker",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "type": "module",
-  "description": "Test MCP App: 10 selectable values + ui/update-model-context for Phase 5 testing",
+  "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",
   "files": [
     "dist"