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

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

@@ -1,393 +0,0 @@
----
-title: "Part 3: Approval UI"
-description: Add human-in-the-loop approval for tool calls.
----
-
-## Background: LangGraph implementation details
-
-import Image from "next/image";
-import approval from "./images/stockbroker-langgraph.png";
-
-<Image
-  src={approval}
-  alt="LangChain LangGraph"
-  width={600}
-  className="mx-auto rounded-lg border shadow"
-/>
-
-Our LangGraph backend interrupts the `purchase_stock` tool execution in order to ensure the user confirms the purchase. The user confirms the purchase by submitting a tool message with the `approve` field set to `true`.
-
-```ts title="assistant-ui-stockbroker/backend/src/index.ts" {6,18-19,32-35}
-const purchaseApproval = async (state: typeof GraphAnnotation.State) => {
-  const { messages } = state;
-  const lastMessage = messages[messages.length - 1];
-  if (!(lastMessage instanceof ToolMessage)) {
-    // Interrupt the node to request permission to execute the purchase.
-    throw new NodeInterrupt("Please confirm the purchase before executing.");
-  }
-};
-
-const shouldExecutePurchase = (state: typeof GraphAnnotation.State) => {
-  const { messages } = state;
-  const lastMessage = messages[messages.length - 1];
-  if (!(lastMessage instanceof ToolMessage)) {
-    // Interrupt the node to request permission to execute the purchase.
-    throw new NodeInterrupt("Please confirm the purchase before executing.");
-  }
-
-  const { approve } = JSON.parse(lastMessage.content as string);
-  return approve ? "execute_purchase" : "agent";
-};
-
-const workflow = new StateGraph(GraphAnnotation)
-  .addNode("agent", callModel)
-  .addEdge(START, "agent")
-  .addNode("tools", toolNode)
-  .addNode("prepare_purchase_details", preparePurchaseDetails)
-  .addNode("purchase_approval", purchaseApproval)
-  .addNode("execute_purchase", executePurchase)
-  .addEdge("prepare_purchase_details", "purchase_approval")
-  .addEdge("execute_purchase", END)
-  .addEdge("tools", "agent")
-  .addConditionalEdges("purchase_approval", shouldExecutePurchase, [
-    "agent",
-    "execute_purchase",
-  ])
-  .addConditionalEdges("agent", shouldContinue, [
-    "tools",
-    END,
-    "prepare_purchase_details",
-  ]);
-```
-
-## Add approval UI
-
-We create a new file under `/components/tools/purchase-stock/PurchaseStockTool.tsx` to define the tool.
-
-First, we define the tool arguments and result types:
-
-```ts title="@/components/tools/purchase-stock/PurchaseStockTool.tsx"
-type PurchaseStockArgs = {
-  ticker: string;
-  companyName: string;
-  quantity: number;
-  maxPurchasePrice: number;
-};
-
-type PurchaseStockResult = {
-  approve?: boolean;
-  cancelled?: boolean;
-  error?: string;
-};
-```
-
-Then we define a tool UI renderer:
-
-```tsx title="@/components/tools/purchase-stock/PurchaseStockTool.tsx"
-"use client";
-
-import { TransactionConfirmationPending } from "./transaction-confirmation-pending";
-import { TransactionConfirmationFinal } from "./transaction-confirmation-final";
-import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
-
-export const PurchaseStockToolUI: ToolCallMessagePartComponent<
-  PurchaseStockArgs,
-  string
-> = function PurchaseStockUI({ args, result, status, addResult }) {
-  const handleReject = async () => {
-    addResult(JSON.stringify({ approve: false }));
-  };
-
-  const handleConfirm = async () => {
-    addResult(JSON.stringify({ approve: true }));
-  };
-
-  return (
-    <div className="mb-4 flex flex-col items-center gap-2">
-      <div>
-        <pre className="whitespace-pre-wrap break-all text-center">
-          purchase_stock({JSON.stringify(args)})
-        </pre>
-      </div>
-      {!result && status.type !== "running" && (
-        <TransactionConfirmationPending
-          {...args}
-          onConfirm={handleConfirm}
-          onReject={handleReject}
-        />
-      )}
-    </div>
-  );
-};
-```
-
-Finally, we add a `TransactionConfirmationPending` component to ask for approval.
-
-This requires shadcn/ui's `Card` and `Button` components. We will install them as a dependency.
-
-<InstallCommand shadcn={["card", "button"]} />
-
-Then create a new file under `/components/tools/purchase-stock/transaction-confirmation-pending.tsx` to define the approval UI.
-
-```tsx title="@/components/tools/purchase-stock/transaction-confirmation-pending.tsx"
-"use client";
-
-import { CheckIcon, XIcon } from "lucide-react";
-
-import { Button } from "@/components/ui/button";
-import {
-  Card,
-  CardContent,
-  CardFooter,
-  CardHeader,
-  CardTitle,
-} from "@/components/ui/card";
-
-type TransactionConfirmation = {
-  ticker: string;
-  companyName: string;
-  quantity: number;
-  maxPurchasePrice: number;
-  onConfirm: () => void;
-  onReject: () => void;
-};
-
-export function TransactionConfirmationPending(props: TransactionConfirmation) {
-  const {
-    ticker,
-    companyName,
-    quantity,
-    maxPurchasePrice,
-    onConfirm,
-    onReject,
-  } = props;
-
-  return (
-    <Card className="mx-auto w-full max-w-md">
-      <CardHeader>
-        <CardTitle className="text-2xl font-bold">
-          Confirm Transaction
-        </CardTitle>
-      </CardHeader>
-      <CardContent className="space-y-4">
-        <div className="grid grid-cols-2 gap-2">
-          <p className="text-muted-foreground text-sm font-medium">Ticker:</p>
-          <p className="text-sm font-bold">{ticker}</p>
-          <p className="text-muted-foreground text-sm font-medium">Company:</p>
-          <p className="text-sm">{companyName}</p>
-          <p className="text-muted-foreground text-sm font-medium">Quantity:</p>
-          <p className="text-sm">{quantity} shares</p>
-          <p className="text-muted-foreground text-sm font-medium">
-            Max Purchase Price:
-          </p>
-          <p className="text-sm">${maxPurchasePrice?.toFixed(2)}</p>
-        </div>
-        <div className="bg-muted rounded-md p-3">
-          <p className="text-sm font-medium">Total Maximum Cost:</p>
-          <p className="text-lg font-bold">
-            ${(quantity * maxPurchasePrice)?.toFixed(2)}
-          </p>
-        </div>
-      </CardContent>
-      <CardFooter className="flex justify-end">
-        <Button variant="outline" onClick={onReject}>
-          <XIcon className="mr-2 h-4 w-4" />
-          Reject
-        </Button>
-        <Button onClick={onConfirm}>
-          <CheckIcon className="mr-2 h-4 w-4" />
-          Confirm
-        </Button>
-      </CardFooter>
-    </Card>
-  );
-}
-```
-
-### Bind approval UI
-
-```tsx title="@/app/page.tsx" {1-5,12}
-"use client";
-
-import { Thread } from "@/components/assistant-ui/thread";
-import { PriceSnapshotToolUI } from "@/components/tools/price-snapshot/PriceSnapshotTool";
-import { PurchaseStockToolUI } from "@/components/tools/purchase-stock/PurchaseStockTool";
-import { AuiConfig, AuiProvider, defineToolkit, Tools, useAui } from "@assistant-ui/react";
-
-const toolkit = defineToolkit({
-  price_snapshot: {
-    type: "backend",
-    render: PriceSnapshotToolUI,
-  },
-  purchase_stock: {
-    type: "backend",
-    render: PurchaseStockToolUI,
-  },
-});
-
-export default function Home() {
-  const aui = useAui();
-  const config = AuiConfig({ tools: Tools({ toolkit }) });
-  return (
-    <AuiProvider extends={aui} config={config}>
-      <Thread />
-    </AuiProvider>
-  );
-}
-```
-
-### Try it out!
-
-Ask the assistant to buy 5 shares of Tesla. You should see the following appear:
-
-import purchase from "./images/acme-approve.png";
-
-<Image
-  src={purchase}
-  alt="Approval UI"
-  width={600}
-  className="mx-auto rounded-lg border shadow"
-/>
-
-## Add `TransactionConfirmationFinal` to show approval result
-
-We will add a component to display the approval result.
-
-```ts title="@/components/tools/purchase-stock/transaction-confirmation-final.tsx"
-"use client";
-
-import { CheckCircle } from "lucide-react";
-
-import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
-
-type TransactionConfirmation = {
-  ticker: string;
-  companyName: string;
-  quantity: number;
-  maxPurchasePrice: number;
-};
-
-export function TransactionConfirmationFinal(props: TransactionConfirmation) {
-  const { ticker, companyName, quantity, maxPurchasePrice } = props;
-
-  return (
-    <Card className="mx-auto w-full max-w-md">
-      <CardHeader className="text-center">
-        <CheckCircle className="mx-auto mb-4 h-16 w-16 text-green-500" />
-        <CardTitle className="text-2xl font-bold text-green-700">
-          Transaction Confirmed
-        </CardTitle>
-      </CardHeader>
-      <CardContent className="space-y-4">
-        <div className="rounded-md border border-green-200 bg-green-50 p-4">
-          <h3 className="mb-2 text-lg font-semibold text-green-800">
-            Purchase Summary
-          </h3>
-          <div className="grid grid-cols-2 gap-2 text-sm">
-            <p className="font-medium text-green-700">Ticker:</p>
-            <p className="font-bold text-green-900">{ticker}</p>
-            <p className="font-medium text-green-700">Company:</p>
-            <p className="text-green-900">{companyName}</p>
-            <p className="font-medium text-green-700">Quantity:</p>
-            <p className="text-green-900">{quantity} shares</p>
-            <p className="font-medium text-green-700">Price per Share:</p>
-            <p className="text-green-900">${maxPurchasePrice?.toFixed(2)}</p>
-          </div>
-        </div>
-        <div className="rounded-md border border-green-300 bg-green-100 p-4">
-          <p className="text-lg font-semibold text-green-800">Total Cost:</p>
-          <p className="text-2xl font-bold text-green-900">
-            ${(quantity * maxPurchasePrice)?.toFixed(2)}
-          </p>
-        </div>
-        <p className="text-center text-sm text-green-600">
-          Your purchase of {quantity} shares of {companyName} ({ticker}) has
-          been successfully processed.
-        </p>
-      </CardContent>
-    </Card>
-  );
-}
-```
-
-### Update `PurchaseStockTool`
-
-We will import the new `<TransactionConfirmationFinal />` component and use it in the `render` function whenever an approval result is available.
-
-```tsx title="@/components/tools/purchase-stock/PurchaseStockTool.tsx" {3,25-30,37-42}
-"use client";
-
-import { TransactionConfirmationPending } from "./transaction-confirmation-pending";
-import { TransactionConfirmationFinal } from "./transaction-confirmation-final";
-import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
-
-type PurchaseStockArgs = {
-  ticker: string;
-  companyName: string;
-  quantity: number;
-  maxPurchasePrice: number;
-};
-
-type PurchaseStockResult = {
-  approve?: boolean;
-  cancelled?: boolean;
-  error?: string;
-};
-
-export const PurchaseStockToolUI: ToolCallMessagePartComponent<
-  PurchaseStockArgs,
-  string
-> = function PurchaseStockUI({ args, result, status, addResult }) {
-  let resultObj: PurchaseStockResult;
-  try {
-    resultObj = result ? JSON.parse(result) : {};
-  } catch (e) {
-    resultObj = { error: result! };
-  }
-
-  const handleReject = () => {
-    addResult(JSON.stringify({ approve: false }));
-  };
-
-  const handleConfirm = async () => {
-    addResult(JSON.stringify({ approve: true }));
-  };
-
-  return (
-    <div className="mb-4 flex flex-col items-center gap-2">
-      <div>
-        <pre className="whitespace-pre-wrap break-all text-center">
-          purchase_stock({JSON.stringify(args)})
-        </pre>
-      </div>
-      {!result && status.type !== "running" && (
-        <TransactionConfirmationPending
-          {...args}
-          onConfirm={handleConfirm}
-          onReject={handleReject}
-        />
-      )}
-      {resultObj.approve && <TransactionConfirmationFinal {...args} />}
-      {resultObj.approve === false && (
-        <pre className="font-bold text-red-600">User rejected purchase</pre>
-      )}
-      {resultObj.cancelled && (
-        <pre className="font-bold text-red-600">Cancelled</pre>
-      )}
-    </div>
-  );
-};
-```
-
-### Try it out!
-
-Confirm the purchase of shares. You should see the approval confirmation UI appear.
-
-import purchase2 from "./images/acme-confirmed.png";
-
-<Image
-  src={purchase2}
-  alt="Approval result"
-  width={600}
-  className="mx-auto rounded-lg border shadow"
-/>

