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

package/.docs/raw/docs/runtimes/a2a/client-and-hooks.mdx

@@ -1,399 +0,0 @@
----
-title: Client and hooks
-description: A2AClient, useA2ARuntime options, hooks, task states, artifacts, errors.
----
-
-import { A2AIcon } from "@/components/icons/a2a";
-
-Deep dive on the runtime's API surface. Start with [overview](/docs/runtimes/a2a/overview) and [quickstart](/docs/runtimes/a2a/quickstart) if you have not already.
-
-## A2AClient
-
-The built-in `A2AClient` handles all communication with the A2A server: JSON serialization, SSE streaming, ProtoJSON enum normalization, and structured error handling.
-
-```ts
-import { A2AClient } from "@assistant-ui/react-a2a";
-
-const client = new A2AClient({
-  baseUrl: "https://my-agent.example.com",
-  headers: { Authorization: "Bearer <token>" },
-  tenant: "my-org",
-  extensions: ["urn:a2a:ext:my-extension"],
-  fetchOptions: { credentials: "include" },
-});
-```
-
-Pass a pre-built client to `useA2ARuntime`:
-
-```tsx
-const runtime = useA2ARuntime({ client });
-```
-
-### Client options
-
-| Option | Type | Description |
-| --- | --- | --- |
-| `baseUrl` | `string` | Base URL of the A2A server. |
-| `basePath` | `string` | Optional path prefix for API endpoints (e.g. `"/v1"`). Does not affect agent card discovery. |
-| `headers` | `Record<string, string>` or `() => Record<string, string>` | Static or dynamic headers (e.g. for auth tokens). |
-| `tenant` | `string` | Tenant ID for multi-tenant servers (prepended to URL paths). |
-| `extensions` | `string[]` | Extension URIs to negotiate via `A2A-Extensions` header. |
-| `fetchOptions` | `RequestInit` (partial) | Extra fetch options applied to every request (e.g. `{ credentials: "include" }`). `headers`, `body`, `method`, and `signal` are managed internally. |
-
-### Client methods
-
-| Method | Description |
-| --- | --- |
-| `sendMessage(message, configuration?, metadata?)` | Send a message (non-streaming). |
-| `streamMessage(message, configuration?, metadata?)` | Send a message with SSE streaming. |
-| `getTask(taskId, historyLength?)` | Get a task by ID. |
-| `listTasks(request?)` | List tasks with filtering and pagination. |
-| `cancelTask(taskId, metadata?)` | Cancel an in-progress task. |
-| `subscribeToTask(taskId)` | Subscribe to SSE updates for a task. |
-| `getAgentCard()` | Fetch the agent card from `/.well-known/agent-card.json`. |
-| `getExtendedAgentCard()` | Fetch the extended (authenticated) agent card. |
-| `createTaskPushNotificationConfig(config)` | Create a push notification config. |
-| `getTaskPushNotificationConfig(taskId, configId)` | Get a push notification config. |
-| `listTaskPushNotificationConfigs(taskId)` | List push notification configs. |
-| `deleteTaskPushNotificationConfig(taskId, configId)` | Delete a push notification config. |
-
-## useA2ARuntime options
-
-Pass either a pre-built `client` or a `baseUrl` (the runtime creates a client for you). Other options layer on top.
-
-| Option | Type | Description |
-| --- | --- | --- |
-| `client` | `A2AClient` | Pre-built A2A client instance (provide this OR `baseUrl`). |
-| `baseUrl` | `string` | A2A server URL (creates a client automatically). |
-| `basePath` | `string` | Path prefix for API endpoints. Only used with `baseUrl`. |
-| `tenant` | `string` | Tenant ID for multi-tenant servers. Only used with `baseUrl`. |
-| `headers` | `Record<string, string>` or `() => Record<string, string>` | Headers for the auto-created client. |
-| `extensions` | `string[]` | Extension URIs to negotiate. Only used with `baseUrl`. |
-| `fetchOptions` | `RequestInit` (partial) | Extra fetch options for the auto-created client (e.g. `{ credentials: "include" }`). `headers`, `body`, `method`, and `signal` are managed internally. Only used with `baseUrl`. |
-| `contextId` | `string` | Initial context ID for the conversation. |
-| `configuration` | `A2ASendMessageConfiguration` | Default send message configuration. |
-| `onError` | `(error: Error) => void` | Error callback. |
-| `onCancel` | `() => void` | Cancellation callback. |
-| `onArtifactComplete` | `(artifact: A2AArtifact) => void` | Fired when an incremental artifact finishes. |
-| `adapters.attachments` | `AttachmentAdapter` | Custom attachment handling. See [adapters](/docs/runtimes/concepts/adapters#attachment-adapter). |
-| `adapters.speech` | `SpeechSynthesisAdapter` | Text-to-speech. See [adapters](/docs/runtimes/concepts/adapters#speech-adapter). |
-| `adapters.feedback` | `FeedbackAdapter` | Feedback collection. See [adapters](/docs/runtimes/concepts/adapters#feedback-adapter). |
-| `adapters.history` | `ThreadHistoryAdapter` | Message persistence. See [adapters](/docs/runtimes/concepts/adapters#history-adapter). |
-| `adapters.threadList` | `UseA2AThreadListAdapter` | Thread switching. See [threads](/docs/runtimes/concepts/threads). |
-
-## Hooks
-
-### Task state
-
-`useA2ATask` returns the current A2A task object, including task state and status message.
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import { useA2ATask } from "@assistant-ui/react-a2a";
-
-function TaskStatus() {
-  const task = useA2ATask();
-  if (!task) return null;
-  return (
-    <div>
-      Task {task.id}: {task.status.state}
-    </div>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import { useA2ATask } from "@assistant-ui/react-a2a";
-import { Text, View } from "react-native";
-
-function TaskStatus() {
-  const task = useA2ATask();
-  if (!task) return null;
-  return (
-    <View>
-      <Text>
-        Task {task.id}: {task.status.state}
-      </Text>
-    </View>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import { useA2ATask } from "@assistant-ui/react-a2a";
-import { Text } from "ink";
-
-function TaskStatus() {
-  const task = useA2ATask();
-  if (!task) return null;
-  return (
-    <Text>
-      Task {task.id}: {task.status.state}
-    </Text>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-### Artifacts list
-
-`useA2AArtifacts` returns the artifacts generated by the current task.
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import { useA2AArtifacts } from "@assistant-ui/react-a2a";
-
-function ArtifactList() {
-  const artifacts = useA2AArtifacts();
-  return (
-    <ul>
-      {artifacts.map((artifact) => (
-        <li key={artifact.artifactId}>
-          {artifact.name}: {artifact.parts.length} parts
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import { useA2AArtifacts } from "@assistant-ui/react-a2a";
-import { Text, View } from "react-native";
-
-function ArtifactList() {
-  const artifacts = useA2AArtifacts();
-  return (
-    <View>
-      {artifacts.map((artifact) => (
-        <Text key={artifact.artifactId}>
-          {artifact.name}: {artifact.parts.length} parts
-        </Text>
-      ))}
-    </View>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import { useA2AArtifacts } from "@assistant-ui/react-a2a";
-import { Box, Text } from "ink";
-
-function ArtifactList() {
-  const artifacts = useA2AArtifacts();
-  return (
-    <Box flexDirection="column">
-      {artifacts.map((artifact) => (
-        <Text key={artifact.artifactId}>
-          {artifact.name}: {artifact.parts.length} parts
-        </Text>
-      ))}
-    </Box>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-### Agent card
-
-`useA2AAgentCard` returns the agent card fetched from the server on initialization.
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx
-import { useA2AAgentCard } from "@assistant-ui/react-a2a";
-
-function AgentInfo() {
-  const card = useA2AAgentCard();
-  if (!card) return null;
-  return (
-    <div>
-      <h3>{card.name}</h3>
-      <p>{card.description}</p>
-      <div>Skills: {card.skills.map((s) => s.name).join(", ")}</div>
-    </div>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx
-import { useA2AAgentCard } from "@assistant-ui/react-a2a";
-import { Text, View } from "react-native";
-
-function AgentInfo() {
-  const card = useA2AAgentCard();
-  if (!card) return null;
-  return (
-    <View>
-      <Text>{card.name}</Text>
-      <Text>{card.description}</Text>
-      <Text>Skills: {card.skills.map((s) => s.name).join(", ")}</Text>
-    </View>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx
-import { useA2AAgentCard } from "@assistant-ui/react-a2a";
-import { Box, Text } from "ink";
-
-function AgentInfo() {
-  const card = useA2AAgentCard();
-  if (!card) return null;
-  return (
-    <Box flexDirection="column">
-      <Text bold>{card.name}</Text>
-      <Text>{card.description}</Text>
-      <Text>Skills: {card.skills.map((s) => s.name).join(", ")}</Text>
-    </Box>
-  );
-}
-```
-
-</Tab>
-</PlatformTabs>
-
-## Task states
-
-The A2A protocol defines 9 task states. The runtime maps them to assistant-ui message statuses:
-
-| A2A task state | Description | Message status |
-| --- | --- | --- |
-| `unspecified` | Unknown or default state. | `running` |
-| `submitted` | Task acknowledged. | `running` |
-| `working` | Task in progress. | `running` |
-| `completed` | Task finished. | `complete` |
-| `failed` | Task errored. | `incomplete (error)` |
-| `canceled` | Task cancelled. | `incomplete (cancelled)` |
-| `rejected` | Agent declined task. | `incomplete (error)` |
-| `input_required` | Agent needs user input. | `requires-action` |
-| `auth_required` | Authentication needed. | `requires-action` |
-
-<Callout type="info">
-When a task enters `input_required`, the user can continue the conversation normally. The runtime sends the next message with the same `taskId` to resume the task.
-</Callout>
-
-## Artifacts
-
-A2A agents can produce artifacts (files, code, data) alongside their responses. Artifacts are accumulated during streaming and accessible via `useA2AArtifacts`.
-
-The runtime supports:
-
-- **Incremental artifact streaming** via `append` mode.
-- **Artifact completion notification** via the `onArtifactComplete` callback.
-- **Automatic reset** of artifacts on each new run.
-
-```tsx
-const runtime = useA2ARuntime({
-  baseUrl: "http://localhost:9999",
-  onArtifactComplete: (artifact) => {
-    console.log("Artifact ready:", artifact.name);
-  },
-});
-```
-
-## Streaming vs non-streaming
-
-The runtime automatically selects the communication mode based on the agent's capabilities:
-
-- If the agent card indicates `capabilities.streaming: true` (or the field is unset), the runtime uses `POST /message:stream` with SSE.
-- If `capabilities.streaming: false`, the runtime falls back to `POST /message:send`.
-
-## Error handling
-
-The client throws `A2AError` instances with structured error information following the `google.rpc.Status` format:
-
-```tsx
-import { A2AError } from "@assistant-ui/react-a2a";
-
-const runtime = useA2ARuntime({
-  baseUrl: "http://localhost:9999",
-  onError: (error) => {
-    if (error instanceof A2AError) {
-      console.log(error.code); // HTTP status code
-      console.log(error.status); // e.g. "NOT_FOUND"
-      console.log(error.details); // google.rpc.ErrorInfo details
-    }
-  },
-});
-```
-
-## Multi-tenancy
-
-For multi-tenant A2A servers, pass a `tenant` option:
-
-```ts
-const client = new A2AClient({
-  baseUrl: "https://agent.example.com",
-  tenant: "my-org",
-});
-```
-
-This prepends `/{tenant}` to all API paths (e.g. `/my-org/message:send`).
-
-## Feature support
-
-| Feature | Supported |
-| --- | --- |
-| Streaming (SSE) | Yes |
-| Non-streaming fallback | Yes |
-| All 9 task states | Yes |
-| Artifacts (text, data, file) | Yes |
-| Agent card discovery | Yes |
-| Multi-tenancy | Yes |
-| Structured errors | Yes |
-| Push notifications CRUD | Yes |
-| Extension negotiation | Yes |
-| Task cancellation | Yes |
-| Message editing | Yes |
-| Message reload | Yes |
-| History persistence | Via [history adapter](/docs/runtimes/concepts/adapters#history-adapter) |
-| Thread list management | Via [thread list adapter](/docs/runtimes/concepts/threads) |
-
-## Related
-
-<Cards>
-  <Card
-    icon={<A2AIcon width={20} height={20} />}
-    title="A2A overview"
-    description="What A2A is and when to pick it."
-    href="/docs/runtimes/a2a/overview"
-  />
-  <Card
-    title="Quickstart"
-    description="Minimal runtime + Thread setup."
-    href="/docs/runtimes/a2a/quickstart"
-  />
-  <Card
-    title="Adapters"
-    description="Attachments, speech, feedback, history, threads."
-    href="/docs/runtimes/concepts/adapters"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/a2a/overview.mdx

@@ -1,60 +0,0 @@
----
-title: A2A Agent Runtime
-description: Connect any A2A v1.0 protocol-compliant agent server to a React chat UI with assistant-ui — full streaming, tool calls, and message metadata supported.
----
-
-`@assistant-ui/react-a2a` is a runtime adapter for the [A2A (Agent-to-Agent) v1.0 protocol](https://github.com/a2aproject/A2A). Use it when your backend speaks A2A; the adapter handles the wire protocol so you can focus on the UI.
-
-## When to use it
-
-Pick the A2A runtime when:
-
-- You have an A2A v1.0 compatible agent server, or you are building one and want a reference client.
-- You want streaming task state, artifacts, and the protocol's full state machine surfaced in the UI.
-- You need multi-tenant or extension-aware A2A clients.
-
-If your backend is not A2A-compliant, see [picking a runtime](/docs/runtimes/pick-a-runtime) for alternatives.
-
-## Architecture
-
-`@assistant-ui/react-a2a` is layered on `ExternalStoreRuntime` (see [architecture](/docs/runtimes/concepts/architecture)). Features that ship as runtime adapters (attachments, speech, feedback, history, threads) work the same way they do everywhere else; see [adapters](/docs/runtimes/concepts/adapters).
-
-## Requirements
-
-- An A2A v1.0 compatible agent server.
-- React 18 or 19.
-
-## Install
-
-<PlatformTabs>
-<Tab value="React">
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-a2a"]} />
-
-</Tab>
-<Tab value="React Native">
-
-<InstallCommand expo={["@assistant-ui/react-native", "@assistant-ui/react-a2a"]} />
-
-</Tab>
-<Tab value="React Ink">
-
-<InstallCommand npm={["@assistant-ui/react-ink", "@assistant-ui/react-a2a", "ink", "react"]} />
-
-</Tab>
-</PlatformTabs>
-
-## Next
-
-<Cards>
-  <Card
-    title="Quickstart"
-    description="Minimal runtime setup with a Thread component."
-    href="/docs/runtimes/a2a/quickstart"
-  />
-  <Card
-    title="Client and hooks"
-    description="A2AClient, useA2ARuntime options, hooks reference, task states, artifacts."
-    href="/docs/runtimes/a2a/client-and-hooks"
-  />
-</Cards>

package/.docs/raw/docs/runtimes/a2a/quickstart.mdx

@@ -1,216 +0,0 @@
----
-title: Quickstart
-description: Minimal runtime and Thread setup against an A2A server.
----
-
-Three steps to a working chat against an A2A server. Assumes you have already installed the package and have an A2A v1.0 server reachable; if not, start at [overview](/docs/runtimes/a2a/overview).
-
-<Steps>
-<Step>
-
-### Wire up the runtime provider
-
-<PlatformTabs>
-<Tab value="React">
-
-```tsx title="app/MyRuntimeProvider.tsx"
-"use client";
-
-import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useA2ARuntime } from "@assistant-ui/react-a2a";
-
-export function MyRuntimeProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const runtime = useA2ARuntime({
-    baseUrl: "http://localhost:9999",
-  });
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Native">
-
-```tsx title="runtime/MyRuntimeProvider.tsx"
-import { AssistantRuntimeProvider } from "@assistant-ui/react-native";
-import { useA2ARuntime } from "@assistant-ui/react-a2a";
-
-export function MyRuntimeProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const runtime = useA2ARuntime({
-    baseUrl: "http://localhost:9999",
-  });
-  return (
-    <AssistantRuntimeProvider runtime={runtime}>
-      {children}
-    </AssistantRuntimeProvider>
-  );
-}
-```
-
-</Tab>
-<Tab value="React Ink">
-
-```tsx title="runtime/MyRuntimeProvider.tsx"
-import { AssistantRuntimeProvider } from "@assistant-ui/react-ink";
-import { useA2ARuntime } from "@assistant-ui/react-a2a";
-
-export function MyRuntimeProvider({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  const runtime = useA2ARuntime({
-    baseUrl: "http://localhost:9999",
-  });
-  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 A2A server is reachable, the runtime negotiates streaming vs non-streaming based on the agent card's `capabilities.streaming` flag and starts forwarding messages.
-
-## Auth and headers
-
-Pass static or dynamic headers when your server expects auth:
-
-```tsx
-const runtime = useA2ARuntime({
-  baseUrl: "http://localhost:9999",
-  headers: async () => ({
-    Authorization: `Bearer ${await getAccessToken()}`,
-  }),
-});
-```
-
-## Adding adapters
-
-Attachments, speech, feedback, history, and a custom thread list are all supported via the standard adapter slots. See [adapters](/docs/runtimes/concepts/adapters) for the contracts; pass them on `useA2ARuntime`:
-
-```tsx
-const runtime = useA2ARuntime({
-  baseUrl: "http://localhost:9999",
-  adapters: { attachments, history, speech, feedback },
-});
-```
-
-For multi-thread, see [threads](/docs/runtimes/concepts/threads) and pass `adapters.threadList`.
-
-## Next
-
-<Cards>
-  <Card
-    title="Client and hooks"
-    description="A2AClient, useA2ARuntime options, hooks reference, task states, artifacts."
-    href="/docs/runtimes/a2a/client-and-hooks"
-  />
-  <Card
-    title="Pick a runtime"
-    description="Compare A2A to other runtime options."
-    href="/docs/runtimes/pick-a-runtime"
-  />
-</Cards>