@assistant-ui/mcp-docs-server 0.2.3 → 0.3.0

package/.docs/raw/docs/runtimes/langgraph/agent-state.mdx

@@ -1,181 +0,0 @@
----
-title: Agent state
-description: Read and optimistically update graph state with useLangGraphState and useLangGraphSetState in LangGraph.
----
-
-`useLangGraphState` mirrors the graph's values object that LangGraph streams to the client. It updates live while the agent runs (when the `values` stream mode is enabled). `useLangGraphSetState` lets you apply optimistic local updates that ride the next send.
-
-## Enable the `values` stream mode
-
-<Callout type="warn">
-The default stream setup does **not** include the `values` stream mode. Without it, `useLangGraphState` never receives live graph state.
-</Callout>
-
-When you call `client.runs.stream` yourself, request `values` alongside the modes you already use:
-
-```ts
-client.runs.stream(threadId, assistantId, {
-  input,
-  streamMode: ["messages", "updates", "custom", "values"],
-});
-```
-
-If you use `unstable_createLangGraphStream`, its default stream modes do **not** include `values` either. Pass the option explicitly:
-
-```ts
-const stream = unstable_createLangGraphStream({
-  client,
-  assistantId: ASSISTANT_ID,
-  streamMode: ["messages", "updates", "custom", "values"],
-});
-```
-
-## Basic usage
-
-```tsx
-import {
-  useLangGraphState,
-  useLangGraphSetState,
-} from "@assistant-ui/react-langgraph";
-import { useAuiState } from "@assistant-ui/react";
-
-type GraphState = {
-  messages: unknown[];
-  filters: { region: string; maxResults: number };
-};
-
-const state = useLangGraphState<GraphState>();
-// state: GraphState | undefined  (latest agent state; updates live while the agent runs)
-
-const setState = useLangGraphSetState<GraphState>();
-// setState(next | (prev) => next)   (optimistic local update; sent with the NEXT run)
-
-const isRunning = useAuiState((s) => s.thread.isRunning);
-// isRunning: boolean                (whether the thread is currently running)
-```
-
-## Example
-
-Render graph state beside the chat and stage an optimistic filter update:
-
-```tsx
-"use client";
-
-import {
-  useLangGraphState,
-  useLangGraphSetState,
-} from "@assistant-ui/react-langgraph";
-import { useAuiState } from "@assistant-ui/react";
-import { Thread } from "@/components/assistant-ui/thread";
-
-type GraphState = {
-  filters: { region: string; maxResults: number };
-  lastQuery?: string;
-};
-
-export function CatalogAssistant() {
-  const state = useLangGraphState<GraphState>();
-  const setState = useLangGraphSetState<GraphState>();
-  const isRunning = useAuiState((s) => s.thread.isRunning);
-
-  return (
-    <div className="flex h-full">
-      <aside className="w-72 border-r p-4">
-        <h2>Graph state</h2>
-        {state ? (
-          <ul>
-            <li>Region: {state.filters.region}</li>
-            <li>Max results: {state.filters.maxResults}</li>
-            {state.lastQuery && <li>Last query: {state.lastQuery}</li>}
-          </ul>
-        ) : (
-          <p>No graph state yet. Ensure streamMode includes "values".</p>
-        )}
-        <button
-          type="button"
-          disabled={isRunning}
-          onClick={() =>
-            setState((prev) => ({
-              ...prev,
-              filters: {
-                region: "eu",
-                maxResults: prev?.filters.maxResults ?? 10,
-              },
-            }))
-          }
-        >
-          Prefer EU region
-        </button>
-        {isRunning && <p>Agent is running…</p>}
-      </aside>
-      <main className="flex-1">
-        <Thread />
-      </main>
-    </div>
-  );
-}
-```
-
-The panel tracks the latest `values` events from the graph. The button updates the local overlay immediately; that update object is merged into the run `input` on the next send so LangGraph applies it through the graph's state reducers and input schema.
-
-## How state is synced
-
-LangGraph state is the graph's values object. When `streamMode` includes `"values"`, each `values` event updates the client-side snapshot that `useLangGraphState` exposes.
-
-The setter from `useLangGraphSetState` overlays that snapshot locally. On the next send, the runtime merges the update object into the run `input`, so LangGraph reduces it through the graph's state reducers and input schema.
-
-If you supply a custom `stream` callback, the staged update is available as `config.state`. Forward it into your run input yourself:
-
-```ts
-const runtime = useLangGraphRuntime({
-  stream: async (messages, { initialize, ...config }) => {
-    const { externalId } = await initialize();
-    if (!externalId) throw new Error("Thread not found");
-
-    const client = createClient();
-    return client.runs.stream(externalId, ASSISTANT_ID, {
-      input: {
-        ...(config.state ?? {}),
-        messages,
-      },
-      streamMode: ["messages", "updates", "custom", "values"],
-    });
-  },
-});
-```
-
-The built-in path that uses the package helpers performs this merge for you. Custom `stream` callbacks must do it explicitly.
-
-## Write-back timing
-
-`useLangGraphSetState` is optimistic and local first. The value reaches the agent only when the next run starts. It is not a live channel into a run that is already in progress. Stage filters, preferences, or other graph fields that the next turn should apply through reducers; do not expect an in-flight run to observe mid-run setter calls.
-
-## Relationship to other state
-
-Keep the three state layers distinct:
-
-- **Your app state** stays yours (React state, URL, a store). assistant-ui does not own it.
-- **`useAuiState`** reads assistant-ui's client state (messages, composer, thread status).
-- **`useLangGraphState` / `useLangGraphSetState`** mirror state the **agent** (your LangGraph graph) owns, synced over the wire via `values` events.
-
-Use `useLangGraphState` and `useLangGraphSetState` for fields that live in the graph state schema. Use `useAuiState` for UI that depends on the chat thread itself. Use your own state for everything else.
-
-## Next
-
-<Cards>
-  <Card
-    title="Streaming"
-    description="Event handlers, message metadata, generative UI."
-    href="/docs/runtimes/langgraph/streaming"
-  />
-  <Card
-    title="Quickstart"
-    description="From-template and manual setup paths."
-    href="/docs/runtimes/langgraph/quickstart"
-  />
-  <Card
-    title="Generative UI"
-    description="Structured UI components emitted by your graph."
-    href="/docs/runtimes/langgraph/generative-ui"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/langgraph/generative-ui.mdx

