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

package/.docs/raw/docs/runtimes/helicone.mdx

@@ -1,61 +0,0 @@
----
-title: Helicone
-description: Configure Helicone proxy for OpenAI API logging and monitoring.
----
-
-Helicone acts as a proxy for your OpenAI API calls, enabling detailed logging and monitoring. To integrate, update your API base URL and add the Helicone-Auth header.
-
-## AI SDK by vercel
-
-1. **Set Environment Variables:**
-
-   - `HELICONE_API_KEY`
-   - `OPENAI_API_KEY`
-
-2. **Configure the OpenAI client:**
-
-```ts
-import { createOpenAI } from "@ai-sdk/openai";
-import { streamText } from "ai";
-
-const openai = createOpenAI({
-  baseURL: "https://oai.helicone.ai/v1",
-  headers: {
-    "Helicone-Auth": `Bearer ${process.env.HELICONE_API_KEY}`,
-  },
-});
-
-export async function POST(req: Request) {
-  const { prompt } = await req.json();
-  return streamText({
-    model: openai("gpt-4o"),
-    prompt,
-  }).toUIMessageStreamResponse();
-}
-```
-
-## LangChain Integration (Python)
-
-1. **Set Environment Variables:**
-
-   - `HELICONE_API_KEY`
-   - `OPENAI_API_KEY`
-
-2. **Configure ChatOpenAI:**
-
-```python
-from langchain_openai import ChatOpenAI
-import os
-
-llm = ChatOpenAI(
-    model_name="gpt-4o",
-    temperature=0,
-    base_url="https://oai.helicone.ai/v1",
-    api_key=os.environ["OPENAI_API_KEY"],
-    default_headers={"Helicone-Auth": f"Bearer {os.environ['HELICONE_API_KEY']}"}
-)
-```
-
-## Summary
-
-Update your API base URL to `https://oai.helicone.ai/v1` and add the `Helicone-Auth` header with your API key either in your Vercel AI SDK or LangChain configuration.

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

