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

package/.docs/raw/docs/runtimes/ag-ui/agent-state.mdx

@@ -1,124 +0,0 @@
----
-title: Agent state
-description: Read and optimistically update agent-owned state with useAgUiState and useAgUiSetState over AG-UI.
----
-
-`useAgUiState` mirrors the state your AG-UI agent owns. It updates live while the agent runs. `useAgUiSetState` lets you apply optimistic local updates that are sent with the next run.
-
-## Basic usage
-
-```tsx
-import { useAgUiState, useAgUiSetState } from "@assistant-ui/react-ag-ui";
-import { useAuiState } from "@assistant-ui/react";
-
-type ResearchState = {
-  topic: string;
-  sources: string[];
-};
-
-const state = useAgUiState<ResearchState>();
-// state: ResearchState | undefined  (latest agent state; updates live while the agent runs)
-
-const setState = useAgUiSetState<ResearchState>();
-// setState(next | (prev) => next)   (optimistic local update; sent with the NEXT run)
-
-const isRunning = useAuiState((s) => s.thread.isRunning);
-// isRunning: boolean                (whether the thread is currently running)
-```
-
-## Example
-
-Render agent state beside the chat and push an optimistic update from a control in your UI:
-
-```tsx
-"use client";
-
-import { useAgUiState, useAgUiSetState } from "@assistant-ui/react-ag-ui";
-import { useAuiState } from "@assistant-ui/react";
-import { Thread } from "@/components/assistant-ui/thread";
-
-type ResearchState = {
-  topic: string;
-  sources: string[];
-};
-
-export function ResearchAssistant() {
-  const state = useAgUiState<ResearchState>();
-  const setState = useAgUiSetState<ResearchState>();
-  const isRunning = useAuiState((s) => s.thread.isRunning);
-
-  return (
-    <div className="flex h-full">
-      <aside className="w-72 border-r p-4">
-        <h2>Research state</h2>
-        {state ? (
-          <ul>
-            <li>Topic: {state.topic}</li>
-            <li>Sources: {state.sources.join(", ") || "none"}</li>
-          </ul>
-        ) : (
-          <p>No agent state yet.</p>
-        )}
-        <button
-          type="button"
-          disabled={isRunning}
-          onClick={() =>
-            setState((prev) => ({
-              topic: prev?.topic ?? "market analysis",
-              sources: [...(prev?.sources ?? []), "sec-filings"],
-            }))
-          }
-        >
-          Prefer SEC filings
-        </button>
-        {isRunning && <p>Agent is running…</p>}
-      </aside>
-      <main className="flex-1">
-        <Thread />
-      </main>
-    </div>
-  );
-}
-```
-
-The panel re-renders as `STATE_SNAPSHOT` and `STATE_DELTA` events arrive. The button updates the local snapshot immediately; that value is included as the `state` field of the next run input.
-
-## How state is synced
-
-The AG-UI protocol delivers agent state on the wire:
-
-- `STATE_SNAPSHOT` replaces the full client-side snapshot.
-- `STATE_DELTA` applies a JSON Patch to the current snapshot.
-
-The runtime applies both client-side, so `useAgUiState` always reflects the latest merged snapshot. Calling the setter from `useAgUiSetState` updates that same local snapshot. On the next run, the runtime automatically includes it as the `state` field of the run input.
-
-This works with any AG-UI agent (Mastra, Pydantic AI, CrewAI, LangGraph via AG-UI adapters, and other AG-UI-compliant servers).
-
-## Write-back timing
-
-`useAgUiSetState` is optimistic and local first. The value reaches the agent only when the next run starts. It is not a live channel into a run that is already in progress. Use it to stage preferences, filters, or other agent-owned fields that the next turn should see.
-
-## Relationship to other state
-
-Keep the three state layers distinct:
-
-- **Your app state** stays yours (React state, URL, a store). assistant-ui does not own it.
-- **`useAuiState`** reads assistant-ui's client state (messages, composer, thread status).
-- **`useAgUiState` / `useAgUiSetState`** mirror state the **agent** owns, synced over the AG-UI wire via snapshots and deltas.
-
-Use `useAgUiState` and `useAgUiSetState` for fields your agent maintains as shared state on the protocol. Use `useAuiState` for UI that depends on the chat thread itself. Use your own state for everything else.
-
-## Next
-
-<Cards>
-  <Card
-    title="Runtime options"
-    description="useAgUiRuntime options, adapters, supported events."
-    href="/docs/runtimes/ag-ui/runtime-options"
-  />
-  <Card
-    title="Quickstart"
-    description="Minimal HttpAgent + useAgUiRuntime setup."
-    href="/docs/runtimes/ag-ui/quickstart"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/ag-ui/overview.mdx

