@assistant-ui/mcp-docs-server 0.1.1

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

@@ -0,0 +1,60 @@
+---
+title: Helicone
+---
+
+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,
+  });
+}
+```
+
+## LangChain Integration (Python)
+
+1. **Set Environment Variables:**
+
+   - `HELICONE_API_KEY`
+   - `OPENAI_API_KEY`
+
+2. **Configure ChatOpenAI:**
+
+```python
+from langchain.chat_models import ChatOpenAI
+import os
+
+llm = ChatOpenAI(
+    model_name="gpt-3.5-turbo",
+    temperature=0,
+    openai_api_base="https://oai.helicone.ai/v1",
+    openai_api_key=os.environ["OPENAI_API_KEY"],
+    openai_api_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

@@ -0,0 +1,320 @@
+---
+title: Getting Started
+---
+
+## 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
+
+import { Steps, Step } from "fumadocs-ui/components/steps";
+
+<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
+
+```sh npm2yarn
+npm install @assistant-ui/react @assistant-ui/react-ui @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="@/api/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"] || "",
+      },
+    };
+
+    if (["POST", "PUT", "PATCH"].includes(method)) {
+      options.body = await req.text();
+    }
+
+    const res = await fetch(
+      `${process.env["LANGGRAPH_API_URL"]}/${path}${queryString}`,
+      options,
+    );
+
+    return new NextResponse(res.body, {
+      status: res.status,
+      statusText: res.statusText,
+      headers: {
+        ...res.headers,
+        ...getCorsHeaders(),
+      },
+    });
+  } catch (e: any) {
+    return NextResponse.json({ error: e.message }, { status: e.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");
+
+// Add a new OPTIONS handler
+export const OPTIONS = () => {
+  return 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 } from "@langchain/langgraph-sdk";
+import { LangChainMessage } 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;
+}) => {
+  const client = createClient();
+  return client.runs.stream(
+    params.threadId,
+    process.env["NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID"]!,
+    {
+      input: {
+        messages: params.messages,
+      },
+      streamMode: "messages",
+    },
+  );
+};
+```
+
+  </Step>
+  <Step>
+
+### Define a `MyAssistant` component
+
+```tsx twoslash include MyAssistant title="@/components/MyAssistant.tsx"
+// @filename: /components/MyAssistant.tsx
+// @include: chatApi
+
+// ---cut---
+"use client";
+
+import { useRef } from "react";
+import { Thread } from "@/components/assistant-ui";
+import { AssistantRuntimeProvider } from "@assistant-ui/react";
+import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
+
+import { createThread, getThreadState, sendMessage } from "@/lib/chatApi";
+
+export function MyAssistant() {
+  const threadIdRef = useRef<string | undefined>();
+  const runtime = useLangGraphRuntime({
+    threadId: threadIdRef.current,
+    stream: async (messages) => {
+      if (!threadIdRef.current) {
+        const { thread_id } = await createThread();
+        threadIdRef.current = thread_id;
+      }
+      const threadId = threadIdRef.current;
+      return sendMessage({
+        threadId,
+        messages,
+      });
+    },
+    onSwitchToNewThread: async () => {
+      const { thread_id } = await createThread();
+      threadIdRef.current = thread_id;
+    },
+    onSwitchToThread: async (threadId) => {
+      const state = await getThreadState(threadId);
+      threadIdRef.current = threadId;
+      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" {2,8}
+// @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/shadcn-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);
+```
+
+## 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. This means that if a user switches away from a thread during an interaction (like waiting for user approval), the interaction state will be preserved when they return to that thread.
+
+To handle interrupts in your application:
+
+1. Make sure your thread state type includes the `interrupts` field
+2. Return the interrupts from `onSwitchToThread` 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.

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

@@ -0,0 +1,11 @@
+---
+title: "Introduction"
+---
+
+import { redirect } from "next/navigation";
+
+<>
+  {redirect(
+    "/docs/runtimes/langgraph/tutorial/introduction",
+  )}
+</>

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

@@ -0,0 +1,28 @@
+---
+title: "Introduction"
+---
+
+In this tutorial, we will build a stockbroker assistant using LangChain.js, LangGraph.js and assistant-ui.
+
+We will go through the necessary steps to integrate assistant-ui with a LangGraph Cloud endpoint.
+Code snippets focus on the setup of the frontend, but we will highlight relevant sections of the backend code as well.
+
+This agent leverages the following features:
+
+- 🚄 Streaming of messages from LangGraph state to assistant-ui
+- 💅 Rich text rendering using Markdown
+- 🛠️ Generative UI: Mapping tool calls to tool UIs
+- 🔁 Approval UI: Confirming tool calls before execution (human-in-the-loop)
+
+## Prerequisites
+
+- Node.js 18.x or higher
+
+## Final Result
+
+- Demo: https://assistant-ui-stockbroker.vercel.app/
+- Source Code: https://github.com/assistant-ui/assistant-ui-stockbroker
+
+## Get Started
+
+Begin Part 1 of the tutorial by [setting up the frontend](/docs/runtimes/langgraph/tutorial/part-1).

package/.docs/raw/docs/runtimes/langgraph/tutorial/part-1.mdx

@@ -0,0 +1,120 @@
+---
+title: "Part 1: Setup frontend"
+---
+
+## Create a new project
+
+Run the following command to create a new Next.js project with the LangGraph assistant-ui template:
+
+```sh
+npx create-assistant-ui@latest -t langgraph my-app
+cd my-app
+```
+
+You should see the following files in your project:
+
+import { File, Folder, Files } from "fumadocs-ui/components/files";
+
+<Files>
+  <Folder name="my-app" defaultOpen>
+    <Folder name="app" defaultOpen>
+      <Folder name="api" defaultOpen>
+        <Folder name="[...path]" defaultOpen>
+          <File name="route.ts" />
+        </Folder>
+      </Folder>
+      <File name="globals.css" />
+      <File name="layout.tsx" />
+      <File name="MyRuntimeProvider.tsx" />
+      <File name="page.tsx" />
+    </Folder>
+    <Folder name="lib">
+      <File name="chatApi.ts" />
+    </Folder>
+    <File name="next.config.ts" />
+    <File name="package.json" />
+    <File name="postcss.config.mjs" />
+    <File name="tailwind.config.ts" />
+    <File name="tsconfig.json" />
+  </Folder>
+</Files>
+
+### Setup environment variables
+
+Create a `.env.local` file in your project with the following variables:
+
+```sh title="@/.env.local"
+LANGGRAPH_API_URL=https://assistant-ui-stockbroker.vercel.app/api
+NEXT_PUBLIC_LANGGRAPH_ASSISTANT_ID=stockbroker
+```
+
+This connects the frontend to a LangGraph Cloud endpoint running under  
+`https://assistant-ui-stockbroker.vercel.app/api`.  
+This endpoint is running the LangGraph agent defined [in this repository](https://github.com/assistant-ui/assistant-ui-stockbroker/blob/main/backend).
+
+### Start the server
+
+You can start the server by running the following command:
+
+```sh
+npm run dev
+```
+
+The server will start and you can view the frontend by opening a browser tab to http://localhost:3000.
+
+You should be able to chat with the assistant and see LLM responses streaming in real-time.
+
+## Explore features
+
+### Streaming
+
+Streaming message support is enabled by default. The LangGraph integration includes sophisticated message handling that efficiently manages streaming responses:
+
+- Messages are accumulated and updated in real-time using `LangGraphMessageAccumulator`
+- Partial message chunks are automatically merged using `appendLangChainChunk`
+- The runtime handles all the complexity of managing streaming state
+
+This means you'll see tokens appear smoothly as they're generated by the LLM, with proper handling of both text content and tool calls.
+
+### Markdown support
+
+Rich text rendering using Markdown is enabled by default.
+
+## Add conversation starter messages
+
+In order to help users understand what the assistant can do, we can add some conversation starter messages.
+
+import Image from "next/image";
+import starter from "./images/conversation-starters.png";
+
+<Image
+  src={starter}
+  alt="Conversation starters"
+  width={600}
+  className="mx-auto rounded-lg border shadow"
+/>
+
+```tsx title="@/app/page.tsx" {5-17}
+export default function Home() {
+  return (
+    <div className="flex h-full flex-col">
+      <Thread
+        welcome={{
+          suggestions: [
+            {
+              prompt: "How much revenue did Apple make last year?",
+            },
+            {
+              prompt: "Is McDonald's profitable?",
+            },
+            {
+              prompt: "What's the current stock price of Tesla?",
+            },
+          ],
+        }}
+        assistantMessage={{ components: { Text: MarkdownText } }}
+      />
+    </div>
+  );
+}
+```