@@ -1,305 +0,0 @@
----
-title: LangGraph Generative UI
-description: Render structured UI components emitted by LangGraph alongside assistant messages.
----
-
-LangGraph's [Generative UI](https://docs.langchain.com/langsmith/generative-ui-react) lets your graph emit structured UI components alongside assistant messages via `push_ui_message` (Python) or `typedUi().push()` (TypeScript). The assistant-ui adapter translates these into [`DataMessagePart`s](/docs/tools/tool-ui) on the associated assistant message, which you render with the existing `makeAssistantDataUI` API.
-
-## Enable the `custom` stream mode
-
-UI messages are emitted through LangGraph's `custom` stream channel. Make sure your `sendMessage` helper includes `"custom"` in `streamMode`:
-
-```ts
-streamMode: ["messages", "updates", "custom"];
-```
-
-If your graph accumulates UI messages in state under the `ui` key (the default for `typedUi`), `"values"` also works; the adapter reads both paths.
-
-## Custom state key
-
-If your graph uses a non-default `stateKey` with `typedUi(config, { stateKey: "my_ui" })` on the server, pass the matching `uiStateKey` option to `useLangGraphRuntime`:
-
-```ts
-const runtime = useLangGraphRuntime({
-  stream: async function* (messages, { initialize }) {
-    /* ... */
-  },
-  uiStateKey: "my_ui",
-});
-```
-
-This only affects the `values` stream path; the `custom` channel carries each UI event individually and does not rely on the state key.
-
-## Emit a UI message from your graph
-
-<Tabs items={["Python", "TypeScript"]}>
-<Tab value="Python">
-
-```python
-from langgraph.graph.ui import push_ui_message
-from langchain_core.messages import AIMessage
-
-async def chart_node(state, config):
-    message = AIMessage(id="msg-1", content="Here's your chart.")
-    push_ui_message(
-        "chart",
-        {"series": [1, 2, 3], "title": "Sales"},
-        message=message,  # Links the UI to this AI message
-    )
-    return {"messages": [message]}
-```
-
-</Tab>
-<Tab value="TypeScript">
-
-```ts
-import { typedUi } from "@langchain/langgraph-sdk/react-ui/server";
-import type { ComponentRegistry } from "./components";
-
-export async function chartNode(state, config) {
-  const ui = typedUi<ComponentRegistry>(config);
-  const message = { id: "msg-1", type: "ai", content: "Here's your chart." };
-  ui.push(
-    { name: "chart", props: { series: [1, 2, 3], title: "Sales" } },
-    { message },
-  );
-  return { messages: [message] };
-}
-```
-
-</Tab>
-</Tabs>
-
-Passing `message` (Python) or `{ message }` (TypeScript) is what links the UI component to a specific assistant message. The adapter reads `metadata.message_id` to attach the generated `DataMessagePart` to the correct message in the thread.
-
-## Register a renderer on the client
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="@/components/ChartUI.tsx"
-import { makeAssistantDataUI } from "@assistant-ui/react";
-
-type ChartProps = {
-  series: number[];
-  title: string;
-};
-
-export const ChartUI = makeAssistantDataUI<ChartProps>({
-  name: "chart",
-  render: ({ data }) => (
-    <div>
-      <h3>{data.title}</h3>
-      <Chart series={data.series} />
-    </div>
-  ),
-});
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="components/ChartUI.tsx"
-import { makeAssistantDataUI } from "@assistant-ui/react-native";
-import { Text, View } from "react-native";
-
-type ChartProps = {
-  series: number[];
-  title: string;
-};
-
-export const ChartUI = makeAssistantDataUI<ChartProps>({
-  name: "chart",
-  render: ({ data }) => (
-    <View>
-      <Text>{data.title}</Text>
-      <Chart series={data.series} />
-    </View>
-  ),
-});
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx title="components/chart-ui.tsx"
-import { makeAssistantDataUI } from "@assistant-ui/react-ink";
-import { Box, Text } from "ink";
-
-type ChartProps = {
-  series: number[];
-  title: string;
-};
-
-export const ChartUI = makeAssistantDataUI<ChartProps>({
-  name: "chart",
-  render: ({ data }) => (
-    <Box flexDirection="column">
-      <Text bold>{data.title}</Text>
-      <Chart series={data.series} />
-    </Box>
-  ),
-});
-```
-
-</Tab>
-</PlatformTabs>
-
-Mount the component once somewhere inside the `AssistantRuntimeProvider` tree. It renders nothing itself; it only registers the renderer:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="@/components/MyAssistant.tsx"
-<AssistantRuntimeProvider runtime={runtime}>
-  <ChartUI />
-  <Thread />
-</AssistantRuntimeProvider>
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="components/MyAssistant.tsx"
-import { View } from "react-native";
-import { Thread } from "@/components/assistant-ui/thread";
-
-<AssistantRuntimeProvider runtime={runtime}>
-  <ChartUI />
-  <View style={{ flex: 1 }}>
-    <Thread />
-  </View>
-</AssistantRuntimeProvider>;
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx title="components/my-assistant.tsx"
-import { Box } from "ink";
-import { Thread } from "./thread.js";
-
-<AssistantRuntimeProvider runtime={runtime}>
-  <ChartUI />
-  <Box flexDirection="column">
-    <Thread />
-  </Box>
-</AssistantRuntimeProvider>;
-```
-
-</Tab>
-</PlatformTabs>
-
-When a matching UI message arrives, the adapter appends a `{ type: "data", name: "chart", data: { series, title } }` part to the parent assistant message and the registered component renders inline.
-
-## Register renderers via `uiComponents`
-
-Instead of mounting separate `makeAssistantDataUI` components, register renderers directly on the runtime hook:
-
-```tsx
-const runtime = useLangGraphRuntime({
-  stream: async function* (messages, { initialize }) {
-    /* ... */
-  },
-  uiComponents: {
-    renderers: {
-      chart: ({ data }) => <Chart series={data.series} title={data.title} />,
-      table: ({ data }) => <DataTable rows={data.rows} />,
-    },
-  },
-});
-```
-
-Static `renderers` are matched by `ui_message` name. If no match is found, the part renders nothing unless a `fallback` is provided.
-
-## Dynamic loading with `fallback`
-
-LangSmith's [Generative UI](https://docs.langchain.com/langsmith/generative-ui-react) supports colocating UI code with your graph and loading it at runtime via `LoadExternalComponent`. The `fallback` option handles any `ui_message` name that has no static renderer:
-
-```tsx
-import { LoadExternalComponent } from "@langchain/langgraph-sdk/react-ui";
-
-const runtime = useLangGraphRuntime({
-  stream: async function* (messages, { initialize }) {
-    /* ... */
-  },
-  uiComponents: {
-    fallback: ({ name, data }) => (
-      <LoadExternalComponent name={name} props={data} />
-    ),
-    renderers: {
-      chart: ({ data }) => <Chart {...data} />,
-    },
-  },
-});
-```
-
-With this setup:
-
-- A `ui_message` with `name: "chart"` renders the static `Chart` component.
-- Any other name (e.g. `"dashboard"`, `"form"`) is handled by `fallback`, which fetches the component from LangSmith at runtime.
-
-`fallback` receives the same props as any data renderer: `name`, `data`, and part state metadata.
-
-## Semantics
-
-The adapter mirrors the reducer in `@langchain/langgraph-sdk/react-ui` exactly:
-
-- UI messages are keyed by their own `id`. Pushing the same id again **replaces** the existing entry.
-- Passing `metadata: { merge: true }` shallow-merges `props` onto the previous entry.
-- Emitting `{ type: "remove-ui", id }` (via `delete_ui_message` or `ui.delete(id)`) removes the entry.
-- UI messages without `metadata.message_id` are held in the runtime but not injected into any message; use `useLangGraphUIMessages()` to access the raw list if needed.
-
-## Restore persisted UI messages on thread switch
-
-If your graph persists UI messages in state via `typedUi`, return them from the `load` callback so they are restored when the user switches threads or refreshes the page:
-
-```tsx
-const runtime = useLangGraphRuntime({
-  stream: async function* (messages, { initialize }) {
-    /* ... */
-  },
-  load: async (externalId) => {
-    const state = await getThreadState(externalId);
-    return {
-      messages: state.values.messages,
-      uiMessages: state.values.ui,
-      interrupts: state.tasks[0]?.interrupts,
-    };
-  },
-});
-```
-
-Without this, each reload starts with an empty UI list even though the messages themselves are loaded.
-
-## Escape hatch: `useLangGraphUIMessages`
-
-```tsx
-import { useLangGraphUIMessages } from "@assistant-ui/react-langgraph";
-
-function Sidebar() {
-  const uiMessages = useLangGraphUIMessages();
-  // Filter, group, or render UI messages outside the thread
-  return <>{uiMessages.map(/* ... */)}</>;
-}
-```
-
-## Related
-
-<Cards>
-  <Card
-    title="Streaming"
-    description="Event handlers, message accumulator, conversion, metadata."
-    href="/docs/runtimes/langgraph/streaming"
-  />
-  <Card
-    title="Interrupts"
-    description="Interrupt persistence and checkpoint-based message editing."
-    href="/docs/runtimes/langgraph/interrupts"
-  />
-  <Card
-    title="Threads"
-    description="Basic thread support, AssistantCloud, custom thread list adapter."
-    href="/docs/runtimes/langgraph/threads"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/langgraph/interrupts.mdx