package/.docs/raw/docs/runtimes/opencode/hooks.mdx

@@ -1,194 +0,0 @@
----
-title: Hooks
-description: Permissions, questions, session state, runtime extras.
----
-
-import { OpenCodeIcon } from "@/components/icons/opencode";
-
-OpenCode-specific React hooks for interacting with the running session. All hooks must be used inside the runtime context (a tree wrapped in `AssistantRuntimeProvider` from a `useOpenCodeRuntime` setup).
-
-## Permissions
-
-OpenCode pauses tool execution to ask the user for permission (e.g. running shell commands, writing files). Permissions linked to a tool call are projected into assistant-ui's standard tool approval contract, so the default `ToolFallback` renders working **Allow**, **Always allow**, and **Deny** actions without a custom permission component. The always option only appears when OpenCode offers patterns to persist.
-
-`useOpenCodePermissions` remains available for custom tool renderers and permission requests that are not linked to a tool call. It returns the pending permission requests and a reply function:
-
-```tsx
-import { useOpenCodePermissions } from "@assistant-ui/react-opencode";
-
-function PermissionPrompt() {
-  const { pending, reply } = useOpenCodePermissions();
-
-  return pending.map((req) => (
-    <div key={req.id}>
-      <p>
-        Allow <code>{req.toolName}</code>: {req.title ?? req.permission}?
-      </p>
-      <button onClick={() => reply(req.id, "once")}>Allow once</button>
-      <button onClick={() => reply(req.id, "always")}>Always allow</button>
-      <button onClick={() => reply(req.id, "reject")}>Reject</button>
-    </div>
-  ));
-}
-```
-
-Return shape:
-
-| Field | Type | Description |
-| --- | --- | --- |
-| `pending` | `OpenCodePermissionRequest[]` | Permission requests waiting for a reply. |
-| `reply` | `(id, response) => Promise<void>` | Send a reply for a pending permission. |
-
-Reply values:
-
-| Reply | Meaning |
-| --- | --- |
-| `"once"` | Approve this single permission request. |
-| `"always"` | Approve this permission and remember the choice. |
-| `"reject"` | Deny the permission; the tool call is cancelled. |
-
-## Questions
-
-OpenCode can ask interactive questions during a run. `useOpenCodeQuestions` returns the pending questions as an array:
-
-```tsx
-import {
-  useOpenCodeQuestions,
-  useOpenCodeRuntimeExtras,
-} from "@assistant-ui/react-opencode";
-
-function QuestionPrompt() {
-  const questions = useOpenCodeQuestions();
-  const { replyToQuestion, rejectQuestion } = useOpenCodeRuntimeExtras();
-
-  return questions.map((req) => (
-    <div key={req.id}>
-      <p>{req.text}</p>
-      <button
-        onClick={() =>
-          replyToQuestion(req.id, [
-            /* QuestionAnswer[] from @opencode-ai/sdk */
-          ])
-        }
-      >
-        Answer
-      </button>
-      <button onClick={() => rejectQuestion(req.id)}>Skip</button>
-    </div>
-  ));
-}
-```
-
-To reply, use `replyToQuestion(id, answers)` or `rejectQuestion(id)` from [`useOpenCodeRuntimeExtras`](#runtime-extras).
-
-## Session
-
-`useOpenCodeSession` returns the current OpenCode `Session` object (server-side session metadata):
-
-```tsx
-import { useOpenCodeSession } from "@assistant-ui/react-opencode";
-
-function SessionInfo() {
-  const session = useOpenCodeSession();
-  if (!session) return null;
-  return <div>Session: {session.id}</div>;
-}
-```
-
-## Thread state
-
-`useOpenCodeThreadState` returns the full projected thread state (messages, run state, interactions, sync metadata). Use it for advanced custom views; most apps don't need it.
-
-```tsx
-import { useOpenCodeThreadState } from "@assistant-ui/react-opencode";
-
-function RunStatus() {
-  const state = useOpenCodeThreadState();
-  return <div>Run: {state.runState.type}</div>;
-}
-```
-
-The returned `OpenCodeThreadState` includes:
-
-- `sessionId`, `session`, `sessionStatus`, `loadState`, `runState`
-- `messageOrder`, `messagesById`, `pendingUserMessages`
-- `childSessionsById` (OpenCode `task` child-session projections keyed by session ID)
-- `interactions.permissions` (pending + resolved), `interactions.questions` (pending + answered + rejected)
-- `unhandledEvents`, `sync` timestamps
-
-You can also pass a selector to read a specific slice:
-
-```tsx
-const isStreaming = useOpenCodeThreadState((s) => s.runState.type === "streaming");
-```
-
-## Runtime extras
-
-`useOpenCodeRuntimeExtras` exposes session-level imperative actions:
-
-```tsx
-import { useOpenCodeRuntimeExtras } from "@assistant-ui/react-opencode";
-
-function SessionActions() {
-  const {
-    fork,
-    revert,
-    unrevert,
-    cancel,
-    refresh,
-    replyToPermission,
-    replyToQuestion,
-    rejectQuestion,
-  } = useOpenCodeRuntimeExtras();
-  // ...
-}
-```
-
-| Action | Description |
-| --- | --- |
-| `fork(messageId)` | Create a new session forked from the given message; returns the new session id. |
-| `revert(messageId)` | Revert the session to the state at the given message. |
-| `unrevert()` | Undo the last revert. |
-| `cancel()` | Cancel an in-flight run. |
-| `refresh()` | Force re-fetch of session messages. |
-| `replyToPermission(id, response)` | Reply to a permission request (`"once"`, `"always"`, `"reject"`). |
-| `replyToQuestion(id, answers)` | Answer a pending question. |
-| `rejectQuestion(id)` | Reject a pending question. |
-
-`useOpenCodePermissions` and `useOpenCodeQuestions` are sugar over `replyToPermission` / `replyToQuestion` / `rejectQuestion` plus the `pending` slices of state.
-
-## Lower-level building blocks
-
-For custom integrations that bypass `useOpenCodeRuntime`:
-
-| Export | Purpose |
-| --- | --- |
-| `OpenCodeEventSource` | Wraps the OpenCode server's event stream into a typed subscription. |
-| `OpenCodeThreadController` | Per-session controller managing message state. |
-| `createOpenCodeThreadState`, `reduceOpenCodeThreadState` | Pure state reducers if you want to drive the state machine yourself. |
-| `projectOpenCodeThreadMessages` | Project raw OpenCode messages into assistant-ui thread messages. |
-| `createOpencodeClient` (re-exported from `@opencode-ai/sdk`) | Build a client with custom config. |
-
-These are only needed for advanced cases; most apps should use `useOpenCodeRuntime` directly.
-
-## Related
-
-<Cards>
-  <Card
-    icon={<OpenCodeIcon width={20} height={20} />}
-    title="OpenCode overview"
-    description="What OpenCode is and when to pick it."
-    href="/docs/runtimes/opencode/overview"
-  />
-  <Card
-    title="Quickstart"
-    description="Minimal runtime + Thread setup."
-    href="/docs/runtimes/opencode/quickstart"
-  />
-  <Card
-    icon={<OpenCodeIcon width={20} height={20} />}
-    title="OpenCode docs"
-    description="The OpenCode server itself."
-    href="https://opencode.ai/"
-  />
-</Cards>

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

@@ -1,58 +0,0 @@
----
-title: OpenCode Runtime
-description: Build a React chat UI for OpenCode coding agents with assistant-ui — streaming, tool calls, file edits, and terminal output rendered in chat.
----
-
-`@assistant-ui/react-opencode` is a runtime adapter for [OpenCode](https://opencode.ai/), an open-source AI coding agent. It wires the OpenCode server's session and event APIs into an assistant-ui thread, including tool permissions, interactive questions, and session state.
-
-<Callout type="warn">
-This adapter is at v0.0.3 and is experimental. The runtime API and exported hooks may change without notice.
-</Callout>
-
-## When to use it
-
-Pick the OpenCode runtime when:
-
-- You are building a UI on top of an OpenCode agent server.
-- You need first-class support for OpenCode's permission and question flows.
-- You want session-aware features: fork, revert, unrevert, refresh.
-
-If your backend is not OpenCode-based, see [picking a runtime](/docs/runtimes/pick-a-runtime) for alternatives.
-
-## Architecture
-
-`@assistant-ui/react-opencode` is layered on `ExternalStoreRuntime` plus a `RemoteThreadList` for session-backed thread management (see [architecture](/docs/runtimes/concepts/architecture)). OpenCode sessions map to assistant-ui threads; the runtime subscribes to a server-sent event stream and projects messages into the thread.
-
-## Requirements
-
-- A running [OpenCode](https://opencode.ai/) server (defaults to `http://localhost:4096`).
-- React 18 or 19.
-
-## Sub-agent conversations
-
-OpenCode `task` tool calls expose their child session through tool metadata. The runtime loads those child sessions, keeps them synchronized from the same OpenCode event stream, and projects their transcripts into `ToolCallMessagePart.messages`. Parallel and recursively nested tasks are supported.
-
-Loading is eager, not keyed to what a renderer displays. Once a thread is subscribed, every `task` part in its transcript fetches its child session, and each child does the same for its own nested tasks, so a long session with many task calls fetches every sub-agent transcript whether or not any of them is expanded. Each child session is fetched once and then kept current from the event stream, so re-subscribing a thread does not refetch it.
-
-A `task` part carries `messages` only once its child session has loaded. While the child is still loading, the part projects as an ordinary tool call, so an empty `messages` array always means the sub-agent produced nothing rather than that its transcript is still in flight.
-
-Use assistant-ui's [`MessagePartPrimitive.Messages`](/docs/tools/multi-agent) inside a `task` tool renderer to display the child conversation. Nested conversations are read-only and inherit the parent thread's tool renderers.
-
-## Install
-
-<InstallCommand npm={["@assistant-ui/react", "@assistant-ui/react-opencode", "@opencode-ai/sdk"]} />
-
-## Next
-
-<Cards>
-  <Card
-    title="Quickstart"
-    description="Minimal useOpenCodeRuntime setup against a local OpenCode server."
-    href="/docs/runtimes/opencode/quickstart"
-  />
-  <Card
-    title="Hooks"
-    description="Permissions, questions, session state, runtime extras."
-    href="/docs/runtimes/opencode/hooks"
-  />
-</Cards>