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

package/.docs/raw/docs/guides/message-timing.mdx

@@ -1,215 +0,0 @@
----
-title: Message Timing & Token Stats
-description: Display stream metadata in AI chat — generation duration, tokens per second, and time to first token, rendered via assistant-ui's React components.
-platforms: ["react"]
----
-
-Display stream performance metrics — duration, tokens per second, TTFT — on assistant messages.
-
-<Callout type="warn">
-  This feature is experimental. The `useMessageTiming()` API and the set of tracked fields may change in future versions.
-</Callout>
-
-<Callout type="info">
-  The [`MessageTiming`](/docs/ui/message-timing) registry component provides a ready-made badge + popover UI. This guide covers the underlying `useMessageTiming()` hook for custom implementations and runtime-specific setup.
-</Callout>
-
-## Reading Timing Data
-
-Use `useMessageTiming()` inside a message component to access timing data:
-
-```tsx
-import type { FC } from "react";
-import { useMessageTiming } from "@assistant-ui/react";
-
-const MessageTimingDisplay: FC = () => {
-  const timing = useMessageTiming();
-  if (!timing?.totalStreamTime) return null;
-
-  const formatMs = (ms: number) =>
-    ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(2)}s`;
-
-  return (
-    <span className="text-xs text-muted-foreground">
-      {formatMs(timing.totalStreamTime)}
-      {timing.tokensPerSecond !== undefined &&
-        ` · ${timing.tokensPerSecond.toFixed(1)} tok/s`}
-    </span>
-  );
-};
-```
-
-Place it inside `MessagePrimitive.Root`, typically near the action bar:
-
-```tsx {8}
-const AssistantMessage: FC = () => {
-  return (
-    <MessagePrimitive.Root>
-      <MessagePrimitive.Parts>{...}</MessagePrimitive.Parts>
-      <ActionBarPrimitive.Root>
-        <ActionBarPrimitive.Copy />
-        <ActionBarPrimitive.Reload />
-        <MessageTimingDisplay />
-      </ActionBarPrimitive.Root>
-    </MessagePrimitive.Root>
-  );
-};
-```
-
-### `useMessageTiming()` Return Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `streamStartTime` | `number` | Unix timestamp when stream started |
-| `firstTokenTime` | `number?` | Time to first text token (ms) |
-| `totalStreamTime` | `number?` | Total stream duration (ms) |
-| `tokenCount` | `number?` | Output token count from message metadata usage |
-| `tokensPerSecond` | `number?` | Throughput (tokens/sec), when token usage is available |
-| `totalChunks` | `number` | Total stream chunks received |
-| `toolCallCount` | `number` | Number of tool calls |
-
-## Runtime Support
-
-| Runtime | Supported | Notes |
-|---------|:-:|-------|
-| [Data Stream](/docs/runtimes/custom/data-stream) | Yes | Automatic via `AssistantMessageAccumulator` |
-| AI SDK (`useChatRuntime`) | Yes | Automatic via client-side tracking |
-| Local (`useLocalRuntime`) | Yes | Pass timing in `ChatModelRunResult.metadata` |
-| ExternalStore | Yes | Pass timing in `ThreadMessageLike.metadata` |
-| LangGraph | Yes | Automatic via client-side tracking |
-| AG-UI | Yes | Automatic via client-side tracking |
-| OpenCode | Yes | Automatic via client-side tracking |
-
-### Data Stream
-
-Timing is tracked automatically inside `AssistantMessageAccumulator`. No setup required.
-
-```tsx
-import { useDataStreamRuntime } from "@assistant-ui/react-data-stream";
-
-const runtime = useDataStreamRuntime({ api: "/api/chat" });
-// useMessageTiming() works out of the box
-```
-
-### AI SDK (`useChatRuntime`)
-
-Timing is tracked automatically on the client side by observing streaming state transitions and content changes. Timing is finalized when each stream completes.
-
-<Callout type="warn">
-  `tokenCount` and `tokensPerSecond` require usage metadata from `finish` or `finish-step` in your AI SDK route. If usage metadata is not emitted, duration and TTFT metrics still work, but token-based metrics are omitted.
-</Callout>
-
-```tsx
-import { useChatRuntime } from "@assistant-ui/ai-sdk";
-
-const runtime = useChatRuntime();
-// useMessageTiming() works out of the box
-```
-
-### Local (`useLocalRuntime`)
-
-Pass timing in the `metadata` field of your `ChatModelRunResult`:
-
-```tsx
-import type { ChatModelAdapter } from "@assistant-ui/react";
-
-const myAdapter: ChatModelAdapter = {
-  async run({ messages, abortSignal }) {
-    const startTime = Date.now();
-    const result = await callMyAPI(messages, abortSignal);
-    const totalStreamTime = Date.now() - startTime;
-
-    return {
-      content: [{ type: "text", text: result.text }],
-      metadata: {
-        timing: {
-          streamStartTime: startTime,
-          totalStreamTime,
-          tokenCount: result.usage?.completionTokens,
-          tokensPerSecond:
-            result.usage?.completionTokens
-              ? result.usage.completionTokens / (totalStreamTime / 1000)
-              : undefined,
-          totalChunks: 1,
-          toolCallCount: 0,
-        },
-      },
-    };
-  },
-};
-```
-
-### ExternalStore (`useExternalStoreRuntime`)
-
-Pass timing in the `metadata.timing` field of your `ThreadMessageLike` messages:
-
-```tsx
-import type { ThreadMessageLike } from "@assistant-ui/react";
-
-const message: ThreadMessageLike = {
-  role: "assistant",
-  content: [{ type: "text", text: fullText }],
-  metadata: {
-    timing: {
-      streamStartTime: startTime,
-      firstTokenTime,
-      totalStreamTime,
-      tokenCount,
-      tokensPerSecond,
-      totalChunks: chunks,
-      toolCallCount: 0,
-    },
-  },
-};
-```
-
-### LangGraph (`useLangGraphRuntime`)
-
-Timing is tracked automatically on the client side by observing streaming state transitions and `LangChainMessage` content changes. No setup required.
-
-```tsx
-import { useLangGraphRuntime } from "@assistant-ui/react-langgraph";
-
-const runtime = useLangGraphRuntime({ stream: myStream });
-// useMessageTiming() works out of the box
-```
-
-### AG-UI (`useAgUiRuntime`)
-
-Timing is tracked automatically on the client side by the AG-UI run aggregator. Each emitted message includes timing metadata computed from stream chunk observations.
-
-```tsx
-import { useMemo } from "react";
-import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
-import { HttpAgent } from "@ag-ui/client";
-
-const agent = useMemo(
-  () => new HttpAgent({ url: "http://localhost:8000/agent" }),
-  [],
-);
-const runtime = useAgUiRuntime({ agent });
-// useMessageTiming() works out of the box
-```
-
-### OpenCode (`useOpenCodeRuntime`)
-
-Timing is tracked automatically on the client side by observing `OpenCodeThreadState` transitions and assistant message content deltas. No setup required.
-
-```tsx
-import { useOpenCodeRuntime } from "@assistant-ui/react-opencode";
-
-const runtime = useOpenCodeRuntime();
-// useMessageTiming() works out of the box
-```
-
-## API Reference
-
-### `useMessageTiming()`
-
-```tsx
-const timing: MessageTiming | undefined = useMessageTiming();
-```
-
-Returns timing metadata for the current assistant message, or `undefined` for non-assistant messages or when no timing data is available.
-
-Must be used inside a `MessagePrimitive.Root` context.

package/.docs/raw/docs/guides/quoting.mdx

@@ -1,169 +0,0 @@
----
-title: Quote Selected Text
-description: Let users select text from AI messages and quote it back into the composer. Full quoting flow with backend handling and programmatic API in assistant-ui.
-platforms: ["react"]
----
-
-import { QuoteComposerSample } from "@/components/pages/docs/samples/quote-composer";
-
-<QuoteComposerSample />
-
-## Get Started
-
-Install and wire up the `quote` registry component by following the [Quote component page](/docs/ui/quote). It covers the install command, component placement, and the `injectQuoteContext` helper for forwarding quote data to the LLM.
-
-<Callout type="warn">
-  **Limitations:** only one quote can be active at a time. `setQuote` replaces the previous quote instead of appending. The floating toolbar only appears when the selection is entirely within a single message part; cross-message and cross-part selections are ignored.
-</Callout>
-
----
-
-## How It Works
-
-When a user selects text in an assistant message, a floating toolbar appears with a Quote button. Clicking it calls `composer.setQuote()` to store the selection on the composer. The [Quote component](/docs/ui/quote) does this out of the box.
-
-When the message is sent, the composer runtime automatically writes the quote to `message.metadata.custom.quote` and clears it from the composer.
-
-On the backend, the route handler extracts the quote from metadata and surfaces it to the LLM. We export a helper called `injectQuoteContext` that handles this automatically for AI-SDK. Without this step, the quote appears in the UI but is not sent to the model as context. See [Backend Handling](#backend-handling) for more info and alternatives.
-
-### Data Shape
-
-```typescript
-type QuoteInfo = {
-  readonly text: string;       // selected plain text
-  readonly messageId: string;  // source message ID
-};
-
-// Stored at: message.metadata.custom.quote
-```
-
-## Backend Handling
-
-Quote data travels in message metadata, not content, so the LLM will not see it unless your backend extracts and surfaces it. The simplest path is [`injectQuoteContext`](/docs/ui/quote#forward-quote-context-to-the-llm), which prepends quoted text as a markdown blockquote before the message parts.
-
-For provider-specific handling, work with the quote metadata directly.
-
-### Claude SDK Citations
-
-Pass the quoted text as a citation source so Claude produces citations that reference it:
-
-```typescript title="app/api/chat/route.ts"
-import Anthropic from "@anthropic-ai/sdk";
-
-const client = new Anthropic();
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const claudeMessages = messages.map((msg) => {
-    const quote = msg.metadata?.custom?.quote;
-    if (!quote?.text) {
-      return { role: msg.role, content: extractText(msg) };
-    }
-
-    return {
-      role: "user",
-      content: [
-        {
-          type: "text",
-          text: quote.text,
-          cache_control: { type: "ephemeral" },
-          citations: { enabled: true },
-        },
-        {
-          type: "text",
-          text: extractText(msg),
-        },
-      ],
-    };
-  });
-
-  const response = await client.messages.create({
-    model: "claude-sonnet-4-6",
-    max_tokens: 1024,
-    messages: claudeMessages,
-  });
-
-  // ... stream response back
-}
-```
-
-### OpenAI Message Context
-
-Inject the quote as additional context in the user message:
-
-```typescript title="app/api/chat/route.ts"
-function injectQuoteForOpenAI(messages) {
-  return messages.map((msg) => {
-    const quote = msg.metadata?.custom?.quote;
-    if (!quote?.text || msg.role !== "user") return msg;
-
-    return {
-      ...msg,
-      content: `[Referring to: "${quote.text}"]\n\n${msg.content}`,
-    };
-  });
-}
-```
-
-## Reading Quote Data
-
-Use `useMessageQuote` to access quote data in custom components:
-
-```tsx
-import { useMessageQuote } from "@assistant-ui/react";
-
-function CustomQuoteDisplay() {
-  const quote = useMessageQuote();
-  if (!quote) return null;
-
-  return (
-    <blockquote className="border-l-2 pl-3 text-sm text-muted-foreground">
-      {quote.text}
-    </blockquote>
-  );
-}
-```
-
-## Programmatic API
-
-Set or clear quotes via `useAui` from `@assistant-ui/react`. Call `aui.thread.composer().setQuote()` when your component is rendered outside of a specific thread context, or `aui.composer.setQuote()` when it is rendered inside a thread:
-
-```tsx
-import { useAui } from "@assistant-ui/react";
-
-function MyComponent() {
-  const aui = useAui();
-
-  const quoteText = () => {
-    aui.thread.composer().setQuote({
-      text: "The text to quote",
-      messageId: "msg-123",
-    });
-  };
-
-  const clearQuote = () => {
-    aui.thread.composer().setQuote(undefined);
-  };
-
-  return (
-    <>
-      <button onClick={quoteText}>Set Quote</button>
-      <button onClick={clearQuote}>Clear Quote</button>
-    </>
-  );
-}
-```
-
-## Design Notes
-
-- **snapshot text:** the selected text is captured when the quote is created and is not linked to the source message afterward.
-- **streaming messages:** the toolbar still works while a message is streaming because it relies on the captured selection rather than message status.
-- **`isEmpty` unchanged:** a quote by itself does not make the composer non-empty; the user still needs to type a reply.
-- **scroll hides toolbar:** the toolbar hides on scroll because its position would otherwise become stale.
-
-## Related
-
-- [Quote component](/docs/ui/quote): Installation, component setup, and API reference
-- [Message Editing](/docs/guides/editing): Edit user messages
-- [Thread](/docs/ui/thread): Main chat container

package/.docs/raw/docs/guides/resumable-stream-deployment.mdx

@@ -1,212 +0,0 @@
----
-title: Resumable Stream Deployment
-description: Production hardening for resumable streams. Authorization, serverless lifetimes, TTLs, key isolation, observability, resource limits, and incident response.
-platforms: ["react"]
----
-
-This guide assumes you have the basic wiring from [Resumable Streams](/docs/guides/resumable-streams) in place and focuses on what to add before serving production traffic.
-
-## Authentication and authorization
-
-The default resume endpoint serves any caller that knows the `streamId`. Treat the id as opaque, not as a credential. Bind every newly created `streamId` to the requesting user at acquire time and verify the binding on every resume.
-
-Store the binding next to the rest of your session state, or in Redis under a separate key. The example below uses a parallel `<keyPrefix>:owner:<streamId>` entry that mirrors the TTL of the underlying stream.
-
-```ts title="/lib/resumable-context.ts"
-import { createResumableStreamContext } from "assistant-stream/resumable";
-import { redis } from "@/lib/redis";
-import { store } from "@/lib/resumable-store";
-
-const OWNER_PREFIX = "aui:resumable:owner";
-const OWNER_TTL_SEC = 24 * 60 * 60;
-
-export const resumableContext = createResumableStreamContext({ store });
-
-export async function bindStreamToUser(streamId: string, userId: string) {
-  await redis.set(`${OWNER_PREFIX}:${streamId}`, userId, { EX: OWNER_TTL_SEC });
-}
-
-export async function assertStreamOwner(streamId: string, userId: string) {
-  const owner = await redis.get(`${OWNER_PREFIX}:${streamId}`);
-  if (owner !== userId) {
-    throw new Response("Not Found", { status: 404 });
-  }
-}
-```
-
-Wrap `resume` with the ownership check. Returning 404 (not 403) avoids confirming the existence of a stream the caller does not own.
-
-```ts title="/app/api/chat/resume/[streamId]/route.ts"
-import { assertStreamOwner, resumableContext } from "@/lib/resumable-context";
-import { getSessionUserId } from "@/lib/auth";
-
-export async function GET(
-  req: Request,
-  ctx: { params: Promise<{ streamId: string }> },
-) {
-  const userId = await getSessionUserId(req);
-  if (!userId) return new Response("Unauthorized", { status: 401 });
-
-  const { streamId } = await ctx.params;
-  await assertStreamOwner(streamId, userId);
-
-  const stream = await resumableContext.resume(streamId);
-  if (!stream) return new Response("Not Found", { status: 404 });
-
-  return new Response(stream, {
-    headers: { "Content-Type": "text/event-stream" },
-  });
-}
-```
-
-## `waitUntil` on serverless
-
-On Vercel and Cloudflare the request handler is torn down once the response is returned, taking the producer task with it. Without a `waitUntil` hook the persisted stream stops growing the moment the originating request unwinds, so reconnects only see the bytes that happened to land before the response flushed.
-
-On Vercel, pass `after` from `next/server`:
-
-```ts title="/lib/resumable-context.ts"
-import { after } from "next/server";
-import { createResumableStreamContext } from "assistant-stream/resumable";
-import { store } from "@/lib/resumable-store";
-
-export const resumableContext = createResumableStreamContext({
-  store,
-  waitUntil: after,
-});
-```
-
-On Cloudflare Workers, take the `ExecutionContext` from your handler and forward `ctx.waitUntil`:
-
-```ts title="/src/worker.ts"
-import { createResumableStreamContext } from "assistant-stream/resumable";
-import { store } from "./resumable-store";
-
-export default {
-  async fetch(req: Request, env: Env, ctx: ExecutionContext) {
-    const resumableContext = createResumableStreamContext({
-      store,
-      waitUntil: (promise) => ctx.waitUntil(promise),
-    });
-    return handle(req, resumableContext);
-  },
-};
-```
-
-In long-lived Node servers (a custom Express app, a container) `waitUntil` can be omitted; the producer task runs on the same event loop as the handler and is not preempted.
-
-## TTL strategy
-
-Streams expire 24 hours after the last write. The default suits typical chat workloads where a user might reload after lunch, but every deployment should pick a number deliberately.
-
-- Shorten when chunks contain sensitive payloads (PII, drafts, internal documents). A 5 to 30 minute window usually covers reload survival without leaving recoverable bytes around.
-- Extend for long-running agent tasks that may legitimately stretch past a day. Set the TTL above the worst-case task duration so the producer can still finalize.
-- Match TTLs across layers. The store TTL, the owner-binding TTL, and any signed cookie that references `streamId` should expire together; otherwise one outlives the other and either leaks or 404s unexpectedly.
-
-Configure on the store for the global default and on the context for a per-deployment override:
-
-```ts
-import {
-  createInMemoryResumableStreamStore,
-  createResumableStreamContext,
-} from "assistant-stream/resumable";
-
-const store = createInMemoryResumableStreamStore({
-  defaultTtlMs: 30 * 60 * 1000,
-});
-
-export const resumableContext = createResumableStreamContext({
-  store,
-  ttlMs: 30 * 60 * 1000,
-});
-```
-
-The Redis adapters accept the same `defaultTtlMs` option.
-
-## Multi-tenant key isolation
-
-When multiple apps or tenants share a Redis instance, set `keyPrefix` per environment so a misconfigured stream in one tenant cannot collide with, or be deleted alongside, another's. The prefix becomes the leading segment of every meta and data key.
-
-```ts title="/lib/resumable-store.ts"
-import { createClient } from "redis";
-import { createRedisResumableStreamStore } from "assistant-stream/resumable/redis";
-
-const client = createClient({ url: process.env.REDIS_URL });
-await client.connect();
-
-export const store = createRedisResumableStreamStore(client, {
-  keyPrefix: `aui:${process.env.APP_NAME}:${process.env.TENANT_ID}`,
-});
-```
-
-Per-tenant prefixes also make incident response cheaper. A `SCAN MATCH aui:app:tenant-42:*` lets you audit or purge a single tenant without touching the rest.
-
-## Observability hooks
-
-`ResumableStreamContextOptions` exposes lifecycle hooks for structured logging, metrics, and tracing. Hook exceptions and rejected promises are reported through `console.error` without affecting stream output or stored lifecycle status.
-
-```ts title="/lib/resumable-context.ts"
-import { createResumableStreamContext } from "assistant-stream/resumable";
-import { logger, metrics } from "@/lib/observability";
-import { store } from "@/lib/resumable-store";
-
-export const resumableContext = createResumableStreamContext({
-  store,
-  onAcquire: (streamId, role) => {
-    metrics.increment("resumable.acquire", { role });
-    logger.info("resumable.acquire", { streamId, role });
-  },
-  onAppend: (streamId, byteLength) => {
-    metrics.histogram("resumable.append.bytes", byteLength);
-  },
-  onFinalize: (streamId, status, error) => {
-    metrics.increment("resumable.finalize", { status });
-    logger.info("resumable.finalize", { streamId, status, error });
-  },
-  onError: (streamId, error) => {
-    const message = error instanceof Error ? error.message : String(error);
-    logger.error("resumable.error", { streamId, error: message });
-  },
-});
-```
-
-Keep synchronous hook work cheap. `onAcquire` runs on the `run()` request path for producers and consumers alike, while the remaining hooks run on the producer's streaming hot path. Returned promises are observed for failures but are not awaited.
-
-## Resource limits
-
-The in-memory store enforces three caps that the Redis adapters intentionally leave to the underlying database. Set them whenever your process can be reached by untrusted callers.
-
-```ts
-import { createInMemoryResumableStreamStore } from "assistant-stream/resumable";
-
-const store = createInMemoryResumableStreamStore({
-  maxChunkBytes: 64 * 1024,
-  maxEntriesPerStream: 5000,
-  maxStreams: 10_000,
-});
-```
-
-- `maxChunkBytes` rejects oversized writes from a misbehaving producer (a runaway tool result, a base64 blob accidentally piped through). The producer task fails fast instead of pinning memory.
-- `maxEntriesPerStream` caps the per-stream entry count. This bounds how much any single stream can grow before it starts erroring; pair it with TTLs so finalized streams clear quickly.
-- `maxStreams` caps total live streams. Useful as a backstop in shared development environments and in single-tenant containers; in serverless deployments the platform already constrains concurrency.
-
-These limits exist on the in-memory store. For Redis, configure `maxmemory` and an eviction policy on the server, and rely on application-level rate limiting upstream.
-
-## Incident response
-
-The streamId leaks through response headers, browser session storage, server access logs, and (in some setups) error reports. If you suspect any of those channels were compromised, treat all in-flight stream ids as exposed.
-
-What to log up front, so you have it when you need it:
-
-- The acquiring user id, request id, and IP for every `acquire` call (via `onAcquire`).
-- The finalize status (and any error) for every stream (via `onFinalize`).
-- The owner-binding writes and reads, with the user id and the streamId.
-
-What to rotate or invalidate during an incident:
-
-- Bump `keyPrefix` on the store. Existing streams become unreachable and new ones land under the rotated namespace.
-- Invalidate signed session cookies that reference any cached streamId.
-- Drop the owner-binding keys for affected users (`DEL aui:resumable:owner:*` scoped by user) so resumes are forced through a fresh acquire.
-- Shorten `defaultTtlMs` temporarily so any orphaned stream rolls off quickly.
-
-After rotation, reissue stream ids server-side and redirect clients through a fresh acquire; do not trust any streamId the client already holds.