@seed-ship/mcp-ui-solid 5.1.0 → 5.3.0

package/src/stores/server-capabilities-store.test.tsx

@@ -0,0 +1,206 @@
+/**
+ * Tests for server-capabilities-store — v5.3.0
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest'
+import { render, cleanup } from '@solidjs/testing-library'
+import { createEffect, createRoot } from 'solid-js'
+import {
+  createServerCapabilitiesStore,
+  setServerCapabilities,
+  useServerCapabilities,
+  ServerCapabilitiesProvider,
+} from './server-capabilities-store'
+import type { ServerInitializeInfo } from './server-capabilities-store'
+
+const sampleInfo: ServerInitializeInfo = {
+  protocolVersion: '2025-06-18',
+  serverInfo: { name: 'deposium-mcp', version: '1.4.2' },
+  capabilities: {
+    tools: { listChanged: true },
+    prompts: { listChanged: false },
+    resources: { listChanged: true, subscribe: false },
+  },
+  instructions: 'Use deposium_chat for synthesis questions.',
+}
+
+describe('createServerCapabilitiesStore — v5.3.0', () => {
+  beforeEach(() => {
+    cleanup()
+    setServerCapabilities(null) // reset module singleton between tests
+  })
+
+  it('two factory stores do not share state', () => {
+    const storeA = createServerCapabilitiesStore()
+    const storeB = createServerCapabilitiesStore()
+
+    storeA.set(sampleInfo)
+
+    expect(storeA.info()?.serverInfo.name).toBe('deposium-mcp')
+    expect(storeB.info()).toBeNull()
+  })
+
+  it('accessors return null until set is called', () => {
+    const store = createServerCapabilitiesStore()
+
+    expect(store.info()).toBeNull()
+    expect(store.capabilities()).toBeNull()
+    expect(store.serverInfo()).toBeNull()
+    expect(store.protocolVersion()).toBeNull()
+    expect(store.hasCapability('tools')).toBe(false)
+  })
+
+  it('set(info) populates all derived accessors', () => {
+    const store = createServerCapabilitiesStore()
+    store.set(sampleInfo)
+
+    expect(store.protocolVersion()).toBe('2025-06-18')
+    expect(store.serverInfo()?.version).toBe('1.4.2')
+    expect(store.capabilities()?.tools?.listChanged).toBe(true)
+  })
+
+  it('set(null) clears the store', () => {
+    const store = createServerCapabilitiesStore()
+    store.set(sampleInfo)
+    expect(store.info()).not.toBeNull()
+
+    store.set(null)
+    expect(store.info()).toBeNull()
+    expect(store.hasCapability('tools')).toBe(false)
+  })
+
+  it('hasCapability returns true for present keys, false for absent', () => {
+    const store = createServerCapabilitiesStore()
+    store.set(sampleInfo)
+
+    expect(store.hasCapability('tools')).toBe(true)
+    expect(store.hasCapability('prompts')).toBe(true)
+    expect(store.hasCapability('resources')).toBe(true)
+    expect(store.hasCapability('logging')).toBe(false)
+    expect(store.hasCapability('completions')).toBe(false)
+    expect(store.hasCapability('experimental')).toBe(false)
+  })
+})
+
+describe('setServerCapabilities + useServerCapabilities (singleton path)', () => {
+  beforeEach(() => {
+    cleanup()
+    setServerCapabilities(null)
+  })
+
+  it('useServerCapabilities falls back to module singleton outside provider', () => {
+    setServerCapabilities(sampleInfo)
+
+    let captured: ReturnType<typeof useServerCapabilities> | null = null
+    const Probe = () => {
+      captured = useServerCapabilities()
+      return null
+    }
+    render(() => <Probe />)
+
+    expect(captured).not.toBeNull()
+    expect(captured!.serverInfo()?.name).toBe('deposium-mcp')
+    expect(captured!.hasCapability('tools')).toBe(true)
+  })
+
+  it('singleton state survives across renders', () => {
+    setServerCapabilities(sampleInfo)
+
+    const captures: Array<string | undefined> = []
+    const Probe = () => {
+      const { serverInfo } = useServerCapabilities()
+      captures.push(serverInfo()?.name)
+      return null
+    }
+    render(() => <Probe />)
+    render(() => <Probe />)
+
+    expect(captures).toEqual(['deposium-mcp', 'deposium-mcp'])
+  })
+})
+
+describe('ServerCapabilitiesProvider scoping', () => {
+  beforeEach(() => {
+    cleanup()
+    setServerCapabilities(null)
+  })
+
+  it('provider with explicit store overrides the singleton for descendants', () => {
+    setServerCapabilities(sampleInfo) // singleton has deposium-mcp
+
+    const scopedStore = createServerCapabilitiesStore()
+    scopedStore.set({
+      ...sampleInfo,
+      serverInfo: { name: 'other-mcp', version: '0.1.0' },
+    })
+
+    let inside: string | undefined
+    let outside: string | undefined
+
+    const Inside = () => {
+      inside = useServerCapabilities().serverInfo()?.name
+      return null
+    }
+    const Outside = () => {
+      outside = useServerCapabilities().serverInfo()?.name
+      return null
+    }
+
+    render(() => (
+      <>
+        <Outside />
+        <ServerCapabilitiesProvider store={scopedStore}>
+          <Inside />
+        </ServerCapabilitiesProvider>
+      </>
+    ))
+
+    expect(outside).toBe('deposium-mcp')
+    expect(inside).toBe('other-mcp')
+  })
+
+  it('provider without store creates a fresh isolated handle', () => {
+    setServerCapabilities(sampleInfo)
+
+    let inside: ReturnType<typeof useServerCapabilities> | null = null
+    const Inside = () => {
+      inside = useServerCapabilities()
+      return null
+    }
+    render(() => (
+      <ServerCapabilitiesProvider>
+        <Inside />
+      </ServerCapabilitiesProvider>
+    ))
+
+    expect(inside).not.toBeNull()
+    expect(inside!.info()).toBeNull() // fresh, not the singleton's state
+  })
+
+  it('set() updates trigger reactive effects', () => {
+    const store = createServerCapabilitiesStore()
+    const captures: Array<string | null> = []
+
+    let dispose: (() => void) | undefined
+    createRoot((d) => {
+      dispose = d
+      createEffect(() => {
+        captures.push(store.serverInfo()?.name ?? null)
+      })
+    })
+
+    // Initial effect run
+    expect(captures).toEqual([null])
+
+    store.set(sampleInfo)
+    expect(captures).toEqual([null, 'deposium-mcp'])
+
+    store.set({ ...sampleInfo, serverInfo: { name: 'renamed', version: '2.0.0' } })
+    expect(captures).toEqual([null, 'deposium-mcp', 'renamed'])
+
+    store.set(null)
+    expect(captures).toEqual([null, 'deposium-mcp', 'renamed', null])
+
+    dispose?.()
+  })
+})

package/src/stores/server-capabilities-store.tsx

@@ -0,0 +1,215 @@
+/**
+ * Server Capabilities Store — reactive snapshot of the MCP `initialize`
+ * response echoed by the server.
+ *
+ * @experimental
+ * @since v5.3.0
+ *
+ * mcp-ui doesn't speak MCP protocol directly — the consumer's transport
+ * layer (stdio child process, HTTP/SSE client, ...) parses the
+ * `initialize` JSON-RPC response and pushes the relevant fields into this
+ * store via `setServerCapabilities(info)`. Components then read
+ * reactively via `useServerCapabilities()` to gate behavior :
+ *
+ * ```tsx
+ * const { capabilities } = useServerCapabilities()
+ * <Show when={capabilities()?.tools?.listChanged}>
+ *   <ToolListSubscriber />
+ * </Show>
+ * ```
+ *
+ * ## Two consumption modes (mirrors `scratchpad-store`)
+ *
+ * 1. **Singleton mode (default)** — `setServerCapabilities(info)` mutates
+ *    the module-level singleton. `useServerCapabilities()` reads from it.
+ *    Use for single-MCP-server consumers (the common case).
+ *
+ * 2. **Multi-instance mode** — wrap a subtree in
+ *    `<ServerCapabilitiesProvider>` to scope a separate handle. Pass
+ *    `store={createServerCapabilitiesStore()}` explicitly when you need to
+ *    drive it from a non-reactive scope (e.g. a transport adapter living
+ *    at the app root).
+ *
+ * ## Note on `elicitation`
+ *
+ * Per MCP spec 2025-06-18, `elicitation` is a **CLIENT** capability, not
+ * a server one. Servers do not declare it. If you need to gate
+ * `<ElicitationForm>` rendering on whether the connected client *itself*
+ * supports elicitation — that's a separate concern (your own state, set
+ * by your transport layer based on its own configuration).
+ */
+
+import { createContext, useContext, type ParentComponent, type JSX } from 'solid-js'
+import { createStore } from 'solid-js/store'
+
+// ─── Types ────────────────────────────────────────────────────
+
+/**
+ * Server capabilities object as advertised in the MCP `initialize` response.
+ * Mirrors the spec 2025-06-18 `ServerCapabilities` shape with permissive
+ * `experimental` for forward compatibility.
+ */
+export interface ServerCapabilities {
+  experimental?: Record<string, unknown>
+  logging?: Record<string, never>
+  tools?: { listChanged?: boolean }
+  prompts?: { listChanged?: boolean }
+  resources?: { listChanged?: boolean; subscribe?: boolean }
+  completions?: Record<string, never>
+}
+
+/**
+ * Subset of the MCP `initialize` response relevant to the UI layer.
+ * Consumers may extend this via the `experimental` field.
+ */
+export interface ServerInitializeInfo {
+  protocolVersion: string
+  serverInfo: { name: string; version: string; title?: string; [key: string]: unknown }
+  capabilities: ServerCapabilities
+  instructions?: string
+}
+
+// ─── Handle ───────────────────────────────────────────────────
+
+export interface ServerCapabilitiesStoreHandle {
+  /** Push a fresh `initialize` snapshot into the store, or clear with `null`. */
+  set: (info: ServerInitializeInfo | null) => void
+  /** Reactive accessor for the full info (null when no initialize received). */
+  info: () => ServerInitializeInfo | null
+  /** Reactive accessor for just the `capabilities` field. */
+  capabilities: () => ServerCapabilities | null
+  /** Reactive accessor for just the `serverInfo` field. */
+  serverInfo: () => ServerInitializeInfo['serverInfo'] | null
+  /** Reactive accessor for the protocol version string. */
+  protocolVersion: () => string | null
+  /**
+   * Helper : returns true if the server advertised the named capability key
+   * with a truthy value (i.e. the key is present, even as an empty object).
+   */
+  hasCapability: (key: keyof ServerCapabilities) => boolean
+}
+
+// ─── Factory ──────────────────────────────────────────────────
+
+/**
+ * Create an isolated server-capabilities store instance.
+ *
+ * Use this when you need to track multiple MCP servers in parallel (rare),
+ * or to drive the store from a non-reactive transport adapter. Pair with
+ * `<ServerCapabilitiesProvider store={...}>` to scope a SolidJS subtree.
+ *
+ * @experimental
+ * @since v5.3.0
+ */
+export function createServerCapabilitiesStore(): ServerCapabilitiesStoreHandle {
+  const [state, setState] = createStore<{ info: ServerInitializeInfo | null }>({ info: null })
+
+  return {
+    set: (info) => setState('info', info),
+    info: () => state.info,
+    capabilities: () => state.info?.capabilities ?? null,
+    serverInfo: () => state.info?.serverInfo ?? null,
+    protocolVersion: () => state.info?.protocolVersion ?? null,
+    hasCapability: (key) => Boolean(state.info?.capabilities?.[key]),
+  }
+}
+
+// ─── Module-level singleton ───────────────────────────────────
+
+const defaultStore: ServerCapabilitiesStoreHandle = createServerCapabilitiesStore()
+
+/**
+ * Push the parsed MCP `initialize` response into the module-level singleton
+ * store. Pass `null` to clear (e.g. on disconnect / server change).
+ *
+ * @experimental
+ * @since v5.3.0
+ *
+ * @example
+ * // In your transport adapter, after receiving the initialize response :
+ * setServerCapabilities({
+ *   protocolVersion: response.result.protocolVersion,
+ *   serverInfo: response.result.serverInfo,
+ *   capabilities: response.result.capabilities,
+ *   instructions: response.result.instructions,
+ * })
+ */
+export function setServerCapabilities(info: ServerInitializeInfo | null): void {
+  defaultStore.set(info)
+}
+
+// ─── Context ──────────────────────────────────────────────────
+
+/**
+ * Context for a scoped server-capabilities store. Populated by
+ * `<ServerCapabilitiesProvider>`. Read by `useServerCapabilities()` with
+ * automatic fallback to the module-level singleton when absent.
+ *
+ * @experimental
+ * @since v5.3.0
+ */
+export const ServerCapabilitiesContext = createContext<ServerCapabilitiesStoreHandle | undefined>(
+  undefined
+)
+
+/**
+ * Provide a scoped `ServerCapabilitiesStoreHandle` to a SolidJS subtree.
+ * Children calling `useServerCapabilities()` bind to this store instead of
+ * the module singleton.
+ *
+ * If no `store` prop is passed, a fresh store is created for the provider's
+ * lifetime. Pass `store` explicitly when you need the handle outside the
+ * tree (e.g. in a transport adapter living at the app root).
+ *
+ * @experimental
+ * @since v5.3.0
+ */
+export const ServerCapabilitiesProvider: ParentComponent<{
+  store?: ServerCapabilitiesStoreHandle
+}> = (props): JSX.Element => {
+  const store = props.store ?? createServerCapabilitiesStore()
+  return (
+    <ServerCapabilitiesContext.Provider value={store}>
+      {props.children}
+    </ServerCapabilitiesContext.Provider>
+  )
+}
+
+// ─── Reactive hook ────────────────────────────────────────────
+
+/**
+ * Hook for components — reads the server capabilities reactively.
+ *
+ * If called inside a `<ServerCapabilitiesProvider>`, reads the scoped
+ * handle; otherwise falls back to the module singleton.
+ *
+ * @experimental
+ * @since v5.3.0
+ *
+ * @example
+ * const { capabilities, serverInfo, hasCapability } = useServerCapabilities()
+ *
+ * <Show when={capabilities()}>
+ *   <p>Connected to {serverInfo()?.name} v{serverInfo()?.version}</p>
+ *   <Show when={hasCapability('tools')}>
+ *     <ToolPalette />
+ *   </Show>
+ * </Show>
+ */
+export function useServerCapabilities(): {
+  info: () => ServerInitializeInfo | null
+  capabilities: () => ServerCapabilities | null
+  serverInfo: () => ServerInitializeInfo['serverInfo'] | null
+  protocolVersion: () => string | null
+  hasCapability: (key: keyof ServerCapabilities) => boolean
+} {
+  const scoped = useContext(ServerCapabilitiesContext)
+  const handle = scoped ?? defaultStore
+  return {
+    info: handle.info,
+    capabilities: handle.capabilities,
+    serverInfo: handle.serverInfo,
+    protocolVersion: handle.protocolVersion,
+    hasCapability: handle.hasCapability,
+  }
+}

