@assistant-ui/mcp-docs-server 0.1.30 → 0.1.31

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

@@ -0,0 +1,496 @@
+---
+title: Quickstart
+description: From-template and manual setup paths to a working LangGraph chat.
+---
+
+Two paths to a running chat against a LangGraph Cloud server. The template is fastest; the manual path is what you adapt when integrating into an existing project.
+
+## From the template
+
+<PlatformTabs>
+<Tab value="React">
+
+```sh
+npx create-assistant-ui@latest -t langgraph my-app
+cd my-app
+```
+
+Set environment variables:
+
+```sh title=".env.local"
+# LANGCHAIN_API_KEY=your_api_key       # production
+# LANGGRAPH_API_URL=your_api_url       # production
+NEXT_PUBLIC_LANGGRAPH_API_URL=your_api_url           # development (no API key required)
+NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
+```
+
+```sh
+npm run dev
+```
+
+Skip ahead to [streaming](/docs/runtimes/langgraph/streaming) to start adding features.
+
+</Tab>
+<Tab value="React Native">
+
+There is not a React Native LangGraph template yet. Use the manual setup below in an Expo app.
+
+</Tab>
+<Tab value="React Ink">
+
+There is not an Ink LangGraph template yet. Use the manual setup below in a Node/Ink app.
+
+</Tab>
+</PlatformTabs>
+
+## Manual setup in an existing project
+
+<Steps>
+<Step>
+
+### Install dependencies
+
+<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>
+
+</Step>
+<Step>
+
+### Create the LangGraph client helper
+
+<PlatformTabs>
+<Tab value="React">
+
+```ts title="@/lib/chatApi.ts"
+import { Client } from "@langchain/langgraph-sdk";
+
+export const createClient = () => {
+  const apiUrl =
+    process.env["NEXT_PUBLIC_LANGGRAPH_API_URL"] ||
+    (typeof window !== "undefined"
+      ? new URL("/api", window.location.href).href
+      : "/api");
+  return new Client({ apiUrl });
+};
+```
+
+</Tab>
+<Tab value="React Native">
+
+```ts title="lib/chatApi.ts"
+import { Client } from "@langchain/langgraph-sdk";
+
+export const createClient = () => {
+  const apiUrl =
+    process.env.EXPO_PUBLIC_LANGGRAPH_API_URL ?? "http://localhost:2024";
+  return new Client({ apiUrl });
+};
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```ts title="lib/chatApi.ts"
+import { Client } from "@langchain/langgraph-sdk";
+
+export const createClient = () => {
+  const apiUrl = process.env.LANGGRAPH_API_URL ?? "http://localhost:2024";
+  return new Client({ apiUrl });
+};
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Build the assistant component
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="@/components/MyAssistant.tsx"
+"use client";
+
+import { useMemo } from "react";
+import { Thread } from "@/components/assistant-ui/thread";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import {
+  unstable_createLangGraphStream,
+  useLangGraphRuntime,
+  type LangChainMessage,
+} from "@assistant-ui/react-langgraph";
+
+import { createClient } from "@/lib/chatApi";
+
+const ASSISTANT_ID = process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!;
+
+export function MyAssistant() {
+  const client = useMemo(() => createClient(), []);
+  const stream = useMemo(
+    () =>
+      unstable_createLangGraphStream({
+        client,
+        assistantId: ASSISTANT_ID,
+      }),
+    [client],
+  );
+
+  const runtime = useLangGraphRuntime({
+    unstable_allowCancellation: true,
+    stream,
+    create: async () => {
+      const { thread_id } = await client.threads.create();
+      return { externalId: thread_id };
+    },
+    load: async (externalId) => {
+      const state = await client.threads.getState<{
+        messages: LangChainMessage[];
+      }>(externalId);
+      return {
+        messages: state.values.messages,
+        interrupts: state.tasks[0]?.interrupts,
+      };
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="components/MyAssistant.tsx"
+import { useMemo } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
+import {
+  unstable_createLangGraphStream,
+  useLangGraphRuntime,
+  type LangChainMessage,
+} from "@assistant-ui/react-langgraph";
+import { Thread } from "@/components/assistant-ui/thread";
+
+import { createClient } from "@/lib/chatApi";
+
+const ASSISTANT_ID = process.env.EXPO_PUBLIC_LANGGRAPH_ASSISTANT_ID!;
+
+export function MyAssistant() {
+  const client = useMemo(() => createClient(), []);
+  const stream = useMemo(
+    () =>
+      unstable_createLangGraphStream({
+        client,
+        assistantId: ASSISTANT_ID,
+      }),
+    [client],
+  );
+
+  const runtime = useLangGraphRuntime({
+    unstable_allowCancellation: true,
+    stream,
+    create: async () => {
+      const { thread_id } = await client.threads.create();
+      return { externalId: thread_id };
+    },
+    load: async (externalId) => {
+      const state = await client.threads.getState<{
+        messages: LangChainMessage[];
+      }>(externalId);
+      return {
+        messages: state.values.messages,
+        interrupts: state.tasks[0]?.interrupts,
+      };
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="components/MyAssistant.tsx"
+import { useMemo } from "react";
+import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
+import {
+  unstable_createLangGraphStream,
+  useLangGraphRuntime,
+  type LangChainMessage,
+} from "@assistant-ui/react-langgraph";
+import { Thread } from "./thread.js";
+
+import { createClient } from "../lib/chatApi.js";
+
+const ASSISTANT_ID = process.env.LANGGRAPH_ASSISTANT_ID!;
+
+export function MyAssistant() {
+  const client = useMemo(() => createClient(), []);
+  const stream = useMemo(
+    () =>
+      unstable_createLangGraphStream({
+        client,
+        assistantId: ASSISTANT_ID,
+      }),
+    [client],
+  );
+
+  const runtime = useLangGraphRuntime({
+    unstable_allowCancellation: true,
+    stream,
+    create: async () => {
+      const { thread_id } = await client.threads.create();
+      return { externalId: thread_id };
+    },
+    load: async (externalId) => {
+      const state = await client.threads.getState<{
+        messages: LangChainMessage[];
+      }>(externalId);
+      return {
+        messages: state.values.messages,
+        interrupts: state.tasks[0]?.interrupts,
+      };
+    },
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Mount the component
+
+<PlatformTabs>
+<Tab value="React">
+
+```tsx title="@/app/page.tsx"
+import { MyAssistant } from "@/components/MyAssistant";
+
+export default function Home() {
+  return (
+    <main className="h-dvh">
+      <MyAssistant />
+    </main>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Native">
+
+```tsx title="app/index.tsx"
+import { View } from "react-native";
+import { MyAssistant } from "@/components/MyAssistant";
+
+export default function Home() {
+  return (
+    <View style={{ flex: 1 }}>
+      <MyAssistant />
+    </View>
+  );
+}
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```tsx title="app.tsx"
+import { Box } from "ink";
+import { MyAssistant } from "./components/MyAssistant.js";
+
+export function App() {
+  return (
+    <Box flexDirection="column">
+      <MyAssistant />
+    </Box>
+  );
+}
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Set environment variables
+
+<PlatformTabs>
+<Tab value="React">
+
+Use the same `.env.local` shape as the template path [above](#from-the-template).
+
+</Tab>
+<Tab value="React Native">
+
+```sh title=".env"
+EXPO_PUBLIC_LANGGRAPH_API_URL=http://localhost:2024
+EXPO_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
+```
+
+</Tab>
+<Tab value="React Ink">
+
+```sh title=".env"
+LANGGRAPH_API_URL=http://localhost:2024
+LANGGRAPH_ASSISTANT_ID=your_graph_id
+```
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+<Step>
+
+### Set up UI components
+
+<PlatformTabs>
+<Tab value="React">
+
+Follow the [UI Components guide](/docs/ui/thread) to wire up the Thread, composer, and supporting primitives.
+
+</Tab>
+<Tab value="React Native">
+
+Follow the [React Native setup](/docs/react-native) to add a native Thread, composer, and supporting primitives.
+
+</Tab>
+<Tab value="React Ink">
+
+Follow the [Ink setup](/docs/ink) to add a terminal Thread, composer, and supporting primitives.
+
+</Tab>
+</PlatformTabs>
+
+</Step>
+</Steps>
+
+## Production proxy backend
+
+For development, the client above hits LangGraph Cloud directly using `NEXT_PUBLIC_LANGGRAPH_API_URL`. For production, proxy through your own backend so your API key never reaches the client. Limit the proxy to the endpoints you actually need.
+
+```ts title="@/app/api/[...path]/route.ts"
+import { NextRequest, NextResponse } from "next/server";
+
+export const runtime = "edge";
+
+function getCorsHeaders() {
+  return {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Allow-Methods": "GET, POST, PUT, PATCH, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "*",
+  };
+}
+
+async function handleRequest(req: NextRequest, method: string) {
+  try {
+    const path = req.nextUrl.pathname.replace(/^\/?api\//, "");
+    const url = new URL(req.url);
+    const searchParams = new URLSearchParams(url.search);
+    searchParams.delete("_path");
+    searchParams.delete("nxtP_path");
+    const queryString = searchParams.toString()
+      ? `?${searchParams.toString()}`
+      : "";
+
+    const options: RequestInit = {
+      method,
+      headers: { "x-api-key": process.env["LANGCHAIN_API_KEY"] ?? "" },
+      signal: req.signal,
+    };
+    if (["POST", "PUT", "PATCH"].includes(method)) {
+      options.body = await req.text();
+    }
+
+    const res = await fetch(
+      `${process.env["LANGGRAPH_API_URL"]}/${path}${queryString}`,
+      options,
+    );
+    const headers = new Headers(res.headers);
+    headers.delete("content-encoding");
+    headers.delete("content-length");
+    headers.delete("transfer-encoding");
+    for (const [key, value] of Object.entries(getCorsHeaders())) {
+      headers.set(key, value);
+    }
+    return new NextResponse(res.body, {
+      status: res.status,
+      statusText: res.statusText,
+      headers,
+    });
+  } catch (e: unknown) {
+    if (e instanceof Error) {
+      const typedError = e as Error & { status?: number };
+      return NextResponse.json(
+        { error: typedError.message },
+        { status: typedError.status ?? 500 },
+      );
+    }
+    return NextResponse.json({ error: "Unknown error" }, { status: 500 });
+  }
+}
+
+export const GET = (req: NextRequest) => handleRequest(req, "GET");
+export const POST = (req: NextRequest) => handleRequest(req, "POST");
+export const PUT = (req: NextRequest) => handleRequest(req, "PUT");
+export const PATCH = (req: NextRequest) => handleRequest(req, "PATCH");
+export const DELETE = (req: NextRequest) => handleRequest(req, "DELETE");
+export const OPTIONS = () =>
+  new NextResponse(null, { status: 204, headers: getCorsHeaders() });
+```
+
+With this route in place, drop `NEXT_PUBLIC_LANGGRAPH_API_URL` from production env vars; the client helper falls back to the same-origin `/api` path. Set `LANGCHAIN_API_KEY` and `LANGGRAPH_API_URL` server-side instead.
+
+## Next
+
+<Cards>
+  <Card
+    title="Streaming"
+    description="Event handlers, message metadata, message conversion."
+    href="/docs/runtimes/langgraph/streaming"
+  />
+  <Card
+    title="Generative UI"
+    description="Structured UI components emitted by your graph."
+    href="/docs/runtimes/langgraph/generative-ui"
+  />
+  <Card
+    title="Interrupts"
+    description="Interrupt persistence and checkpoint-based message editing."
+    href="/docs/runtimes/langgraph/interrupts"
+  />
+</Cards>

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

@@ -0,0 +1,127 @@
+---
+title: Streaming
+description: Event handlers, message accumulator, conversion, metadata, and generative UI.
+---
+
+LangGraph emits a rich stream of events: top-level message chunks, subgraph events, custom UI messages, errors, and metadata. This page documents how to observe and react to each.
+
+## Message accumulator
+
+`LangGraphMessageAccumulator` lets you append messages incoming from the server to replicate the messages state client-side.
+
+```ts
+import {
+  LangGraphMessageAccumulator,
+  appendLangChainChunk,
+} from "@assistant-ui/react-langgraph";
+
+const accumulator = new LangGraphMessageAccumulator({
+  appendMessage: appendLangChainChunk,
+});
+
+if (event.event === "messages/partial") {
+  accumulator.addMessages(event.data);
+}
+```
+
+## Message conversion
+
+`convertLangChainMessages` transforms LangChain messages to assistant-ui's format. Use it when bridging into a custom adapter or rendering messages outside the runtime.
+
+```ts
+import { convertLangChainMessages } from "@assistant-ui/react-langgraph";
+
+const threadMessage = convertLangChainMessages(langChainMessage);
+```
+
+## Event handlers
+
+Listen to streaming events by passing `eventHandlers` to `useLangGraphRuntime`:
+
+```ts
+const runtime = useLangGraphRuntime({
+  stream: async (messages, { initialize, ...config }) => {
+    /* ... */
+  },
+  eventHandlers: {
+    onMessageChunk: (chunk, metadata) => {
+      // Fired for each chunk in messages-tuple mode.
+      // metadata contains langgraph_step, langgraph_node, ls_model_name, etc.
+      // For pipe-namespaced events emitted by subgraphs (e.g. messages|tools:call_abc),
+      // metadata.namespace holds the suffix ("tools:call_abc"). Use it to attribute
+      // a chunk to a specific subgraph.
+    },
+    onValues: (values) => {
+      // Fired when a top-level values event is received.
+      // Subgraph values events are routed to onSubgraphValues instead.
+    },
+    onUpdates: (updates) => {
+      // Fired when a top-level updates event is received.
+      // Subgraph updates events are routed to onSubgraphUpdates instead.
+    },
+    onSubgraphValues: (namespace, values) => {
+      // Fired when a subgraph values|<namespace> event is received
+      // (e.g. namespace === "tools:call_abc").
+    },
+    onSubgraphUpdates: (namespace, updates) => {
+      // Fired when a subgraph updates|<namespace> event is received.
+    },
+    onMetadata: (metadata) => {
+      /* thread metadata */
+    },
+    onInfo: (info) => {
+      /* informational messages */
+    },
+    onError: (error) => {
+      // Fired for both top-level and subgraph errors.
+    },
+    onSubgraphError: (namespace, error) => {
+      // Additionally fired for subgraph errors with the namespace.
+      // Use this to attribute a subgraph failure to its source without marking
+      // the parent message as incomplete (that only happens for top-level errors).
+    },
+    onCustomEvent: (type, data) => {
+      /* custom events */
+    },
+  },
+});
+```
+
+## Message metadata
+
+When using `streamMode: "messages-tuple"`, each chunk includes metadata from the LangGraph server. Access accumulated metadata per message with `useLangGraphMessageMetadata`:
+
+```ts
+import { useLangGraphMessageMetadata } from "@assistant-ui/react-langgraph";
+
+function MyComponent() {
+  const metadata = useLangGraphMessageMetadata();
+  // Map<string, LangGraphTupleMetadata> keyed by message ID
+}
+```
+
+## Generative UI
+
+LangGraph can 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/guides/tool-ui) on the associated assistant message, which you render with the existing `makeAssistantDataUI` API.
+
+See [Generative UI](/docs/runtimes/langgraph/generative-ui) for full setup: enabling the `custom` stream channel, emitting UI messages, registering renderers, dynamic loading, and persisting UI state across thread switches.
+
+## Next
+
+<Cards>
+  <Card
+    title="Generative UI"
+    description="Structured UI components emitted by your graph."
+    href="/docs/runtimes/langgraph/generative-ui"
+  />
+  <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>