@assistant-ui/mcp-docs-server 0.1.30 → 0.1.32

package/.docs/organized/code-examples/with-mcp.md

@@ -0,0 +1,748 @@
+# Example: with-mcp
+
+## app/app/api/chat/route.ts
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { frontendTools } from "@assistant-ui/react-ai-sdk";
+import { convertToModelMessages, streamText } from "ai";
+
+export const maxDuration = 30;
+
+export async function POST(req: Request) {
+  const { messages, system, tools } = await req.json();
+  const result = streamText({
+    model: openai("gpt-5.4-nano"),
+    messages: await convertToModelMessages(messages),
+    system,
+    tools: { ...frontendTools(tools) },
+  });
+  return result.toUIMessageStreamResponse();
+}
+
+```
+
+## app/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/app/layout.tsx
+
+```tsx
+import type { ReactNode } from "react";
+import "./globals.css";
+
+export const metadata = {
+  title: "react-mcp",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" className="h-full">
+      <body className="min-h-full bg-background text-foreground antialiased">
+        {children}
+      </body>
+    </html>
+  );
+}
+
+```
+
+## app/app/mcp/callback/page.tsx
+
+```tsx
+"use client";
+
+import { useRouter } from "next/navigation";
+import { McpOAuthCallback } from "@assistant-ui/react-mcp";
+import { Providers } from "../../providers";
+
+export default function CallbackPage() {
+  const router = useRouter();
+  return (
+    <Providers>
+      <h1>Completing OAuth…</h1>
+      <McpOAuthCallback
+        onComplete={() => router.replace("/")}
+        onError={(err) => {
+          console.error("OAuth callback failed:", err);
+        }}
+      >
+        {(result) => (
+          <pre>
+            {JSON.stringify(
+              {
+                status: result.status,
+                serverId: result.serverId,
+                error: result.error?.message ?? null,
+              },
+              null,
+              2,
+            )}
+          </pre>
+        )}
+      </McpOAuthCallback>
+    </Providers>
+  );
+}
+
+```
+
+## app/app/page.tsx
+
+```tsx
+"use client";
+
+import { Thread } from "@/components/assistant-ui/thread";
+import { McpConfigDialog } from "@/components/assistant-ui/mcp-config";
+import { Providers } from "./providers";
+
+export default function Home() {
+  return (
+    <Providers>
+      <main className="grid h-dvh grid-rows-[auto_1fr]">
+        <header className="flex items-center justify-between gap-3 border-b px-4 py-3">
+          <div className="flex flex-col">
+            <h1 className="font-semibold text-base tracking-tight">
+              react-mcp
+            </h1>
+            <p className="text-muted-foreground text-xs">
+              Connect MCP servers, then chat — connected tools are exposed to
+              the model automatically.
+            </p>
+          </div>
+          <McpConfigDialog />
+        </header>
+        <Thread />
+      </main>
+    </Providers>
+  );
+}
+
+```
+
+## app/app/providers.tsx
+
+```tsx
+"use client";
+
+import type { ReactNode } from "react";
+import { AssistantRuntimeProvider, useAui } from "@assistant-ui/react";
+import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
+import { McpManagerResource, defineConnector } from "@assistant-ui/react-mcp";
+
+const connectors = [
+  defineConnector({
+    id: "local-test",
+    name: "Local test MCP",
+    url: "http://localhost:8787/mcp",
+    auth: { type: "oauth", scopes: ["mcp"] },
+  }),
+];
+
+export function Providers({ children }: { children: ReactNode }) {
+  const aui = useAui({ mcp: McpManagerResource({ connectors }) });
+  const runtime = useChatRuntime();
+  return (
+    <AssistantRuntimeProvider runtime={runtime} aui={aui}>
+      {children}
+    </AssistantRuntimeProvider>
+  );
+}
+
+```
+
+## app/next.config.ts
+
+```typescript
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: [
+    "@assistant-ui/react-mcp",
+    "@assistant-ui/store",
+    "@assistant-ui/tap",
+    "@assistant-ui/ui",
+  ],
+  allowedDevOrigins: ["*"],
+};
+
+export default nextConfig;
+
+```
+
+## app/tsconfig.json
+
+```json
+{
+  "extends": "@assistant-ui/x-buildutils/ts/next",
+  "compilerOptions": {
+    "typeRoots": [
+      "./node_modules/@types",
+      "../node_modules/@types",
+      "../../../node_modules/@types",
+      "../node_modules/@assistant-ui/x-buildutils/types"
+    ],
+    "paths": {
+      "@/*": ["./*"],
+      "@/components/assistant-ui/*": [
+        "../../../packages/ui/src/components/assistant-ui/*"
+      ],
+      "@/components/ui/*": ["../../../packages/ui/src/components/ui/*"],
+      "@/lib/utils": ["../../../packages/ui/src/lib/utils"],
+      "@assistant-ui/ui/*": ["../../../packages/ui/src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts",
+    "**/*.ts",
+    "**/*.tsx"
+  ],
+  "exclude": ["node_modules"]
+}
+
+```
+
+## components.json
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/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"
+  }
+}
+
+```
+
+## package.json
+
+```json
+{
+  "name": "with-mcp",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "concurrently -n server,app -c blue,magenta \"pnpm dev:server\" \"pnpm dev:app\"",
+    "dev:server": "tsx watch server/server.ts",
+    "dev:app": "next dev app --port 3010",
+    "build": "next build app",
+    "start:server": "tsx server/server.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.64",
+    "@assistant-ui/react": "workspace:*",
+    "@assistant-ui/react-ai-sdk": "workspace:*",
+    "@assistant-ui/react-markdown": "workspace:*",
+    "@assistant-ui/react-mcp": "workspace:*",
+    "@assistant-ui/store": "workspace:*",
+    "@assistant-ui/tap": "workspace:*",
+    "@assistant-ui/ui": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ai": "^6.0.188",
+    "assistant-stream": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cors": "^2.8.6",
+    "express": "^5.2.1",
+    "lucide-react": "^1.16.0",
+    "next": "^16.2.6",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "tailwind-merge": "^3.6.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "concurrently": "^9.2.1",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
+    "tsx": "^4.22.3",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.3"
+  }
+}
+
+```
+
+## README.md
+
+```markdown
+# with-mcp
+
+Minimal harness for `@assistant-ui/react-mcp`. Runs a local MCP server with
+OAuth (PKCE + DCR) under `server/`, and a Next.js client under `app/` that
+uses the package's primitives.
+
+## Run
+
+```sh
+cd examples/with-mcp
+pnpm dev
+```
+
+This starts both the server (`http://localhost:8787`) and the Next.js app
+(`http://localhost:3010`).
+
+Open the app, click **Connect** on the "Local test MCP" connector, then
+**Authorize ↗** to walk through the OAuth flow. After redirect the server
+transitions to `connected` and the `echo` / `fingerprint` tools appear.
+
+## Notes
+
+- The test server is in-memory: tokens, clients, and codes don't persist
+  across restarts.
+- OAuth auto-approves (no consent screen). PKCE verification, DCR, and
+  refresh-token rotation still run end-to-end.
+- This example is intentionally unstyled; primitives are unstyled. See
+  `app/app/McpUI.tsx` for raw composition.
+
+```
+
+## server/server.ts
+
+```typescript
+/**
+ * Standalone test MCP server with OAuth.
+ *
+ * - OAuth 2.1 authorization server (PKCE + DCR) via @modelcontextprotocol/sdk auth router.
+ * - One MCP tool, `echo`, that returns its input.
+ * - All state in memory; for local development / E2E only.
+ *
+ * Run: `pnpm dev:server` (defaults to http://localhost:8787)
+ */
+import express from "express";
+import cors from "cors";
+import { randomBytes, randomUUID, createHash } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import type { OAuthServerProvider } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { OAuthRegisteredClientsStore } from "@modelcontextprotocol/sdk/server/auth/clients.js";
+import type {
+  OAuthClientInformationFull,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import { z } from "zod";
+
+const PORT = Number(process.env.PORT ?? 8787);
+const ISSUER = process.env.ISSUER ?? `http://localhost:${PORT}`;
+
+// ───────────────────────────────────────────────────────────────────────────
+// In-memory OAuth provider
+// ───────────────────────────────────────────────────────────────────────────
+
+type AuthorizationGrant = {
+  clientId: string;
+  redirectUri: string;
+  codeChallenge: string;
+  scopes: string[];
+  state?: string;
+};
+
+const clients = new Map<string, OAuthClientInformationFull>();
+const authCodes = new Map<string, AuthorizationGrant>();
+const tokens = new Map<string, AuthInfo>();
+const refreshTokens = new Map<string, { clientId: string; scopes: string[] }>();
+
+const clientsStore: OAuthRegisteredClientsStore = {
+  async getClient(clientId) {
+    return clients.get(clientId);
+  },
+  async registerClient(client) {
+    const clientId = `client_${randomUUID()}`;
+    const full: OAuthClientInformationFull = {
+      ...client,
+      client_id: clientId,
+      client_id_issued_at: Math.floor(Date.now() / 1000),
+    };
+    clients.set(clientId, full);
+    return full;
+  },
+};
+
+const provider: OAuthServerProvider = {
+  get clientsStore() {
+    return clientsStore;
+  },
+
+  async authorize(client, params, res) {
+    // Auto-approve for the test server.
+    const code = randomBytes(24).toString("base64url");
+    authCodes.set(code, {
+      clientId: client.client_id,
+      redirectUri: params.redirectUri,
+      codeChallenge: params.codeChallenge,
+      scopes: params.scopes ?? [],
+      ...(params.state !== undefined ? { state: params.state } : {}),
+    });
+
+    const target = new URL(params.redirectUri);
+    target.searchParams.set("code", code);
+    if (params.state) target.searchParams.set("state", params.state);
+    res.redirect(target.toString());
+  },
+
+  async challengeForAuthorizationCode(_client, authorizationCode) {
+    const grant = authCodes.get(authorizationCode);
+    if (!grant) throw new Error("invalid authorization code");
+    return grant.codeChallenge;
+  },
+
+  async exchangeAuthorizationCode(
+    client,
+    authorizationCode,
+  ): Promise<OAuthTokens> {
+    const grant = authCodes.get(authorizationCode);
+    if (!grant) throw new Error("invalid authorization code");
+    if (grant.clientId !== client.client_id) {
+      throw new Error("authorization code/client mismatch");
+    }
+    authCodes.delete(authorizationCode);
+
+    const accessToken = randomBytes(32).toString("base64url");
+    const refreshToken = randomBytes(32).toString("base64url");
+    tokens.set(accessToken, {
+      token: accessToken,
+      clientId: client.client_id,
+      scopes: grant.scopes,
+      expiresAt: Math.floor(Date.now() / 1000) + 60 * 60,
+    });
+    refreshTokens.set(refreshToken, {
+      clientId: client.client_id,
+      scopes: grant.scopes,
+    });
+    return {
+      access_token: accessToken,
+      refresh_token: refreshToken,
+      token_type: "Bearer",
+      expires_in: 60 * 60,
+      scope: grant.scopes.join(" "),
+    };
+  },
+
+  async exchangeRefreshToken(
+    client,
+    refreshToken,
+    scopes,
+  ): Promise<OAuthTokens> {
+    const grant = refreshTokens.get(refreshToken);
+    if (!grant) throw new Error("invalid refresh token");
+    if (grant.clientId !== client.client_id) {
+      throw new Error("refresh token/client mismatch");
+    }
+    const newAccess = randomBytes(32).toString("base64url");
+    const newRefresh = randomBytes(32).toString("base64url");
+    const effectiveScopes = scopes ?? grant.scopes;
+    refreshTokens.delete(refreshToken);
+    tokens.set(newAccess, {
+      token: newAccess,
+      clientId: client.client_id,
+      scopes: effectiveScopes,
+      expiresAt: Math.floor(Date.now() / 1000) + 60 * 60,
+    });
+    refreshTokens.set(newRefresh, {
+      clientId: client.client_id,
+      scopes: effectiveScopes,
+    });
+    return {
+      access_token: newAccess,
+      refresh_token: newRefresh,
+      token_type: "Bearer",
+      expires_in: 60 * 60,
+      scope: effectiveScopes.join(" "),
+    };
+  },
+
+  async verifyAccessToken(token): Promise<AuthInfo> {
+    const info = tokens.get(token);
+    if (!info) throw new Error("invalid access token");
+    return info;
+  },
+};
+
+// ───────────────────────────────────────────────────────────────────────────
+// MCP server
+// ───────────────────────────────────────────────────────────────────────────
+
+function buildMcpServer(): McpServer {
+  const server = new McpServer({ name: "aui-mcp-test", version: "0.0.1" });
+  server.tool(
+    "echo",
+    "Echo back the provided text.",
+    { text: z.string().describe("Text to echo back") },
+    async ({ text }) => ({
+      content: [{ type: "text" as const, text: `echo: ${text}` }],
+    }),
+  );
+  server.tool(
+    "fingerprint",
+    "Return a deterministic fingerprint of a string (sha256 hex).",
+    { input: z.string() },
+    async ({ input }) => ({
+      content: [
+        {
+          type: "text" as const,
+          text: createHash("sha256").update(input).digest("hex"),
+        },
+      ],
+    }),
+  );
+  return server;
+}
+
+// ───────────────────────────────────────────────────────────────────────────
+// Express wiring
+// ───────────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const app = express();
+
+  app.use(
+    cors({
+      origin: true,
+      credentials: false,
+      // Without these the browser won't expose MCP session/auth headers.
+      exposedHeaders: ["Mcp-Session-Id", "WWW-Authenticate"],
+      allowedHeaders: [
+        "Authorization",
+        "Content-Type",
+        "Mcp-Session-Id",
+        "Accept",
+        "mcp-protocol-version",
+      ],
+    }),
+  );
+
+  app.use(
+    mcpAuthRouter({
+      provider,
+      issuerUrl: new URL(ISSUER),
+      scopesSupported: ["mcp"],
+      resourceName: "aui-mcp-test",
+    }),
+  );
+
+  const bearer = requireBearerAuth({ verifier: provider });
+
+  app.post("/mcp", bearer, async (req, res) => {
+    try {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+      });
+      res.on("close", () => transport.close());
+      const server = buildMcpServer();
+      await server.connect(transport);
+      await transport.handleRequest(req, res);
+    } catch (err) {
+      console.error("MCP request error:", err);
+      if (!res.headersSent) res.status(500).end();
+    }
+  });
+
+  app.get("/health", (_req, res) => res.json({ ok: true }));
+
+  app.listen(PORT, () => {
+    console.log(`MCP test server listening on ${ISSUER}`);
+    console.log(
+      `  - OAuth metadata: ${ISSUER}/.well-known/oauth-authorization-server`,
+    );
+    console.log(`  - MCP endpoint:   ${ISSUER}/mcp`);
+  });
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
+
+```
+
+## tsconfig.json
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "types": ["node"],
+    "paths": {
+      "@/*": ["./app/*"]
+    }
+  },
+  "include": [
+    "app/next-env.d.ts",
+    "app/**/*.ts",
+    "app/**/*.tsx",
+    "server/**/*.ts",
+    "app/.next/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}
+
+```
+