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

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

@@ -1,496 +0,0 @@
----
-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 langchain 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

@@ -1,144 +0,0 @@
----
-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/tools/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.
-
-## Queueing messages during a run
-
-Set `unstable_enableMessageQueue` to keep the composer usable while a run is streaming. A message sent during a queued run steers by default — it lands in the steer lane, ahead of previously queued items; `send({ steer: false })` queues a follow-up behind them instead. Pending items are held in `composer.queue` and drain once the run settles.
-
-```tsx
-const runtime = useLangGraphRuntime({
-  stream,
-  unstable_enableMessageQueue: true,
-});
-```
-
-Render the pending messages with [`ComposerPrimitive.Queue`](/docs/api-reference/primitives/composer) and [`QueueItemPrimitive`](/docs/api-reference/primitives/queue-item).
-
-## Per-run config
-
-When a message is sent, its `runConfig` is forwarded to `stream` and, if you use `unstable_createLangGraphStream`, posted as the LangGraph SDK run `config`. Automatic frontend tool-result resumes and `useLangGraphSendCommand` reuse the `runConfig` of the run that produced the pending tool call or interrupt. An explicit `runConfig` on `useLangGraphSend` still wins. A thread refetch that still carries the interrupt keeps that owner. History loaded without local ownership stays unconfigured on resume; the recording is session-scoped and does not survive a reload.
-
-## 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>