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

package/dist/stores/server-capabilities-store.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 { type ParentComponent } from 'solid-js';
+/**
+ * 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;
+}
+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;
+}
+/**
+ * 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 declare function createServerCapabilitiesStore(): ServerCapabilitiesStoreHandle;
+/**
+ * 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 declare function setServerCapabilities(info: ServerInitializeInfo | null): void;
+/**
+ * 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 declare const ServerCapabilitiesContext: import("solid-js").Context<ServerCapabilitiesStoreHandle | 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 declare const ServerCapabilitiesProvider: ParentComponent<{
+    store?: ServerCapabilitiesStoreHandle;
+}>;
+/**
+ * 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 declare function useServerCapabilities(): {
+    info: () => ServerInitializeInfo | null;
+    capabilities: () => ServerCapabilities | null;
+    serverInfo: () => ServerInitializeInfo['serverInfo'] | null;
+    protocolVersion: () => string | null;
+    hasCapability: (key: keyof ServerCapabilities) => boolean;
+};
+//# sourceMappingURL=server-capabilities-store.d.ts.map

package/dist/stores/server-capabilities-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-capabilities-store.d.ts","sourceRoot":"","sources":["../../src/stores/server-capabilities-store.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAA6B,KAAK,eAAe,EAAY,MAAM,UAAU,CAAA;AAKpF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC/B,KAAK,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IACjC,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IACnC,SAAS,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAA;IACrF,YAAY,EAAE,kBAAkB,CAAA;IAChC,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAID,MAAM,WAAW,6BAA6B;IAC5C,+EAA+E;IAC/E,GAAG,EAAE,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,KAAK,IAAI,CAAA;IAChD,8EAA8E;IAC9E,IAAI,EAAE,MAAM,oBAAoB,GAAG,IAAI,CAAA;IACvC,2DAA2D;IAC3D,YAAY,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAA;IAC7C,yDAAyD;IACzD,UAAU,EAAE,MAAM,oBAAoB,CAAC,YAAY,CAAC,GAAG,IAAI,CAAA;IAC3D,yDAAyD;IACzD,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACpC;;;OAGG;IACH,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,kBAAkB,KAAK,OAAO,CAAA;CAC1D;AAID;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,IAAI,6BAA6B,CAW7E;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,GAAG,IAAI,CAE7E;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,uEAErC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B,EAAE,eAAe,CAAC;IACvD,KAAK,CAAC,EAAE,6BAA6B,CAAA;CACtC,CAOA,CAAA;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,IAAI;IACvC,IAAI,EAAE,MAAM,oBAAoB,GAAG,IAAI,CAAA;IACvC,YAAY,EAAE,MAAM,kBAAkB,GAAG,IAAI,CAAA;IAC7C,UAAU,EAAE,MAAM,oBAAoB,CAAC,YAAY,CAAC,GAAG,IAAI,CAAA;IAC3D,eAAe,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACpC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,kBAAkB,KAAK,OAAO,CAAA;CAC1D,CAUA"}

package/dist/stores/server-capabilities-store.js

@@ -0,0 +1,61 @@
+import { createComponent } from "solid-js/web";
+import { createContext, useContext } from "solid-js";
+import { createStore } from "solid-js/store";
+function createServerCapabilitiesStore() {
+  const [state, setState] = createStore({
+    info: null
+  });
+  return {
+    set: (info) => setState("info", info),
+    info: () => state.info,
+    capabilities: () => {
+      var _a;
+      return ((_a = state.info) == null ? void 0 : _a.capabilities) ?? null;
+    },
+    serverInfo: () => {
+      var _a;
+      return ((_a = state.info) == null ? void 0 : _a.serverInfo) ?? null;
+    },
+    protocolVersion: () => {
+      var _a;
+      return ((_a = state.info) == null ? void 0 : _a.protocolVersion) ?? null;
+    },
+    hasCapability: (key) => {
+      var _a, _b;
+      return Boolean((_b = (_a = state.info) == null ? void 0 : _a.capabilities) == null ? void 0 : _b[key]);
+    }
+  };
+}
+const defaultStore = createServerCapabilitiesStore();
+function setServerCapabilities(info) {
+  defaultStore.set(info);
+}
+const ServerCapabilitiesContext = createContext(void 0);
+const ServerCapabilitiesProvider = (props) => {
+  const store = props.store ?? createServerCapabilitiesStore();
+  return createComponent(ServerCapabilitiesContext.Provider, {
+    value: store,
+    get children() {
+      return props.children;
+    }
+  });
+};
+function useServerCapabilities() {
+  const scoped = useContext(ServerCapabilitiesContext);
+  const handle = scoped ?? defaultStore;
+  return {
+    info: handle.info,
+    capabilities: handle.capabilities,
+    serverInfo: handle.serverInfo,
+    protocolVersion: handle.protocolVersion,
+    hasCapability: handle.hasCapability
+  };
+}
+export {
+  ServerCapabilitiesContext,
+  ServerCapabilitiesProvider,
+  createServerCapabilitiesStore,
+  setServerCapabilities,
+  useServerCapabilities
+};
+//# sourceMappingURL=server-capabilities-store.js.map

package/dist/stores/server-capabilities-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-capabilities-store.js","sources":["../../src/stores/server-capabilities-store.tsx"],"sourcesContent":["/**\n * Server Capabilities Store — reactive snapshot of the MCP `initialize`\n * response echoed by the server.\n *\n * @experimental\n * @since v5.3.0\n *\n * mcp-ui doesn't speak MCP protocol directly — the consumer's transport\n * layer (stdio child process, HTTP/SSE client, ...) parses the\n * `initialize` JSON-RPC response and pushes the relevant fields into this\n * store via `setServerCapabilities(info)`. Components then read\n * reactively via `useServerCapabilities()` to gate behavior :\n *\n * ```tsx\n * const { capabilities } = useServerCapabilities()\n * <Show when={capabilities()?.tools?.listChanged}>\n *   <ToolListSubscriber />\n * </Show>\n * ```\n *\n * ## Two consumption modes (mirrors `scratchpad-store`)\n *\n * 1. **Singleton mode (default)** — `setServerCapabilities(info)` mutates\n *    the module-level singleton. `useServerCapabilities()` reads from it.\n *    Use for single-MCP-server consumers (the common case).\n *\n * 2. **Multi-instance mode** — wrap a subtree in\n *    `<ServerCapabilitiesProvider>` to scope a separate handle. Pass\n *    `store={createServerCapabilitiesStore()}` explicitly when you need to\n *    drive it from a non-reactive scope (e.g. a transport adapter living\n *    at the app root).\n *\n * ## Note on `elicitation`\n *\n * Per MCP spec 2025-06-18, `elicitation` is a **CLIENT** capability, not\n * a server one. Servers do not declare it. If you need to gate\n * `<ElicitationForm>` rendering on whether the connected client *itself*\n * supports elicitation — that's a separate concern (your own state, set\n * by your transport layer based on its own configuration).\n */\n\nimport { createContext, useContext, type ParentComponent, type JSX } from 'solid-js'\nimport { createStore } from 'solid-js/store'\n\n// ─── Types ────────────────────────────────────────────────────\n\n/**\n * Server capabilities object as advertised in the MCP `initialize` response.\n * Mirrors the spec 2025-06-18 `ServerCapabilities` shape with permissive\n * `experimental` for forward compatibility.\n */\nexport interface ServerCapabilities {\n  experimental?: Record<string, unknown>\n  logging?: Record<string, never>\n  tools?: { listChanged?: boolean }\n  prompts?: { listChanged?: boolean }\n  resources?: { listChanged?: boolean; subscribe?: boolean }\n  completions?: Record<string, never>\n}\n\n/**\n * Subset of the MCP `initialize` response relevant to the UI layer.\n * Consumers may extend this via the `experimental` field.\n */\nexport interface ServerInitializeInfo {\n  protocolVersion: string\n  serverInfo: { name: string; version: string; title?: string; [key: string]: unknown }\n  capabilities: ServerCapabilities\n  instructions?: string\n}\n\n// ─── Handle ───────────────────────────────────────────────────\n\nexport interface ServerCapabilitiesStoreHandle {\n  /** Push a fresh `initialize` snapshot into the store, or clear with `null`. */\n  set: (info: ServerInitializeInfo | null) => void\n  /** Reactive accessor for the full info (null when no initialize received). */\n  info: () => ServerInitializeInfo | null\n  /** Reactive accessor for just the `capabilities` field. */\n  capabilities: () => ServerCapabilities | null\n  /** Reactive accessor for just the `serverInfo` field. */\n  serverInfo: () => ServerInitializeInfo['serverInfo'] | null\n  /** Reactive accessor for the protocol version string. */\n  protocolVersion: () => string | null\n  /**\n   * Helper : returns true if the server advertised the named capability key\n   * with a truthy value (i.e. the key is present, even as an empty object).\n   */\n  hasCapability: (key: keyof ServerCapabilities) => boolean\n}\n\n// ─── Factory ──────────────────────────────────────────────────\n\n/**\n * Create an isolated server-capabilities store instance.\n *\n * Use this when you need to track multiple MCP servers in parallel (rare),\n * or to drive the store from a non-reactive transport adapter. Pair with\n * `<ServerCapabilitiesProvider store={...}>` to scope a SolidJS subtree.\n *\n * @experimental\n * @since v5.3.0\n */\nexport function createServerCapabilitiesStore(): ServerCapabilitiesStoreHandle {\n  const [state, setState] = createStore<{ info: ServerInitializeInfo | null }>({ info: null })\n\n  return {\n    set: (info) => setState('info', info),\n    info: () => state.info,\n    capabilities: () => state.info?.capabilities ?? null,\n    serverInfo: () => state.info?.serverInfo ?? null,\n    protocolVersion: () => state.info?.protocolVersion ?? null,\n    hasCapability: (key) => Boolean(state.info?.capabilities?.[key]),\n  }\n}\n\n// ─── Module-level singleton ───────────────────────────────────\n\nconst defaultStore: ServerCapabilitiesStoreHandle = createServerCapabilitiesStore()\n\n/**\n * Push the parsed MCP `initialize` response into the module-level singleton\n * store. Pass `null` to clear (e.g. on disconnect / server change).\n *\n * @experimental\n * @since v5.3.0\n *\n * @example\n * // In your transport adapter, after receiving the initialize response :\n * setServerCapabilities({\n *   protocolVersion: response.result.protocolVersion,\n *   serverInfo: response.result.serverInfo,\n *   capabilities: response.result.capabilities,\n *   instructions: response.result.instructions,\n * })\n */\nexport function setServerCapabilities(info: ServerInitializeInfo | null): void {\n  defaultStore.set(info)\n}\n\n// ─── Context ──────────────────────────────────────────────────\n\n/**\n * Context for a scoped server-capabilities store. Populated by\n * `<ServerCapabilitiesProvider>`. Read by `useServerCapabilities()` with\n * automatic fallback to the module-level singleton when absent.\n *\n * @experimental\n * @since v5.3.0\n */\nexport const ServerCapabilitiesContext = createContext<ServerCapabilitiesStoreHandle | undefined>(\n  undefined\n)\n\n/**\n * Provide a scoped `ServerCapabilitiesStoreHandle` to a SolidJS subtree.\n * Children calling `useServerCapabilities()` bind to this store instead of\n * the module singleton.\n *\n * If no `store` prop is passed, a fresh store is created for the provider's\n * lifetime. Pass `store` explicitly when you need the handle outside the\n * tree (e.g. in a transport adapter living at the app root).\n *\n * @experimental\n * @since v5.3.0\n */\nexport const ServerCapabilitiesProvider: ParentComponent<{\n  store?: ServerCapabilitiesStoreHandle\n}> = (props): JSX.Element => {\n  const store = props.store ?? createServerCapabilitiesStore()\n  return (\n    <ServerCapabilitiesContext.Provider value={store}>\n      {props.children}\n    </ServerCapabilitiesContext.Provider>\n  )\n}\n\n// ─── Reactive hook ────────────────────────────────────────────\n\n/**\n * Hook for components — reads the server capabilities reactively.\n *\n * If called inside a `<ServerCapabilitiesProvider>`, reads the scoped\n * handle; otherwise falls back to the module singleton.\n *\n * @experimental\n * @since v5.3.0\n *\n * @example\n * const { capabilities, serverInfo, hasCapability } = useServerCapabilities()\n *\n * <Show when={capabilities()}>\n *   <p>Connected to {serverInfo()?.name} v{serverInfo()?.version}</p>\n *   <Show when={hasCapability('tools')}>\n *     <ToolPalette />\n *   </Show>\n * </Show>\n */\nexport function useServerCapabilities(): {\n  info: () => ServerInitializeInfo | null\n  capabilities: () => ServerCapabilities | null\n  serverInfo: () => ServerInitializeInfo['serverInfo'] | null\n  protocolVersion: () => string | null\n  hasCapability: (key: keyof ServerCapabilities) => boolean\n} {\n  const scoped = useContext(ServerCapabilitiesContext)\n  const handle = scoped ?? defaultStore\n  return {\n    info: handle.info,\n    capabilities: handle.capabilities,\n    serverInfo: handle.serverInfo,\n    protocolVersion: handle.protocolVersion,\n    hasCapability: handle.hasCapability,\n  }\n}\n"],"names":["createServerCapabilitiesStore","state","setState","createStore","info","set","capabilities","serverInfo","protocolVersion","hasCapability","key","Boolean","defaultStore","setServerCapabilities","ServerCapabilitiesContext","createContext","undefined","ServerCapabilitiesProvider","props","store","_$createComponent","Provider","value","children","useServerCapabilities","scoped","useContext","handle"],"mappings":";;;AAuGO,SAASA,gCAA+D;AAC7E,QAAM,CAACC,OAAOC,QAAQ,IAAIC,YAAmD;AAAA,IAAEC,MAAM;AAAA,EAAA,CAAM;AAE3F,SAAO;AAAA,IACLC,KAAMD,CAAAA,SAASF,SAAS,QAAQE,IAAI;AAAA,IACpCA,MAAMA,MAAMH,MAAMG;AAAAA,IAClBE,cAAcA,MAAAA;;AAAML,0BAAMG,SAANH,mBAAYK,iBAAgB;AAAA;AAAA,IAChDC,YAAYA,MAAAA;;AAAMN,0BAAMG,SAANH,mBAAYM,eAAc;AAAA;AAAA,IAC5CC,iBAAiBA,MAAAA;;AAAMP,0BAAMG,SAANH,mBAAYO,oBAAmB;AAAA;AAAA,IACtDC,eAAgBC,CAAAA;;AAAQC,sBAAQV,iBAAMG,SAANH,mBAAYK,iBAAZL,mBAA2BS,IAAI;AAAA;AAAA,EAAA;AAEnE;AAIA,MAAME,eAA8CZ,8BAAAA;AAkB7C,SAASa,sBAAsBT,MAAyC;AAC7EQ,eAAaP,IAAID,IAAI;AACvB;AAYO,MAAMU,4BAA4BC,cACvCC,MACF;AAcO,MAAMC,6BAERA,CAACC,UAAuB;AAC3B,QAAMC,QAAQD,MAAMC,SAASnB,8BAAAA;AAC7B,SAAAoB,gBACGN,0BAA0BO,UAAQ;AAAA,IAACC,OAAOH;AAAAA,IAAK,IAAAI,WAAA;AAAA,aAC7CL,MAAMK;AAAAA,IAAQ;AAAA,EAAA,CAAA;AAGrB;AAuBO,SAASC,wBAMd;AACA,QAAMC,SAASC,WAAWZ,yBAAyB;AACnD,QAAMa,SAASF,UAAUb;AACzB,SAAO;AAAA,IACLR,MAAMuB,OAAOvB;AAAAA,IACbE,cAAcqB,OAAOrB;AAAAA,IACrBC,YAAYoB,OAAOpB;AAAAA,IACnBC,iBAAiBmB,OAAOnB;AAAAA,IACxBC,eAAekB,OAAOlB;AAAAA,EAAAA;AAE1B;"}

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.0",
   "description": "SolidJS components for rendering MCP-generated UI resources",
   "type": "module",
   "main": "./dist/index.cjs",