@@ -1,104 +0,0 @@
----
-title: Interrupts and message editing
-description: Interrupt persistence and checkpoint-based message editing.
----
-
-Both interrupt persistence and message editing rely on LangGraph's server-side checkpoints. Once you have one wired up, the other is mostly free.
-
-## Interrupt persistence
-
-LangGraph supports interrupting the execution flow to request user input or handle specific interactions. These interrupts can be persisted and restored when switching between threads:
-
-1. Make sure your thread state type includes the `interrupts` field.
-2. Return the interrupts from the `load` function along with the messages.
-3. The runtime automatically restores the interrupt state when switching threads.
-
-```ts
-const runtime = useLangGraphRuntime({
-  stream: async (messages, { initialize, ...config }) => {
-    /* ... */
-  },
-  load: async (externalId) => {
-    const state = await getThreadState(externalId);
-    return {
-      messages: state.values.messages,
-      interrupts: state.tasks[0]?.interrupts,
-    };
-  },
-});
-```
-
-This is particularly useful for applications that require user approval flows, multi-step forms, or other interactive elements that span multiple thread switches.
-
-## Message editing and regeneration
-
-LangGraph uses server-side checkpoints for state management. To support message editing (branching) and regeneration, provide a `getCheckpointId` callback that resolves the appropriate checkpoint for server-side forking.
-
-```ts
-const runtime = useLangGraphRuntime({
-  stream: async (messages, { initialize, ...config }) => {
-    const { externalId } = await initialize();
-    if (!externalId) throw new Error("Thread not found");
-    return sendMessage({ threadId: externalId, messages, config });
-  },
-  create: async () => {
-    const { thread_id } = await createThread();
-    return { externalId: thread_id };
-  },
-  load: async (externalId) => {
-    const state = await getThreadState(externalId);
-    return {
-      messages: state.values.messages,
-      interrupts: state.tasks[0]?.interrupts,
-    };
-  },
-  getCheckpointId: async (threadId, parentMessages) => {
-    const client = createClient();
-    const history = await client.threads.getHistory(threadId);
-    for (const state of history) {
-      const stateMessages = state.values.messages;
-      if (!stateMessages || stateMessages.length !== parentMessages.length) {
-        continue;
-      }
-      const hasStableIds =
-        parentMessages.every((m) => typeof m.id === "string") &&
-        stateMessages.every((m) => typeof m.id === "string");
-      if (!hasStableIds) continue;
-
-      const isMatch = parentMessages.every(
-        (m, i) => m.id === stateMessages[i]?.id,
-      );
-      if (isMatch) {
-        return state.checkpoint.checkpoint_id ?? null;
-      }
-    }
-    return null;
-  },
-});
-```
-
-When `getCheckpointId` is provided:
-
-- **Edit buttons** appear on user messages, allowing users to edit and resend from that point.
-- **Regenerate buttons** appear on assistant messages, allowing users to regenerate the response.
-
-The resolved `checkpointId` is passed to your `stream` callback via `config.checkpointId`. Your `sendMessage` helper should map it to the LangGraph SDK's `checkpoint_id` parameter (see [quickstart](/docs/runtimes/langgraph/quickstart) for the helper).
-
-<Callout type="info">
-Without `getCheckpointId`, edit and regenerate buttons will not appear. This is intentional; truncating client-side messages without forking from the correct server-side checkpoint would produce incorrect state.
-</Callout>
-
-## Next
-
-<Cards>
-  <Card
-    title="Threads"
-    description="Basic thread support, AssistantCloud, custom thread list adapter."
-    href="/docs/runtimes/langgraph/threads"
-  />
-  <Card
-    title="Streaming"
-    description="Event handlers, message metadata, generative UI."
-    href="/docs/runtimes/langgraph/streaming"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/langgraph/overview.mdx