@@ -1,70 +0,0 @@
----
-title: AG-UI Agent Runtime
-description: Wire AG-UI (Agent-User Interaction) protocol agents into a React chat UI with assistant-ui — bidirectional events, generative UI, and human-in-the-loop.
----
-
-`@assistant-ui/react-ag-ui` is a runtime adapter for the [AG-UI (Agent-User Interaction) protocol](https://github.com/ag-ui-protocol/ag-ui). It lets your assistant-ui frontend speak to any AG-UI-compliant agent server, including CopilotKit-based backends.
-
-## When to use it
-
-Pick the AG-UI runtime when:
-
-- Your backend implements the AG-UI protocol (e.g. CopilotKit agents, custom AG-UI servers).
-- You want streaming text, thinking events, reasoning events, tool calls, and state snapshots in one protocol.
-- You need agent-side state synchronization via `STATE_SNAPSHOT` and `STATE_DELTA` events.
-
-If your backend is not AG-UI-compliant, see [picking a runtime](/docs/runtimes/pick-a-runtime) for alternatives.
-
-## Architecture
-
-`@assistant-ui/react-ag-ui` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). The runtime owns AG-UI event parsing and message reconstruction; you provide an `HttpAgent` from `@ag-ui/client` and the adapter handles the wire protocol.
-
-Shared adapters (attachments, speech, dictation, feedback, history) work the same way described in [adapters](/docs/runtimes/concepts/adapters).
-
-## Requirements
-
-- An AG-UI-compatible agent server.
-- React 18 or 19.
-
-## Install
-
-<PlatformTabs>
-<Tab value="React">
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-ag-ui", "@ag-ui/client"]} />
-
-</Tab>
-<Tab value="React Native">
-
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-ag-ui", "@ag-ui/client"]} />
-
-</Tab>
-<Tab value="React Ink">
-
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-ag-ui", "@ag-ui/client", "ink", "react"]} />
-
-</Tab>
-</PlatformTabs>
-
-## Example
-
-[`examples/with-ag-ui`](https://github.com/assistant-ui/assistant-ui/tree/main/examples/with-ag-ui) shows a complete reference implementation. Or scaffold one directly:
-
-```sh
-npx assistant-ui@latest create my-app -e with-ag-ui
-```
-
-## Next
-
-<Cards>
-  <Card
-    title="Quickstart"
-    description="Minimal HttpAgent + useAgUiRuntime setup."
-    href="/docs/runtimes/ag-ui/quickstart"
-  />
-  <Card
-    title="Runtime options"
-    description="useAgUiRuntime options, adapters, events, thread list."
-    href="/docs/runtimes/ag-ui/runtime-options"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/ag-ui/quickstart.mdx

@@ -1,243 +0,0 @@
----
-title: Quickstart
-description: Minimal HttpAgent + useAgUiRuntime setup against an AG-UI server.
----
-
-Three steps to a working chat against an AG-UI agent. Assumes you have already installed the package and have an AG-UI server reachable; if not, start at [overview](/docs/runtimes/ag-ui/overview).
-
-<Steps>
-<Step>
-
-### Wire up the runtime provider
-
-Create an `HttpAgent` pointing at your AG-UI endpoint and pass it to `useAgUiRuntime`:
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="app/MyRuntimeProvider.tsx"
-"use client";
-
-import { useMemo } from "react";
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
-import { HttpAgent } from "@ag-ui/client";
-
-export function MyRuntimeProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const agent = useMemo(
-    () =>
-      new HttpAgent({
-        url: "http://localhost:8000/agent",
-      }),
-    [],
-  );
-
-  const runtime = useAgUiRuntime({ agent });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="runtime/MyRuntimeProvider.tsx"
-import { useMemo } from "react";
-import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
-import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
-import { HttpAgent } from "@ag-ui/client";
-
-export function MyRuntimeProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const agent = useMemo(
-    () =>
-      new HttpAgent({
-        url: "http://localhost:8000/agent",
-      }),
-    [],
-  );
-
-  const runtime = useAgUiRuntime({ agent });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx title="runtime/MyRuntimeProvider.tsx"
-import { useMemo } from "react";
-import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
-import { useAgUiRuntime } from "@assistant-ui/react-ag-ui";
-import { HttpAgent } from "@ag-ui/client";
-
-export function MyRuntimeProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const agent = useMemo(
-    () =>
-      new HttpAgent({
-        url: "http://localhost:8000/agent",
-      }),
-    [],
-  );
-
-  const runtime = useAgUiRuntime({ agent });
-
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-</Step>
-<Step>
-
-### Render the Thread
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="app/page.tsx"
-import { Thread } from "@/components/assistant-ui/thread";
-import { MyRuntimeProvider } from "./MyRuntimeProvider";
-
-export default function Page() {
-  return (
-    <MyRuntimeProvider>
-      <Thread />
-    </MyRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="app/index.tsx"
-import { View } from "react-native";
-import { Thread } from "@/components/assistant-ui/thread";
-import { MyRuntimeProvider } from "@/runtime/MyRuntimeProvider";
-
-export default function Page() {
-  return (
-    <MyRuntimeProvider>
-      <View style={{ flex: 1 }}>
-        <Thread />
-      </View>
-    </MyRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx title="app.tsx"
-import { Box } from "ink";
-import { Thread } from "./components/thread.js";
-import { MyRuntimeProvider } from "./runtime/MyRuntimeProvider.js";
-
-export function App() {
-  return (
-    <MyRuntimeProvider>
-      <Box flexDirection="column">
-        <Thread />
-      </Box>
-    </MyRuntimeProvider>
-  );
-}
-```
-
-</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>
-
-Once your AG-UI server is reachable, the runtime parses incoming events (`TEXT_MESSAGE_*`, `TOOL_CALL_*`, `STATE_SNAPSHOT`, etc.) into assistant-ui messages.
-
-## Showing thinking and reasoning
-
-`showThinking` (default `true`) controls whether `THINKING_*` and `REASONING_*` events render as visible reasoning in the UI:
-
-```tsx
-const runtime = useAgUiRuntime({
-  agent,
-  showThinking: false, // hide thinking blocks
-});
-```
-
-## Adding adapters
-
-Attachments, speech, dictation, feedback, history, and a custom thread list are supported via the standard adapter slots. See [adapters](/docs/runtimes/concepts/adapters):
-
-```tsx
-const runtime = useAgUiRuntime({
-  agent,
-  adapters: { attachments, history, speech, feedback },
-});
-```
-
-For multi-thread, pass `adapters.threadList` (experimental); see [runtime options](/docs/runtimes/ag-ui/runtime-options#thread-list-experimental).
-
-## Next
-
-<Cards>
-  <Card
-    title="Runtime options"
-    description="useAgUiRuntime options, adapters, events, thread list."
-    href="/docs/runtimes/ag-ui/runtime-options"
-  />
-  <Card
-    title="Pick a runtime"
-    description="Compare AG-UI to other runtime options."
-    href="/docs/runtimes/pick-a-runtime"
-  />
-</Cards>