@@ -1,607 +0,0 @@
----
-title: Getting Started
-description: Connect to LangGraph Cloud API for agent workflows with streaming.
----
-
-## Requirements
-
-You need a LangGraph Cloud API server. You can start a server locally via [LangGraph Studio](https://github.com/langchain-ai/langgraph-studio) or use [LangSmith](https://www.langchain.com/langsmith) for a hosted version.
-
-The state of the graph you are using must have a `messages` key with a list of LangChain-alike messages.
-
-## New project from template
-
-
-<Steps>
-  <Step>
-  ### Create a new project based on the LangGraph assistant-ui template
-
-```sh
-npx create-assistant-ui@latest -t langgraph my-app
-```
-
-  </Step>
-  <Step>
-  ### Set environment variables
-
-Create a `.env.local` file in your project with the following variables:
-
-```sh
-# LANGCHAIN_API_KEY=your_api_key # for production
-# LANGGRAPH_API_URL=your_api_url # for production
-NEXT_PUBLIC_LANGGRAPH_API_URL=your_api_url # for development (no api key required)
-NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
-```
-
-  </Step>
-</Steps>
-
-
-## Installation in existing React project
-
-<Steps>
-  <Step>
-
-### Install dependencies
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-langgraph", "@langchain/langgraph-sdk"]} />
-
-  </Step>
-    <Step>
-
-### Setup a proxy backend endpoint (optional, for production)
-
-<Callout type="warn">
-  This example forwards every request to the LangGraph server directly from the
-  browser. For production use-cases, you should limit the API calls to the
-  subset of endpoints that you need and perform authorization checks.
-</Callout>
-
-```tsx twoslash title="@/app/api/[...path]/route.ts"
-import { NextRequest, NextResponse } from "next/server";
-
-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"] || "",
-      },
-    };
-
-    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");
-    const corsHeaders = getCorsHeaders();
-    for (const [key, value] of Object.entries(corsHeaders)) {
-      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(),
-  });
-```
-
-  </Step>
-  <Step>
-
-### Setup helper functions
-
-```tsx twoslash include chatApi title="@/lib/chatApi.ts"
-// @filename: /lib/chatApi.ts
-
-// ---cut---
-import { Client, type ThreadState } from "@langchain/langgraph-sdk";
-import { LangChainMessage, LangGraphCommand } from "@assistant-ui/react-langgraph";
-
-const createClient = () => {
-  const apiUrl = process.env["NEXT_PUBLIC_LANGGRAPH_API_URL"] || "/api";
-  return new Client({
-    apiUrl,
-  });
-};
-
-export const createThread = async () => {
-  const client = createClient();
-  return client.threads.create();
-};
-
-export const getThreadState = async (
-  threadId: string,
-): Promise<ThreadState<{ messages: LangChainMessage[] }>> => {
-  const client = createClient();
-  return client.threads.getState(threadId);
-};
-
-export const sendMessage = async (params: {
-  threadId: string;
-  messages?: LangChainMessage[];
-  command?: LangGraphCommand;
-}) => {
-  const client = createClient();
-  return client.runs.stream(
-    params.threadId,
-    process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
-    {
-      input: params.messages?.length
-        ? { messages: params.messages }
-        : null,
-      command: params.command,
-      // Include "custom" if you use LangSmith Generative UI
-      // (`push_ui_message` / `typedUi().push()`). See the Generative UI
-      // section below for details.
-      streamMode: ["messages", "updates", "custom"],
-    },
-  );
-};
-```
-
-  </Step>
-  <Step>
-
-### Define a `MyAssistant` component
-
-```tsx twoslash include MyAssistant title="@/components/MyAssistant.tsx"
-// @filename: /components/MyAssistant.tsx
-// @include: chatApi
-
-// ---cut---
-"use client";
-
-import { Thread } from "@/components/assistant-ui/thread";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
-
-import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
-
-export function MyAssistant() {
-  const runtime = useLangGraphRuntime({
-    stream: async function* (messages, { initialize, command }) {
-      const { externalId } = await initialize();
-      if (!externalId) throw new Error("Thread not found");
-
-      const generator = await sendMessage({
-        threadId: externalId,
-        messages,
-        command,
-      });
-
-      yield* generator;
-    },
-    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,
-      };
-    },
-  });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      <Thread />
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-  </Step>
-  <Step>
-
-### Use the `MyAssistant` component
-
-```tsx twoslash title="@/app/page.tsx" {1,6}
-// @include: MyAssistant
-// @filename: /app/page.tsx
-// ---cut---
-import { MyAssistant } from "@/components/MyAssistant";
-
-export default function Home() {
-  return (
-    <main className="h-dvh">
-      <MyAssistant />
-    </main>
-  );
-}
-```
-
-  </Step>
-  <Step>
-
-### Setup environment variables
-
-Create a `.env.local` file in your project with the following variables:
-
-```sh
-# LANGCHAIN_API_KEY=your_api_key # for production
-# LANGGRAPH_API_URL=your_api_url # for production
-NEXT_PUBLIC_LANGGRAPH_API_URL=your_api_url # for development (no api key required)
-NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=your_graph_id
-```
-
-  </Step>
-  <Step>
-
-### Setup UI components
-
-Follow the [UI Components](/docs/ui/thread) guide to setup the UI components.
-
-  </Step>
-</Steps>
-
-## Advanced APIs
-
-### Message Accumulator
-
-The `LangGraphMessageAccumulator` lets you append messages incoming from the server to replicate the messages state client side.
-
-```typescript
-import {
-  LangGraphMessageAccumulator,
-  appendLangChainChunk,
-} from "@assistant-ui/react-langgraph";
-
-const accumulator = new LangGraphMessageAccumulator({
-  appendMessage: appendLangChainChunk,
-});
-
-// Add new chunks from the server
-if (event.event === "messages/partial") accumulator.addMessages(event.data);
-```
-
-### Message Conversion
-
-Use `convertLangChainMessages` to transform LangChain messages to assistant-ui format:
-
-```typescript
-import { convertLangChainMessages } from "@assistant-ui/react-langgraph";
-
-const threadMessage = convertLangChainMessages(langChainMessage);
-```
-
-### Event Handlers
-
-You can listen to streaming events by passing `eventHandlers` to `useLangGraphRuntime`:
-
-```typescript
-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.
-    },
-    onValues: (values) => {
-      // Fired when a "values" event is received
-    },
-    onUpdates: (updates) => {
-      // Fired when an "updates" event is received
-    },
-    onMetadata: (metadata) => { /* thread metadata */ },
-    onInfo: (info) => { /* informational messages */ },
-    onError: (error) => { /* stream 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 the `useLangGraphMessageMetadata` hook:
-
-```typescript
-import { useLangGraphMessageMetadata } from "@assistant-ui/react-langgraph";
-
-function MyComponent() {
-  const metadata = useLangGraphMessageMetadata();
-  // Map<string, LangGraphTupleMetadata> keyed by message ID
-}
-```
-
-## Thread Management
-
-### Basic Thread Support
-
-The `useLangGraphRuntime` hook now includes built-in thread management capabilities:
-
-```typescript
-const runtime = useLangGraphRuntime({
-  stream: async (messages, { initialize, ...config }) => {
-    // initialize() creates or loads a thread and returns its IDs
-    const { remoteId, externalId } = await initialize();
-    // Use externalId (your backend's thread ID) for API calls
-    return sendMessage({ threadId: externalId, messages, config });
-  },
-  create: async () => {
-    // Called when creating a new thread
-    const { thread_id } = await createThread();
-    return { externalId: thread_id };
-  },
-  load: async (externalId) => {
-    // Called when loading an existing thread
-    const state = await getThreadState(externalId);
-    return {
-      messages: state.values.messages,
-      interrupts: state.tasks[0]?.interrupts,
-    };
-  },
-});
-```
-
-### Cloud Persistence
-
-For persistent thread history across sessions, integrate with assistant-cloud:
-
-```typescript
-const runtime = useLangGraphRuntime({
-  cloud: new AssistantCloud({
-    baseUrl: process.env.NEXT_PUBLIC_ASSISTANT_BASE_URL,
-    anonymous: true,
-  }),
-  // ... stream, create, load functions
-});
-```
-
-See the [Cloud Persistence guide](/docs/cloud/langgraph) for detailed setup instructions.
-
-## Message Editing & Regeneration
-
-LangGraph uses server-side checkpoints for state management. To support message editing (branching) and regeneration, you need to provide a `getCheckpointId` callback that resolves the appropriate checkpoint for server-side forking.
-
-```typescript
-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();
-    // Get the thread state history and find the checkpoint
-    // that matches the parent messages by exact message ID sequence.
-    // If IDs are missing, return null and skip edit/reload for safety.
-    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((message) => typeof message.id === "string") &&
-        stateMessages.every((message) => typeof message.id === "string");
-      if (!hasStableIds) {
-        continue;
-      }
-
-      const isMatch = parentMessages.every(
-        (message, index) => message.id === stateMessages[index]?.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 the helper function in the setup section above).
-
-<Callout type="info">
-  Without `getCheckpointId`, the edit and regenerate buttons will not appear. This is intentional — simply truncating client-side messages without forking from the correct server-side checkpoint would produce incorrect state.
-</Callout>
-
-## 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 will automatically restore the interrupt state when switching threads
-
-This feature is particularly useful for applications that require user approval flows, multi-step forms, or any other interactive elements that might span multiple thread switches.
-
-## Generative UI (`ui_message`)
-
-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 LangGraph adapter translates these into [`DataMessagePart`s](/docs/guides/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"]
-```
-
-Alternatively, 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` on the client:
-
-```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 doesn't rely on the state key.
-
-### Emit a UI message from your graph
-
-```python title="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]}
-```
-
-```ts title="TypeScript"
-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] };
-}
-```
-
-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
-
-```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>
-  ),
-});
-```
-
-Mount the component once somewhere inside the `AssistantRuntimeProvider` tree. It renders nothing itself — it only registers the renderer:
-
-```tsx title="@/components/MyAssistant.tsx"
-<AssistantRuntimeProvider runtime={runtime}>
-  <ChartUI />
-  <Thread />
-</AssistantRuntimeProvider>
-```
-
-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.
-
-### 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` / `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're 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(/* ... */)}</>;
-}
-```

package/.docs/raw/docs/runtimes/langgraph/tutorial/index.mdx

@@ -1,12 +0,0 @@
----
-title: "Introduction"
-description: Build a stockbroker assistant with LangGraph and assistant-ui.
----
-
-import { redirect } from "next/navigation";
-
-<>
-  {redirect(
-    "/docs/runtimes/langgraph/tutorial/introduction",
-  )}
-</>