@@ -1,84 +0,0 @@
----
-title: LangGraph UI Runtime
-description: Build a chat UI for LangGraph agents in React with assistant-ui — streaming, subgraph events, UI messages, interrupts, and end-to-end cancellation supported.
----
-
-`@assistant-ui/react-langgraph` integrates with [`@langchain/langgraph-sdk`](https://docs.langchain.com/oss/javascript/langgraph-sdk) directly, exposing the full LangGraph Cloud feature set in assistant-ui: streaming, subgraph events, UI messages, message metadata, interrupts, and end-to-end cancellation.
-
-<Callout type="info">
-**Migrating from LangServe?** LangChain has deprecated `RemoteRunnable` upstream and consolidated the chain and agent execution stories under LangGraph. Rebuild your chain as a LangGraph graph (LangChain's [LangServe → LangGraph migration guide](https://github.com/langchain-ai/langserve/blob/main/MIGRATION.md) covers the shape change), deploy via LangGraph Cloud or self-host LangGraph Studio, and use this runtime on the frontend. The runtime ships streaming, interrupts, generative UI, message metadata, and end-to-end cancellation out of the box.
-</Callout>
-
-## When to use it
-
-Pick the LangGraph runtime when:
-
-- You have (or want) a LangGraph Cloud server, locally via [LangGraph Studio](https://docs.langchain.com/langsmith/quick-start-studio) or hosted via [LangSmith](https://www.langchain.com/langsmith).
-- Your graph state has a `messages` key with LangChain-alike messages.
-- You want generative UI (`ui_message`), per-message metadata, subgraph events, or checkpoint-based message editing.
-
-<Callout type="info">
-If you are already using `@langchain/react`'s `useStream` hook, the alternative [`@assistant-ui/react-langchain`](/docs/runtimes/langchain) adapter may fit better. It delegates the stream plumbing to the upstream hook; the feature surface differs, see [LangChain useStream](/docs/runtimes/langchain) for the comparison table.
-</Callout>
-
-## Architecture
-
-`@assistant-ui/react-langgraph` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Graph state is the source of truth; the runtime renders messages from `state.values.messages` and submits user input back to the graph.
-
-Shared adapters (attachments, speech, feedback, history) work the same way described in [adapters](/docs/runtimes/concepts/adapters).
-
-## Requirements
-
-- A LangGraph Cloud API server.
-- React 18 or 19.
-- The graph state must include a `messages` key with LangChain-alike messages.
-
-## Install
-
-<PlatformTabs>
-<Tab value="React">
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk"]} />
-
-</Tab>
-<Tab value="React Native">
-
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk"]} />
-
-</Tab>
-<Tab value="React Ink">
-
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk", "ink", "react"]} />
-
-</Tab>
-</PlatformTabs>
-
-## Next
-
-<Cards>
-  <Card
-    title="Quickstart"
-    description="From-template and manual setup paths to a working LangGraph chat."
-    href="/docs/runtimes/langgraph/quickstart"
-  />
-  <Card
-    title="Streaming"
-    description="Event handlers, message metadata, generative UI."
-    href="/docs/runtimes/langgraph/streaming"
-  />
-  <Card
-    title="Interrupts"
-    description="Interrupt persistence and checkpoint-based message editing."
-    href="/docs/runtimes/langgraph/interrupts"
-  />
-  <Card
-    title="Threads"
-    description="Basic thread support, AssistantCloud, custom thread list adapter."
-    href="/docs/runtimes/langgraph/threads"
-  />
-  <Card
-    title="Tutorial: Stockbroker"
-    description="End-to-end stockbroker assistant with generative UI and approval flows."
-    href="/docs/runtimes/langgraph/tutorial/introduction"
-  />
-</Cards>