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

package/.docs/organized/code-examples/with-assistant-transport.md

@@ -1,575 +0,0 @@
-# Example: with-assistant-transport
-
-## app/globals.css
-
-```css
-@import "tailwindcss";
-@import "tw-animate-css";
-
-@source "../../../packages/ui/src";
-
-@custom-variant dark (&:is(.dark *));
-
-@theme inline {
-  --radius-sm: calc(var(--radius) - 4px);
-  --radius-md: calc(var(--radius) - 2px);
-  --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-card: var(--card);
-  --color-card-foreground: var(--card-foreground);
-  --color-popover: var(--popover);
-  --color-popover-foreground: var(--popover-foreground);
-  --color-primary: var(--primary);
-  --color-primary-foreground: var(--primary-foreground);
-  --color-secondary: var(--secondary);
-  --color-secondary-foreground: var(--secondary-foreground);
-  --color-muted: var(--muted);
-  --color-muted-foreground: var(--muted-foreground);
-  --color-accent: var(--accent);
-  --color-accent-foreground: var(--accent-foreground);
-  --color-destructive: var(--destructive);
-  --color-border: var(--border);
-  --color-input: var(--input);
-  --color-ring: var(--ring);
-  --color-chart-1: var(--chart-1);
-  --color-chart-2: var(--chart-2);
-  --color-chart-3: var(--chart-3);
-  --color-chart-4: var(--chart-4);
-  --color-chart-5: var(--chart-5);
-  --color-sidebar: var(--sidebar);
-  --color-sidebar-foreground: var(--sidebar-foreground);
-  --color-sidebar-primary: var(--sidebar-primary);
-  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
-  --color-sidebar-accent: var(--sidebar-accent);
-  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
-  --color-sidebar-border: var(--sidebar-border);
-  --color-sidebar-ring: var(--sidebar-ring);
-}
-
-:root {
-  --radius: 0.625rem;
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.141 0.005 285.823);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.141 0.005 285.823);
-  --popover: oklch(1 0 0);
-  --popover-foreground: oklch(0.141 0.005 285.823);
-  --primary: oklch(0.21 0.006 285.885);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.967 0.001 286.375);
-  --secondary-foreground: oklch(0.21 0.006 285.885);
-  --muted: oklch(0.967 0.001 286.375);
-  --muted-foreground: oklch(0.552 0.016 285.938);
-  --accent: oklch(0.967 0.001 286.375);
-  --accent-foreground: oklch(0.21 0.006 285.885);
-  --destructive: oklch(0.577 0.245 27.325);
-  --border: oklch(0.92 0.004 286.32);
-  --input: oklch(0.92 0.004 286.32);
-  --ring: oklch(0.705 0.015 286.067);
-  --chart-1: oklch(0.646 0.222 41.116);
-  --chart-2: oklch(0.6 0.118 184.704);
-  --chart-3: oklch(0.398 0.07 227.392);
-  --chart-4: oklch(0.828 0.189 84.429);
-  --chart-5: oklch(0.769 0.188 70.08);
-  --sidebar: oklch(0.985 0 0);
-  --sidebar-foreground: oklch(0.141 0.005 285.823);
-  --sidebar-primary: oklch(0.21 0.006 285.885);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.967 0.001 286.375);
-  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
-  --sidebar-border: oklch(0.92 0.004 286.32);
-  --sidebar-ring: oklch(0.705 0.015 286.067);
-}
-
-.dark {
-  --background: oklch(0.141 0.005 285.823);
-  --foreground: oklch(0.985 0 0);
-  --card: oklch(0.21 0.006 285.885);
-  --card-foreground: oklch(0.985 0 0);
-  --popover: oklch(0.21 0.006 285.885);
-  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.92 0.004 286.32);
-  --primary-foreground: oklch(0.21 0.006 285.885);
-  --secondary: oklch(0.274 0.006 286.033);
-  --secondary-foreground: oklch(0.985 0 0);
-  --muted: oklch(0.274 0.006 286.033);
-  --muted-foreground: oklch(0.705 0.015 286.067);
-  --accent: oklch(0.274 0.006 286.033);
-  --accent-foreground: oklch(0.985 0 0);
-  --destructive: oklch(0.704 0.191 22.216);
-  --border: oklch(1 0 0 / 10%);
-  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.552 0.016 285.938);
-  --chart-1: oklch(0.488 0.243 264.376);
-  --chart-2: oklch(0.696 0.17 162.48);
-  --chart-3: oklch(0.769 0.188 70.08);
-  --chart-4: oklch(0.627 0.265 303.9);
-  --chart-5: oklch(0.645 0.246 16.439);
-  --sidebar: oklch(0.21 0.006 285.885);
-  --sidebar-foreground: oklch(0.985 0 0);
-  --sidebar-primary: oklch(0.488 0.243 264.376);
-  --sidebar-primary-foreground: oklch(0.985 0 0);
-  --sidebar-accent: oklch(0.274 0.006 286.033);
-  --sidebar-accent-foreground: oklch(0.985 0 0);
-  --sidebar-border: oklch(1 0 0 / 10%);
-  --sidebar-ring: oklch(0.552 0.016 285.938);
-}
-
-@layer base {
-  * {
-    @apply border-border outline-ring/50;
-  }
-  body {
-    @apply bg-background text-foreground;
-  }
-}
-
-```
-
-## app/layout.tsx
-
-```tsx
-import type { Metadata } from "next";
-import "./globals.css";
-
-export const metadata: Metadata = {
-  title: "assistant-ui with Assistant Transport",
-  description:
-    "An example of using assistant-ui with the assistant-transport runtime",
-};
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="en">
-      <body className="font-sans antialiased">
-        <div className="flex h-screen flex-col">
-          <header className="bg-background border-b px-4 py-2">
-            <h1 className="text-lg font-semibold">
-              Assistant Transport Example
-            </h1>
-          </header>
-          <main className="flex-1 overflow-hidden">{children}</main>
-        </div>
-      </body>
-    </html>
-  );
-}
-
-```
-
-## app/MyRuntimeProvider.tsx
-
-```tsx
-"use client";
-
-import {
-  AssistantRuntimeProvider,
-  AuiConfig,
-  Tools,
-  type AssistantTransportConnectionMetadata,
-  unstable_createMessageConverter as createMessageConverter,
-  useAssistantTransportRuntime,
-} from "@assistant-ui/react";
-import {
-  convertLangChainMessages,
-  type LangChainMessage,
-} from "@assistant-ui/react-langgraph";
-import type { ReactNode } from "react";
-import toolkit from "./toolkit";
-
-type MyRuntimeProviderProps = {
-  children: ReactNode;
-};
-
-type State = {
-  messages: LangChainMessage[];
-};
-
-const LangChainMessageConverter = createMessageConverter(
-  convertLangChainMessages,
-);
-
-const converter = (
-  state: State,
-  connectionMetadata: AssistantTransportConnectionMetadata,
-) => {
-  const optimisticStateMessages = connectionMetadata.pendingCommands.map(
-    (c): LangChainMessage[] => {
-      if (c.type === "add-message") {
-        return [
-          {
-            type: "human" as const,
-            content: [
-              {
-                type: "text" as const,
-                text: c.message.parts
-                  .map((p) => (p.type === "text" ? p.text : ""))
-                  .join("\n"),
-              },
-            ],
-          },
-        ];
-      }
-      return [];
-    },
-  );
-
-  const messages = [...state.messages, ...optimisticStateMessages.flat()];
-  return {
-    messages: LangChainMessageConverter.toThreadMessages(messages),
-    isRunning: connectionMetadata.isSending || false,
-  };
-};
-
-export function MyRuntimeProvider({ children }: MyRuntimeProviderProps) {
-  const runtime = useAssistantTransportRuntime({
-    initialState: {
-      messages: [],
-    },
-    api: process.env.NEXT_PUBLIC_API_URL || "http://localhost:8010/assistant",
-    converter,
-    headers: async () => ({
-      "Test-Header": "test-value",
-    }),
-    body: {
-      "Test-Body": "test-value",
-    },
-    prepareSendCommandsRequest: (body) => {
-      console.log("Assistant transport request tools:", body.tools);
-      return body;
-    },
-    onResponse: () => {
-      console.log("Response received from server");
-    },
-    onFinish: () => {
-      console.log("Conversation completed");
-    },
-    onError: (error: Error) => {
-      console.error("Assistant transport error:", error);
-    },
-    onCancel: () => {
-      console.log("Request cancelled");
-    },
-  });
-  const config = AuiConfig({
-    tools: Tools({ toolkit }),
-  });
-
-  return (
-    <AssistantRuntimeProvider config={config} runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-
-```
-
-## app/page.tsx
-
-```tsx
-"use client";
-
-import { Thread } from "@/components/assistant-ui/thread";
-import {
-  useAui,
-  AuiProvider,
-  AuiConfig,
-  Suggestions,
-} from "@assistant-ui/react";
-import { MyRuntimeProvider } from "./MyRuntimeProvider";
-
-function ThreadWithSuggestions() {
-  const aui = useAui();
-  const config = AuiConfig({
-    suggestions: Suggestions([
-      {
-        title: "What's the weather",
-        label: "in San Francisco?",
-        prompt: "What's the weather like in San Francisco today?",
-      },
-      {
-        title: "Tell me about yourself",
-        label: "and your capabilities",
-        prompt: "What can you help me with?",
-      },
-    ]),
-  });
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <Thread />
-    </AuiProvider>
-  );
-}
-
-export default function Home() {
-  return (
-    <MyRuntimeProvider>
-      <div className="h-full">
-        <ThreadWithSuggestions />
-      </div>
-    </MyRuntimeProvider>
-  );
-}
-
-```
-
-## app/toolkit.tsx
-
-```tsx
-"use generative";
-
-import { defineToolkit } from "@assistant-ui/react";
-import { z } from "zod";
-
-export default defineToolkit({
-  get_weather: {
-    description: "Get the current weather for a city",
-    parameters: z.object({
-      location: z.string().describe("The city to get weather for"),
-      unit: z
-        .enum(["celsius", "fahrenheit"])
-        .optional()
-        .describe("Temperature unit"),
-    }),
-    execute: async ({ location, unit = "celsius" }) => {
-      "use client";
-
-      console.log(`Getting weather for ${location} in ${unit}`);
-      await new Promise((resolve) => setTimeout(resolve, 1000));
-
-      const temp = Math.floor(Math.random() * 30) + 10;
-      const conditions = ["sunny", "cloudy", "rainy", "partly cloudy"];
-      const condition =
-        conditions[Math.floor(Math.random() * conditions.length)];
-
-      return {
-        location,
-        temperature: temp,
-        unit,
-        condition,
-        humidity: Math.floor(Math.random() * 40) + 40,
-        windSpeed: Math.floor(Math.random() * 20) + 5,
-      };
-    },
-    streamCall: async (reader) => {
-      "use client";
-
-      console.log("streamCall", reader);
-      const city = await reader.args.get("location");
-      console.log("location", city);
-
-      const args = await reader.args.get();
-      console.log("args", args);
-
-      const result = await reader.response.get();
-      console.log("result", result);
-    },
-    renderText: {
-      running: ({ args }) => `Getting weather for ${args.location ?? "..."}`,
-      complete: ({ args, result }) =>
-        result
-          ? `${args.location}: ${result.temperature}° ${result.unit}, ${result.condition}`
-          : "Weather lookup complete",
-    },
-  },
-});
-
-```
-
-## components.json
-
-```json
-{
-  "$schema": "https://ui.shadcn.com/schema.json",
-  "style": "new-york",
-  "rsc": true,
-  "tsx": true,
-  "tailwind": {
-    "config": "",
-    "css": "app/globals.css",
-    "baseColor": "zinc",
-    "cssVariables": true,
-    "prefix": ""
-  },
-  "aliases": {
-    "components": "@/components",
-    "utils": "@/lib/utils",
-    "ui": "@/components/ui",
-    "lib": "@/lib",
-    "hooks": "@/hooks"
-  },
-  "iconLibrary": "lucide",
-  "registries": {
-    "@assistant-ui": "https://r.assistant-ui.com/{name}.json"
-  }
-}
-
-```
-
-## next.config.js
-
-```javascript
-import { withAui } from "@assistant-ui/next";
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  experimental: {
-    optimizePackageImports: ["@assistant-ui/react"],
-  },
-  async rewrites() {
-    return [
-      {
-        source: "/assistant/:path*",
-        destination: "http://localhost:8000/assistant/:path*",
-      },
-    ];
-  },
-};
-
-export default withAui(nextConfig);
-
-```
-
-## package.json
-
-```json
-{
-  "name": "with-assistant-transport",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start"
-  },
-  "dependencies": {
-    "@assistant-ui/react": "workspace:*",
-    "@assistant-ui/react-langgraph": "workspace:*",
-    "@assistant-ui/react-markdown": "workspace:*",
-    "@assistant-ui/ui": "workspace:*",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.31.0",
-    "next": "^16.3.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "tailwind-merge": "^3.6.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@assistant-ui/next": "workspace:*",
-    "@assistant-ui/x-buildutils": "workspace:*",
-    "@tailwindcss/postcss": "^4.3.3",
-    "@types/node": "^26.2.0",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.4",
-    "postcss": "^8.5.26",
-    "tailwindcss": "^4.3.3",
-    "tw-animate-css": "^1.4.0",
-    "typescript": "^7.0.2"
-  }
-}
-
-```
-
-## README.md
-
-```markdown
-# Assistant Transport Example
-
-This example demonstrates how to use assistant-ui with the `useAssistantTransportRuntime` hook to connect to a custom backend server that implements the assistant-transport protocol.
-
-## Quick Start
-
-### Using CLI (Recommended)
-
-```bash
-npx assistant-ui@latest create my-app --example with-assistant-transport
-cd my-app
-```
-
-### Environment Variables
-
-Create `.env.local`:
-
-```
-NEXT_PUBLIC_API_URL=http://localhost:8000/assistant
-```
-
-### Run
-
-```bash
-npm install
-npm run dev
-```
-
-The application will be available at [http://localhost:3000](http://localhost:3000).
-
-## Overview
-
-The Assistant Transport runtime allows you to connect assistant-ui to any backend server that can handle:
-
-- `AddMessageCommand` - for sending user messages
-- `AddToolResultCommand` - for sending tool execution results
-- Streaming responses using the `assistant-stream` format
-
-## Backend Server Requirements
-
-Your backend server should:
-
-1. Accept POST requests at the configured endpoint (e.g., `/assistant`)
-2. Handle the following command types in the request body:
-   - `AddMessageCommand`: `{ type: "add-message", message: { role: "user", parts: [...] } }`
-   - `AddToolResultCommand`: `{ type: "add-tool-result", toolCallId: string, result: object }`
-3. Return streaming responses using the `assistant-stream` format
-4. Include CORS headers to allow requests from the frontend
-
-## Key Features
-
-- **Custom Runtime**: Uses `useAssistantTransportRuntime` to connect to any backend
-- **Streaming Support**: Handles real-time streaming responses from the server
-- **Tool Support**: Supports tool calling between frontend and backend
-- **Error Handling**: Includes proper error handling and loading states
-- **Modern UI**: Built with Tailwind CSS and Radix UI components
-
-## Related Documentation
-
-- [assistant-ui Documentation](https://www.assistant-ui.com/docs)
-- [Assistant Transport Runtime API](https://www.assistant-ui.com/docs/runtimes/custom/assistant-transport)
-
-```
-
-## tsconfig.json
-
-```json
-{
-  "extends": "@assistant-ui/x-buildutils/ts/next",
-  "compilerOptions": {
-    "paths": {
-      "@/*": ["./*"],
-      "@/components/assistant-ui/*": [
-        "../../packages/ui/src/components/assistant-ui/*"
-      ],
-      "@/components/ui/*": [
-        "../../packages/ui/src/components/ui/base/*",
-        "../../packages/ui/src/components/ui/radix/*"
-      ],
-      "@/components/ui/radix/*": [
-        "../../packages/ui/src/components/ui/radix/*"
-      ],
-      "@/lib/utils": ["../../packages/ui/src/lib/utils"],
-      "@assistant-ui/ui/*": ["../../packages/ui/src/*"]
-    }
-  },
-  "include": ["**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
-}
-
-```
-