package/src/types/chat-bus.ts

@@ -53,6 +53,7 @@ export interface ChatEvents {
   // --- Interactions ---
   onChatPromptResponse: (event: ChatEventBase & { response: ChatPromptResponse }) => void
   onClarificationNeeded: (event: ChatEventBase & { clarification: ClarificationEvent }) => void
+  onElicitation: (event: ChatEventBase & { elicitation: ElicitationEvent }) => void
 
   // --- Agentic (handled by app, not MCP-UI) ---
   onAgentSwitch: (event: ChatEventBase & { agent: AgentContext }) => void
@@ -568,6 +569,45 @@ export interface ToolCallEvent {
   duration_ms?: number
 }
 
+/**
+ * MCP `elicitation/create` request payload — server asks the client to
+ * collect input from the user according to a JSON Schema.
+ *
+ * Derived from MCP spec 2025-06-18. See
+ * `elicitationToPromptConfig()` in `services/chat-bus.ts` for the
+ * helper that converts this to a `ChatPromptConfig`.
+ *
+ * @experimental
+ * @since v5.2.0
+ */
+export interface ElicitationEvent {
+  /** Question / instruction to present to the user. */
+  message: string
+  /** JSON Schema describing the expected response shape. Object with primitive properties only. */
+  requestedSchema: ElicitationRequestedSchema
+}
+
+export interface ElicitationRequestedSchema {
+  type: 'object'
+  properties: Record<string, ElicitationPropertySchema>
+  required?: string[]
+}
+
+export interface ElicitationPropertySchema {
+  type: 'string' | 'number' | 'integer' | 'boolean'
+  title?: string
+  description?: string
+  /** Enum of allowed values (strings or numbers). */
+  enum?: Array<string | number>
+  /** Parallel array with display labels for each enum entry. */
+  enumNames?: string[]
+  default?: unknown
+  minimum?: number
+  maximum?: number
+  /** String format hint — date, date-time, email, uri. */
+  format?: 'date' | 'date-time' | 'email' | 'uri'
+}
+
 export interface ClarificationEvent {
   /** The question to ask the user */
   question: string