@seed-ship/mcp-ui-solid 5.2.0 → 5.3.1

package/docs/recipes/elicitation-pseudo-spec-adapter.md

@@ -0,0 +1,171 @@
+# Recipe — Pseudo-elicit → spec elicit adapter
+
+> **Audience** : consumer chat apps that talk to an MCP server still emitting
+> a *legacy* "pseudo-elicit" payload inline with `tools/call` results, but
+> wanting to use mcp-ui's spec-correct `<ChatPrompt>` / `<ElicitationForm>`
+> (MCP 2025-06-18).
+>
+> **Where this code lives** : in YOUR consumer app, not in mcp-ui. mcp-ui
+> stays tool- and server-agnostic by design — it ships the spec helper
+> (`elicitationToPromptConfig`, `<ElicitationForm>`) but does NOT bake in
+> any vendor-specific wire shape.
+
+## Why this exists
+
+The MCP spec 2025-06-18 defines elicitation as a server→client JSON-RPC
+*request* (`elicitation/create`) carrying `{ message, requestedSchema }`,
+with `requestedSchema` shaped as a JSON Schema object.
+
+Some servers ship a different convention — they return an `elicitation`
+**object inline** in the result of a `tools/call`, with a flat `fields[]`
+array instead of a JSON Schema. Example (deposium_MCPs as of 2026-04) :
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "elicitation": {
+      "type": "form",
+      "title": "Required Parameters Missing",
+      "description": "Please provide the following required parameters:",
+      "fields": [
+        { "name": "tenant_id", "type": "string", "label": "Tenant ID", "required": true, "default": "<uuid>" },
+        { "name": "space_id",  "type": "string", "label": "Space ID",  "required": true, "default": "default" }
+      ]
+    }
+  }
+}
+```
+
+Until that server migrates to spec elicitation, the chat app can adapt the
+shape on the fly, then drive `<ElicitationForm>` (or
+`elicitationToPromptConfig`) as if everything were spec.
+
+## The adapter (drop-in TypeScript)
+
+```ts
+import type { ElicitationEvent, ElicitationPropertySchema } from '@seed-ship/mcp-ui-solid'
+
+interface PseudoElicit {
+  type: 'form'
+  title: string
+  description?: string
+  fields: Array<{
+    name: string
+    type: 'string' | 'number' | 'boolean'
+    label?: string
+    description?: string
+    required?: boolean
+    default?: unknown
+    enum?: Array<string | number>
+  }>
+}
+
+/**
+ * Convert a pseudo-elicit payload (legacy inline form spec) to a spec-shaped
+ * MCP `ElicitationEvent`. Returns `null` if the input does not look like a
+ * pseudo-elicit — the caller can then handle the tools/call result normally.
+ */
+export function pseudoElicitToSpec(toolResult: unknown): ElicitationEvent | null {
+  const pseudo = (toolResult as { elicitation?: PseudoElicit })?.elicitation
+  if (!pseudo || pseudo.type !== 'form' || !Array.isArray(pseudo.fields)) {
+    return null
+  }
+
+  const properties: Record<string, ElicitationPropertySchema> = {}
+  const required: string[] = []
+
+  for (const field of pseudo.fields) {
+    const schema: ElicitationPropertySchema = {
+      type: mapType(field.type),
+      ...(field.label !== undefined && { title: field.label }),
+      ...(field.description !== undefined && { description: field.description }),
+      ...(field.default !== undefined && { default: field.default }),
+      ...(field.enum && { enum: field.enum }),
+    }
+    properties[field.name] = schema
+    if (field.required) required.push(field.name)
+  }
+
+  return {
+    message: [pseudo.title, pseudo.description].filter(Boolean).join(' — '),
+    requestedSchema: {
+      type: 'object',
+      properties,
+      ...(required.length > 0 && { required }),
+    },
+  }
+}
+
+function mapType(t: string): ElicitationPropertySchema['type'] {
+  if (t === 'number' || t === 'boolean') return t
+  return 'string' // safe fallback for unknown legacy types
+}
+```
+
+## Wiring it into the chat app
+
+```ts
+import { bus } from './your-bus-instance'
+import { ElicitationForm } from '@seed-ship/mcp-ui-solid'
+import { pseudoElicitToSpec } from './adapters/pseudo-elicit'
+
+async function callTool(name: string, args: Record<string, unknown>) {
+  const response = await mcpClient.callTool(name, args)
+
+  // 1. Check for pseudo-elicit BEFORE treating result as a normal tool output.
+  const elicit = pseudoElicitToSpec(response.result)
+  if (elicit) {
+    showElicitationDialog(elicit, async (content) => {
+      // 2. Re-invoke the tool with the collected args merged in.
+      return callTool(name, { ...args, ...content })
+    })
+    return
+  }
+
+  // 3. Normal tool output path.
+  handleToolResult(response.result)
+}
+
+function showElicitationDialog(
+  event: ElicitationEvent,
+  onAccept: (content: Record<string, unknown>) => Promise<void>
+) {
+  // Mount <ElicitationForm> in your modal layer, or pipe through the bus :
+  bus.events.emit('onElicitation', { streamKey: 'main', elicitation: event })
+}
+```
+
+If you also want `<ElicitationForm>` to render directly :
+
+```tsx
+<Show when={pendingElicit()}>
+  <ElicitationForm
+    event={pendingElicit()!}
+    onAccept={async (content) => {
+      setPendingElicit(null)
+      await retryToolCall(content)
+    }}
+    onCancel={() => setPendingElicit(null)}
+  />
+</Show>
+```
+
+## Going both ways (spec + pseudo)
+
+Once your server migrates to real `elicitation/create` (server→client
+JSON-RPC request over a bidirectional transport), keep the adapter
+in place — it's harmless on a normal `tools/call` result (returns
+`null`) and lets you support both wire shapes for the duration of the
+rollout.
+
+For the spec path, your transport adapter handles the JSON-RPC request
+directly and emits the same `onElicitation` event with a payload that
+already matches `ElicitationEvent` — no adapter call needed.
+
+## Reference
+
+- MCP spec : https://spec.modelcontextprotocol.io/specification/2025-06-18/client/elicitation/
+- mcp-ui types : `ElicitationEvent`, `ElicitationRequestedSchema`, `ElicitationPropertySchema` (all exported from `@seed-ship/mcp-ui-solid`)
+- mcp-ui helpers : `elicitationToPromptConfig` (services/chat-bus), `<ElicitationForm>` (components)

package/docs/recipes/feedback-inline-wiring.md

@@ -0,0 +1,142 @@
+# Recipe — Wire `<FeedbackInline>` to a feedback HTTP endpoint
+
+> **Audience** : consumer apps that ship `<FeedbackInline>` (per-message
+> thumbs-up/down) and want to persist ratings to a backend.
+>
+> mcp-ui's `<FeedbackInline>` is intentionally endpoint-agnostic — it
+> calls `onSubmit(rating, context)` and the consumer owns the HTTP / store
+> wiring. This recipe shows the most common pattern, using the Deposium
+> `POST /api/feedback` endpoint as a concrete example.
+
+## What `<FeedbackInline>` gives you
+
+```tsx
+<FeedbackInline
+  messageHash={msg.hash}
+  context={{ intent: msg.intent, confidenceBand: msg.band }}
+  onSubmit={(rating, context) => persistFeedback(rating, context)}
+/>
+```
+
+The component :
+- Renders two buttons (positive / negative).
+- Flips to "submitted" optimistically on click — UI does NOT revert on network error (best-effort design).
+- Calls `onSubmit('positive' | 'negative', context?)` exactly once.
+
+`rating` already matches the shape Deposium expects. Mapping is direct.
+
+## Endpoint reference (Deposium)
+
+`POST /api/feedback` — no auth required, behind the chat-stream / standard
+middleware chain.
+
+### Request body
+
+```ts
+interface FeedbackRequest {
+  message_hash: string                           // REQUIRED — message ID being rated
+  rating: 'positive' | 'negative' | 'partial'
+  confidence_band?: 'high' | 'medium' | 'low'    // optional, free-form string
+  intent?: string                                // optional, e.g. 'search_query'
+  space_ids?: string[] | string | null
+  comment?: string
+  tenant_id?: string
+}
+```
+
+### Response
+
+| Status | Body |
+|---|---|
+| 200    | `{ ok: true, id: 'fb_<timestamp>_<rand4>' }` |
+| 400    | `{ error: 'rating must be one of: positive, negative, partial' }` |
+
+### Side effects (worth knowing)
+
+- `INSERT` into `logs.feedback` (PostgreSQL) — drives dashboard analytics.
+- `'positive' | 'negative'` ratings also update
+  `logs.intent_classifications.feedback_success`. `'partial'` does **not**
+  propagate (intentional — neither true nor false).
+
+## Wiring (the recipe)
+
+```tsx
+import { FeedbackInline, type FeedbackInlineContext } from '@seed-ship/mcp-ui-solid'
+
+function persistFeedback(
+  messageHash: string,
+  rating: 'positive' | 'negative',
+  ctx?: FeedbackInlineContext
+): Promise<void> {
+  return fetch('/api/feedback', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      message_hash: messageHash,
+      rating, // 'positive' | 'negative' — matches endpoint as-is
+      ...(ctx?.intent && { intent: ctx.intent }),
+      ...(ctx?.confidenceBand && { confidence_band: ctx.confidenceBand }),
+      ...(ctx?.tenantId && { tenant_id: ctx.tenantId }),
+      ...(ctx?.spaceIds && { space_ids: ctx.spaceIds }),
+      ...(ctx?.comment && { comment: ctx.comment }),
+    }),
+  }).then(async (res) => {
+    if (!res.ok) {
+      console.warn('[feedback] persist failed', res.status, await res.text())
+    }
+  }).catch((err) => {
+    // Silent failure — UI is already in the optimistic "submitted" state.
+    console.warn('[feedback] network error', err)
+  })
+}
+
+function MessageRow(props: { msg: ChatMessage }) {
+  return (
+    <div class="message-row">
+      <p>{props.msg.text}</p>
+      <FeedbackInline
+        messageHash={props.msg.hash}
+        context={{
+          intent: props.msg.intent,
+          confidenceBand: props.msg.confidenceBand,
+        }}
+        onSubmit={(rating, ctx) => persistFeedback(props.msg.hash, rating, ctx)}
+      />
+    </div>
+  )
+}
+```
+
+## Variations
+
+### "Partial" rating
+
+`<FeedbackInline>` emits only `'positive'` / `'negative'`. If you need a
+third state (`'partial'`), build a separate UI (e.g. a star rating or a
+3-button row) and call the endpoint directly with `rating: 'partial'`.
+
+### Free-text comment
+
+Add a textarea below `<FeedbackInline>` that opens after the rating click.
+Send a follow-up `POST /api/feedback` with the same `message_hash` and a
+`comment` field — the endpoint accepts multiple records per message.
+
+### Optimistic vs strict semantics
+
+Default behavior is best-effort (UI never reverts). If you need stricter
+semantics — offline retry queue, edit-rating UX — wrap `<FeedbackInline>`
+in your own component and own the state externally instead of relying on
+the component's internal flip.
+
+## Where this code lives
+
+In your consumer app. mcp-ui ships `<FeedbackInline>` and the `onSubmit`
+contract; the HTTP wiring (URL, auth, retry policy, schema mapping) is
+the consumer's responsibility by design — same pattern as
+`pseudo-elicit-spec-adapter`.
+
+## Reference
+
+- mcp-ui component : `<FeedbackInline>` (exported from `@seed-ship/mcp-ui-solid`)
+- mcp-ui types : `FeedbackInlineProps`, `FeedbackInlineContext`
+- Deposium endpoint : `POST /api/feedback` — see deposium_MCPs `src/routes/feedback.ts`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-ship/mcp-ui-solid",
-  "version": "5.2.0",
+  "version": "5.3.1",
   "description": "SolidJS components for rendering MCP-generated UI resources",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -140,7 +140,7 @@
   },
   "dependencies": {
     "@types/dompurify": "^3.0.5",
-    "dompurify": "^3.3.3",
+    "dompurify": "^3.4.1",
     "marked": "^16.3.0",
     "zod": "^3.22.4"
   },

package/src/components/ElicitationForm.test.tsx

@@ -0,0 +1,197 @@
+/**
+ * Tests for ElicitationForm — v5.3.0
+ *
+ * Coverage focus : the inverse mapping (ChatPromptResponse → spec content)
+ * that this wrapper owns. The forward mapping (spec → ChatPromptConfig) is
+ * already covered by `chat-bus.test.ts elicitationToPromptConfig`.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, fireEvent, cleanup } from '@solidjs/testing-library'
+import { ElicitationForm } from './ElicitationForm'
+import type { ElicitationEvent } from '../types/chat-bus'
+
+describe('ElicitationForm — v5.3.0', () => {
+  beforeEach(() => {
+    cleanup()
+  })
+
+  it('boolean property → confirm UI → onAccept gets { propName: true }', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Proceed?',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          consent: { type: 'boolean', description: 'I agree' },
+        },
+        required: ['consent'],
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} onCancel={() => {}} />
+    ))
+
+    // ChatPrompt renders a Confirm button — find and click it.
+    const confirmBtn = getByText('Confirm') as HTMLElement
+    fireEvent.click(confirmBtn)
+
+    expect(onAccept).toHaveBeenCalledTimes(1)
+    expect(onAccept).toHaveBeenCalledWith({ consent: true })
+  })
+
+  it('single enum property → choice UI → onAccept gets { propName: enumValue }', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Pick a tier',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          tier: {
+            type: 'string',
+            enum: ['free', 'pro', 'enterprise'],
+            enumNames: ['Free', 'Pro', 'Enterprise'],
+          },
+        },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} />
+    ))
+
+    fireEvent.click(getByText('Pro') as HTMLElement)
+
+    expect(onAccept).toHaveBeenCalledWith({ tier: 'pro' })
+  })
+
+  it('numeric enum property → onAccept coerces value to number', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Pick a level',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          level: { type: 'integer', enum: [1, 2, 3] },
+        },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} />
+    ))
+
+    fireEvent.click(getByText('2') as HTMLElement)
+
+    expect(onAccept).toHaveBeenCalledWith({ level: 2 })
+  })
+
+  it('multi-property schema → form UI → onAccept gets formValues unchanged', () => {
+    const onAccept = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Tenant scope required',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          tenant_id: { type: 'string', title: 'Tenant ID' },
+          space_id: { type: 'string', title: 'Space ID', default: 'default' },
+        },
+        required: ['tenant_id', 'space_id'],
+      },
+    }
+
+    const { container, getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} />
+    ))
+
+    const tenantInput = container.querySelector('input[name="tenant_id"]') as HTMLInputElement
+    const spaceInput = container.querySelector('input[name="space_id"]') as HTMLInputElement
+    expect(tenantInput).toBeTruthy()
+    expect(spaceInput).toBeTruthy()
+
+    fireEvent.input(tenantInput, { target: { value: 'acme-co' } })
+    fireEvent.input(spaceInput, { target: { value: 'prod' } })
+
+    const submitBtn = getByText('Submit') as HTMLElement
+    fireEvent.click(submitBtn)
+
+    expect(onAccept).toHaveBeenCalledTimes(1)
+    const [content] = onAccept.mock.calls[0]
+    expect(content).toMatchObject({ tenant_id: 'acme-co', space_id: 'prod' })
+  })
+
+  it('X dismiss → onCancel fires, onAccept does NOT', () => {
+    const onAccept = vi.fn()
+    const onCancel = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Pick a tier',
+      requestedSchema: {
+        type: 'object',
+        properties: {
+          tier: { type: 'string', enum: ['a', 'b'] },
+        },
+      },
+    }
+
+    const { container } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} onCancel={onCancel} />
+    ))
+
+    const dismissBtn = container.querySelector('[aria-label="Dismiss"]') as HTMLElement
+    fireEvent.click(dismissBtn)
+
+    expect(onCancel).toHaveBeenCalledTimes(1)
+    expect(onAccept).not.toHaveBeenCalled()
+  })
+
+  it('onDecline takes precedence over onCancel when provided', () => {
+    const onAccept = vi.fn()
+    const onCancel = vi.fn()
+    const onDecline = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Proceed?',
+      requestedSchema: {
+        type: 'object',
+        properties: { consent: { type: 'boolean' } },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm
+        event={event}
+        onAccept={onAccept}
+        onCancel={onCancel}
+        onDecline={onDecline}
+        dismissLabel="Decline"
+      />
+    ))
+
+    fireEvent.click(getByText('Decline') as HTMLElement)
+
+    expect(onDecline).toHaveBeenCalledTimes(1)
+    expect(onCancel).not.toHaveBeenCalled()
+    expect(onAccept).not.toHaveBeenCalled()
+  })
+
+  it('confirm cancel button → onCancel fires (dismissed=true via cancel button)', () => {
+    const onAccept = vi.fn()
+    const onCancel = vi.fn()
+    const event: ElicitationEvent = {
+      message: 'Proceed?',
+      requestedSchema: {
+        type: 'object',
+        properties: { consent: { type: 'boolean' } },
+      },
+    }
+
+    const { getByText } = render(() => (
+      <ElicitationForm event={event} onAccept={onAccept} onCancel={onCancel} />
+    ))
+
+    fireEvent.click(getByText('Cancel') as HTMLElement)
+
+    expect(onCancel).toHaveBeenCalledTimes(1)
+    expect(onAccept).not.toHaveBeenCalled()
+  })
+})

package/src/components/ElicitationForm.tsx

@@ -0,0 +1,126 @@
+/**
+ * ElicitationForm — schema-driven renderer for MCP `elicitation/create` requests
+ *
+ * @experimental
+ * @since v5.3.0
+ *
+ * Thin wrapper over `<ChatPrompt>` + `elicitationToPromptConfig()` that
+ * accepts a spec-shaped `ElicitationEvent` (MCP 2025-06-18) and exposes a
+ * spec-shaped `onAccept(content)` callback whose payload is ready to send
+ * back as the `accept` outcome of an `elicitation/create` reply.
+ *
+ * The mapping (boolean → confirm, single enum ≤4 → choice, else → form) is
+ * delegated to the `elicitationToPromptConfig` helper — same rules, same
+ * tests. This component owns the inverse mapping : extracting a spec-shaped
+ * `Record<string, unknown>` from the `ChatPromptResponse`.
+ *
+ * ## Outcome semantics (per MCP spec 2025-06-18)
+ *
+ * | User action                           | Callback fired     | Payload                          |
+ * |---------------------------------------|--------------------|----------------------------------|
+ * | Submit form / pick choice / confirm   | `onAccept(content)`| `{ [propName]: value, ... }`     |
+ * | X icon / Cancel button                | `onCancel()` *or* `onDecline()` if provided | none                |
+ *
+ * mcp-ui's `<ChatPrompt>` does not natively distinguish "decline" (explicit
+ * refusal) from "cancel" (passive close). To surface a decline action,
+ * pass `dismissLabel="Decline"` and route the callback via `onDecline`.
+ *
+ * @example
+ * ```tsx
+ * bus.events.on('onElicitation', ({ elicitation }) => {
+ *   render(() => (
+ *     <ElicitationForm
+ *       event={elicitation}
+ *       onAccept={(content) => sendElicitationReply({ action: 'accept', content })}
+ *       onCancel={() => sendElicitationReply({ action: 'cancel' })}
+ *     />
+ *   ), mountPoint)
+ * })
+ * ```
+ */
+
+import { Component } from 'solid-js'
+import { ChatPrompt } from './ChatPrompt'
+import { elicitationToPromptConfig } from '../services/chat-bus'
+import type {
+  ChatPromptResponse,
+  ElicitationEvent,
+  ElicitationPropertySchema,
+} from '../types/chat-bus'
+
+export interface ElicitationFormProps {
+  /** MCP `elicitation/create` request payload to render. */
+  event: ElicitationEvent
+  /**
+   * Called when user submits a valid response. `content` is keyed by the
+   * elicitation `requestedSchema.properties` names — ready to send back as
+   * the `accept` outcome of an `elicitation/create` reply.
+   */
+  onAccept: (content: Record<string, unknown>) => void
+  /** Called when user dismisses (X icon, confirm-cancel button). */
+  onCancel?: () => void
+  /**
+   * Optional explicit decline action. When provided, takes precedence over
+   * `onCancel` on dismiss. Pair with `dismissLabel="Decline"` to surface as
+   * a decline action in the UI.
+   */
+  onDecline?: () => void
+  /** Label on the dismiss button (default: X icon). */
+  dismissLabel?: string
+}
+
+/**
+ * @experimental
+ * Schema-driven renderer for MCP `elicitation/create` requests.
+ */
+export const ElicitationForm: Component<ElicitationFormProps> = (props) => {
+  const config = () => elicitationToPromptConfig(props.event)
+
+  const handleSubmit = (response: ChatPromptResponse): void => {
+    if (response.dismissed) {
+      ;(props.onDecline ?? props.onCancel)?.()
+      return
+    }
+    props.onAccept(extractContent(response, props.event))
+  }
+
+  return <ChatPrompt config={config()} dismissLabel={props.dismissLabel} onSubmit={handleSubmit} />
+}
+
+function extractContent(
+  response: ChatPromptResponse,
+  event: ElicitationEvent
+): Record<string, unknown> {
+  // Form: response.value is already a Record keyed by property names.
+  if (typeof response.value !== 'string') {
+    return response.value
+  }
+
+  const propEntries = Object.entries(event.requestedSchema.properties)
+
+  // Single-property cases (boolean confirm or single enum choice).
+  if (propEntries.length === 1) {
+    const [name, schema] = propEntries[0]
+    return { [name]: coerceScalar(response.value, schema) }
+  }
+
+  // Multi-property string response — shouldn't happen since the helper
+  // routes multi-prop schemas to 'form'. Fall back gracefully.
+  console.warn(
+    '[MCP-UI] ElicitationForm: received string value for multi-property schema. Falling back to _value.'
+  )
+  return { _value: response.value }
+}
+
+function coerceScalar(value: string, schema: ElicitationPropertySchema): unknown {
+  // Confirm always emits the literal 'confirmed' on accept (cancel path is
+  // trapped earlier by `dismissed: true`). Map to boolean true.
+  if (schema.type === 'boolean') return true
+
+  if (schema.type === 'number' || schema.type === 'integer') {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : value
+  }
+
+  return value
+}

package/src/components/index.ts

@@ -88,5 +88,9 @@ export type { DataPreviewSectionProps } from './DataPreviewSection'
 export { RenderContext, RenderProvider, useRenderContext } from './RenderContext'
 export type { RenderContextValue, RenderComponentFn } from './RenderContext'
 
+// MCP elicitation (v5.3.0)
+export { ElicitationForm } from './ElicitationForm'
+export type { ElicitationFormProps } from './ElicitationForm'
+
 // Default exports for lazy loading compatibility
 export { UIResourceRenderer as default } from './UIResourceRenderer'