@assistant-ui/react-mcp 0.0.0

package/dist/utils/serverId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverId.d.ts","sourceRoot":"","sources":["../../src/utils/serverId.ts"],"names":[],"mappings":"AAIA,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAcpD"}

package/dist/utils/serverId.js

@@ -0,0 +1,16 @@
+// Server ids are joined with tool names via `__` to form unique tool
+// names for the AI SDK. The separator must not appear inside ids,
+// otherwise two distinct `(serverId, toolName)` pairs could produce
+// the same composite name.
+export function assertValidServerId(id) {
+    if (id.length === 0) {
+        throw new Error("MCP server id must not be empty.");
+    }
+    if (id.includes("__")) {
+        throw new Error(`MCP server id "${id}" must not contain "__" — that sequence is reserved for separating server id from tool name.`);
+    }
+    if (id.includes("\x1f")) {
+        throw new Error(`MCP server id "${id}" must not contain the ASCII Unit Separator (\\x1f) — it is reserved as the list delimiter in primitive id-list selectors.`);
+    }
+}
+//# sourceMappingURL=serverId.js.map

package/dist/utils/serverId.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serverId.js","sourceRoot":"","sources":["../../src/utils/serverId.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,kEAAkE;AAClE,oEAAoE;AACpE,2BAA2B;AAC3B,MAAM,UAAU,mBAAmB,CAAC,EAAU;IAC5C,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,kBAAkB,EAAE,8FAA8F,CACnH,CAAC;IACJ,CAAC;IACD,IAAI,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,kBAAkB,EAAE,4HAA4H,CACjJ,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@assistant-ui/react-mcp",
+  "version": "0.0.0",
+  "description": "MCP server configuration and connection primitives for @assistant-ui",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "oauth",
+    "assistant-ui",
+    "react"
+  ],
+  "author": "AgentbaseAI Inc.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "aui-build"
+  },
+  "dependencies": {
+    "@assistant-ui/core": "workspace:*",
+    "@assistant-ui/store": "workspace:*",
+    "@assistant-ui/tap": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@radix-ui/react-primitive": "^2.1.4",
+    "assistant-stream": "workspace:*"
+  },
+  "peerDependencies": {
+    "@types/react": "*",
+    "react": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@assistant-ui/x-buildutils": "workspace:*",
+    "@types/react": "^19.2.14",
+    "react": "^19.2.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "homepage": "https://www.assistant-ui.com/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/assistant-ui/assistant-ui.git",
+    "directory": "packages/react-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/assistant-ui/assistant-ui/issues"
+  }
+}

package/src/auth/buildHeaders.ts

@@ -0,0 +1,19 @@
+import type { MCPAuthConfig } from "../mcp-scope";
+import type { MCPPersistedAuthState } from "./types";
+
+/**
+ * Build request headers for the bearer/none flows. For bearer, prefer a token
+ * stored at add-form time (persisted), falling back to a static token on the
+ * config (used by connectors that hardcode a token, rare in practice).
+ */
+export function buildHeaders(
+  auth: MCPAuthConfig,
+  persisted: MCPPersistedAuthState | null,
+): Record<string, string> | undefined {
+  if (auth.type === "bearer") {
+    const token = persisted?.token ?? auth.token;
+    if (!token) return undefined;
+    return { Authorization: `Bearer ${token}` };
+  }
+  return undefined;
+}

package/src/auth/createOAuthProvider.ts

@@ -0,0 +1,172 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientInformationFull,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { MCPStorage } from "../resources/storage/types";
+import type { MCPAuthConfig } from "../mcp-scope";
+
+const STATE_PREFIX = "aui-mcp:";
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function base64UrlToBytes(b64url: string): Uint8Array {
+  const padded =
+    b64url.replace(/-/g, "+").replace(/_/g, "/") +
+    "=".repeat((4 - (b64url.length % 4)) % 4);
+  const bin = atob(padded);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+function encodeServerIdInState(serverId: string): string {
+  const bytes = new TextEncoder().encode(serverId);
+  return `${STATE_PREFIX}${bytesToBase64Url(bytes)}`;
+}
+
+export function decodeServerIdFromState(state: string): string | null {
+  if (!state.startsWith(STATE_PREFIX)) return null;
+  const dot = state.indexOf(".", STATE_PREFIX.length);
+  const encoded =
+    dot === -1
+      ? state.slice(STATE_PREFIX.length)
+      : state.slice(STATE_PREFIX.length, dot);
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(
+      base64UrlToBytes(encoded),
+    );
+  } catch {
+    return null;
+  }
+}
+
+export type CreateOAuthProviderOptions = {
+  serverId: string;
+  /** Must be `auth.type === "oauth"`. */
+  config: Extract<MCPAuthConfig, { type: "oauth" }>;
+  storage: MCPStorage;
+  redirectUri: string;
+  /** Called by the SDK to start the authorization redirect. */
+  onAuthorizationUrl: (url: URL) => void;
+};
+
+/**
+ * Builds an OAuthClientProvider for the MCP SDK, backed by MCPStorage.
+ * Token refresh and DCR are handled by the SDK; this provider only mediates
+ * load/save and the redirect step.
+ */
+export function createOAuthProvider(
+  opts: CreateOAuthProviderOptions,
+): OAuthClientProvider {
+  const { serverId, config, storage, redirectUri, onAuthorizationUrl } = opts;
+
+  type Cache = {
+    tokens?: OAuthTokens | undefined;
+    clientInformation?: OAuthClientInformationFull | undefined;
+    codeVerifier?: string | undefined;
+  };
+  let cached: Cache | null = null;
+
+  const loadCache = async (): Promise<Cache> => {
+    if (cached) return cached;
+    const persisted = await storage.loadAuthState(serverId);
+    const initial: Cache = {};
+    if (persisted?.tokens) initial.tokens = persisted.tokens;
+    if (config.clientId) {
+      const ci: OAuthClientInformationFull = {
+        client_id: config.clientId,
+        redirect_uris: [redirectUri],
+      };
+      if (config.clientSecret) ci.client_secret = config.clientSecret;
+      initial.clientInformation = ci;
+    } else if (persisted?.clientInformation) {
+      initial.clientInformation = persisted.clientInformation;
+    }
+    if (persisted?.codeVerifier) initial.codeVerifier = persisted.codeVerifier;
+    cached = initial;
+    return cached;
+  };
+
+  const persist = async () => {
+    const c = cached;
+    if (!c) return;
+    const next: Parameters<typeof storage.saveAuthState>[1] = {};
+    if (c.tokens) next.tokens = c.tokens;
+    if (c.clientInformation) next.clientInformation = c.clientInformation;
+    if (c.codeVerifier) next.codeVerifier = c.codeVerifier;
+    await storage.saveAuthState(serverId, next);
+  };
+
+  const clientMetadata: OAuthClientMetadata = {
+    client_name: "assistant-ui",
+    redirect_uris: [redirectUri],
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+    token_endpoint_auth_method: "none",
+    scope: config.scopes?.join(" "),
+  };
+
+  return {
+    get redirectUrl() {
+      return redirectUri;
+    },
+    get clientMetadata() {
+      return clientMetadata;
+    },
+    state() {
+      // Embed the server id so the callback handler can route it back to the
+      // right MCPServerResource without app-level wiring.
+      const nonce =
+        typeof crypto !== "undefined" && "randomUUID" in crypto
+          ? crypto.randomUUID()
+          : `${Date.now()}.${Math.random()}`;
+      return `${encodeServerIdInState(serverId)}.${nonce}`;
+    },
+    async clientInformation() {
+      const c = await loadCache();
+      return c.clientInformation;
+    },
+    async saveClientInformation(info) {
+      const c = await loadCache();
+      c.clientInformation = info as OAuthClientInformationFull;
+      await persist();
+    },
+    async tokens() {
+      const c = await loadCache();
+      return c.tokens;
+    },
+    async saveTokens(tokens) {
+      const c = await loadCache();
+      c.tokens = tokens;
+      await persist();
+    },
+    async redirectToAuthorization(url) {
+      onAuthorizationUrl(url);
+    },
+    async saveCodeVerifier(codeVerifier) {
+      const c = await loadCache();
+      c.codeVerifier = codeVerifier;
+      await persist();
+    },
+    async codeVerifier() {
+      const c = await loadCache();
+      if (!c.codeVerifier) {
+        throw new Error("No code verifier saved for this OAuth flow");
+      }
+      return c.codeVerifier;
+    },
+    async invalidateCredentials(scope) {
+      const c = await loadCache();
+      if (scope === "all" || scope === "tokens") delete c.tokens;
+      if (scope === "all" || scope === "client") delete c.clientInformation;
+      if (scope === "all" || scope === "verifier") delete c.codeVerifier;
+      await persist();
+    },
+  };
+}

package/src/auth/types.ts

@@ -0,0 +1,12 @@
+import type {
+  OAuthTokens,
+  OAuthClientInformationFull,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+
+export type MCPPersistedAuthState = {
+  tokens?: OAuthTokens;
+  clientInformation?: OAuthClientInformationFull;
+  codeVerifier?: string;
+  /** Bearer token (entered at add-form time). */
+  token?: string;
+};

package/src/connector.ts

@@ -0,0 +1,7 @@
+import type { MCPConnector } from "./mcp-scope";
+import { assertValidServerId } from "./utils/serverId";
+
+export function defineConnector(connector: MCPConnector): MCPConnector {
+  assertValidServerId(connector.id);
+  return connector;
+}

package/src/context/McpConnectorByIndexProvider.tsx

@@ -0,0 +1,16 @@
+import type { FC, PropsWithChildren } from "react";
+import { useAui, AuiProvider, Derived } from "@assistant-ui/store";
+
+export const McpConnectorByIndexProvider: FC<
+  PropsWithChildren<{ index: number }>
+> = ({ index, children }) => {
+  const aui = useAui({
+    mcpServer: Derived({
+      source: "mcp",
+      query: { kind: "connector", index },
+      get: (parent) => parent.mcp().connector({ index }),
+    }),
+  });
+
+  return <AuiProvider value={aui}>{children}</AuiProvider>;
+};

package/src/context/McpCustomServerByIndexProvider.tsx

@@ -0,0 +1,16 @@
+import type { FC, PropsWithChildren } from "react";
+import { useAui, AuiProvider, Derived } from "@assistant-ui/store";
+
+export const McpCustomServerByIndexProvider: FC<
+  PropsWithChildren<{ index: number }>
+> = ({ index, children }) => {
+  const aui = useAui({
+    mcpServer: Derived({
+      source: "mcp",
+      query: { kind: "custom", index },
+      get: (parent) => parent.mcp().customServer({ index }),
+    }),
+  });
+
+  return <AuiProvider value={aui}>{children}</AuiProvider>;
+};

package/src/context/McpServerByIdProvider.tsx

@@ -0,0 +1,17 @@
+import type { FC, PropsWithChildren } from "react";
+import { useAui, AuiProvider, Derived } from "@assistant-ui/store";
+
+export const McpServerByIdProvider: FC<PropsWithChildren<{ id: string }>> = ({
+  id,
+  children,
+}) => {
+  const aui = useAui({
+    mcpServer: Derived({
+      source: "mcp",
+      query: { id },
+      get: (parent) => parent.mcp().server({ id }),
+    }),
+  });
+
+  return <AuiProvider value={aui}>{children}</AuiProvider>;
+};

package/src/hooks/useMcpOAuthCallback.tsx

@@ -0,0 +1,79 @@
+import { type FC, type ReactNode, useEffect, useRef, useState } from "react";
+import { useAui } from "@assistant-ui/store";
+import { decodeServerIdFromState } from "../auth/createOAuthProvider";
+
+export type UseMcpOAuthCallbackOptions = {
+  /** Defaults to `window.location.href`. */
+  url?: string;
+  onComplete?: (serverId: string) => void;
+  onError?: (err: Error) => void;
+};
+
+export type UseMcpOAuthCallbackResult = {
+  status: "idle" | "running" | "done" | "error";
+  serverId: string | null;
+  error: Error | null;
+};
+
+export function useMcpOAuthCallback(
+  opts: UseMcpOAuthCallbackOptions = {},
+): UseMcpOAuthCallbackResult {
+  const aui = useAui();
+  const [result, setResult] = useState<UseMcpOAuthCallbackResult>({
+    status: "idle",
+    serverId: null,
+    error: null,
+  });
+  // Guard against React 18 Strict Mode's mount-unmount-remount: the effect
+  // body must not run completeAuth twice for the same URL, otherwise the
+  // single-use OAuth code is double-redeemed and the second attempt 4xxs.
+  const startedRef = useRef<string | null>(null);
+  const optsRef = useRef(opts);
+  optsRef.current = opts;
+
+  useEffect(() => {
+    const url =
+      opts.url ?? (typeof window !== "undefined" ? window.location.href : null);
+    if (!url) return;
+    if (startedRef.current === url) return;
+    startedRef.current = url;
+
+    (async () => {
+      try {
+        const parsed = new URL(url);
+        const state = parsed.searchParams.get("state");
+        const error = parsed.searchParams.get("error");
+        if (error) {
+          throw new Error(
+            parsed.searchParams.get("error_description") ?? error,
+          );
+        }
+        if (!state) throw new Error("missing state parameter in callback URL");
+        const serverId = decodeServerIdFromState(state);
+        if (!serverId) {
+          throw new Error("callback state does not match an MCP server");
+        }
+        setResult({ status: "running", serverId, error: null });
+        await aui.mcp().server({ id: serverId }).completeAuth(url);
+        setResult({ status: "done", serverId, error: null });
+        optsRef.current.onComplete?.(serverId);
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        setResult((prev) => ({ ...prev, status: "error", error: e }));
+        optsRef.current.onError?.(e);
+      }
+    })();
+  }, [aui, opts.url]);
+
+  return result;
+}
+
+export const McpOAuthCallback: FC<
+  UseMcpOAuthCallbackOptions & {
+    children?: (result: UseMcpOAuthCallbackResult) => ReactNode;
+  }
+> = ({ children, ...opts }) => {
+  const result = useMcpOAuthCallback(opts);
+  if (children) return <>{children(result)}</>;
+  return null;
+};

package/src/index.ts

@@ -0,0 +1,68 @@
+// Scope augmentation must be imported for module declaration side-effect.
+import "./mcp-scope";
+
+// Resource — the entry point. Mount via:
+//   useAui({ mcp: McpManagerResource({ connectors }) })
+export {
+  McpManagerResource,
+  type McpManagerResourceProps,
+} from "./resources/McpManagerResource";
+
+// Internal — exported for advanced cases (custom manager / lookup wiring).
+export {
+  McpServerResource,
+  type McpServerResourceProps,
+} from "./resources/McpServerResource";
+
+// Connector helper
+export { defineConnector } from "./connector";
+
+// Storage resources
+export {
+  McpLocalStorage,
+  type McpLocalStorageOptions,
+} from "./resources/storage/McpLocalStorage";
+export { McpMemoryStorage } from "./resources/storage/McpMemoryStorage";
+export { McpCustomStorage } from "./resources/storage/McpCustomStorage";
+export type {
+  MCPStorage,
+  MCPStorageElement,
+} from "./resources/storage/types";
+
+// Primitives (namespaced)
+export * as McpManagerPrimitive from "./primitives/manager";
+export * as McpServerPrimitive from "./primitives/server";
+export * as McpAddFormPrimitive from "./primitives/addForm";
+
+// Per-server scope providers. The iteration primitives wrap each item in
+// the appropriate ByIndex provider. The ById provider is useful for
+// rendering server UI outside the iteration primitives (static id known).
+export { McpServerByIdProvider } from "./context/McpServerByIdProvider";
+export { McpConnectorByIndexProvider } from "./context/McpConnectorByIndexProvider";
+export { McpCustomServerByIndexProvider } from "./context/McpCustomServerByIndexProvider";
+
+// OAuth callback
+export {
+  useMcpOAuthCallback,
+  McpOAuthCallback,
+  type UseMcpOAuthCallbackOptions,
+  type UseMcpOAuthCallbackResult,
+} from "./hooks/useMcpOAuthCallback";
+
+// Auth state shape
+export type { MCPPersistedAuthState } from "./auth/types";
+
+// Public types
+export type {
+  MCPAuthConfig,
+  MCPConnector,
+  MCPCustomServerRecord,
+  MCPServerKind,
+  MCPConnectionState,
+  MCPToolInfo,
+  MCPServerState,
+  MCPManagerState,
+  MCPServerMethods,
+  MCPManagerMethods,
+  MCPServerQuery,
+} from "./mcp-scope";

package/src/mcp-scope.ts

@@ -0,0 +1,110 @@
+import "@assistant-ui/store";
+
+export type MCPAuthConfig =
+  | { type: "none" }
+  | { type: "bearer"; token?: string | undefined }
+  | {
+      type: "oauth";
+      scopes?: string[] | undefined;
+      authorizationEndpoint?: string | undefined;
+      tokenEndpoint?: string | undefined;
+      registrationEndpoint?: string | undefined;
+      clientId?: string | undefined;
+      clientSecret?: string | undefined;
+    };
+
+export type MCPConnector = {
+  id: string;
+  name: string;
+  url: string;
+  icon?: string | undefined;
+  auth: MCPAuthConfig;
+};
+
+export type MCPCustomServerRecord = {
+  id: string;
+  name: string;
+  url: string;
+  auth: MCPAuthConfig;
+  createdAt: number;
+};
+
+export type MCPServerKind = "connector" | "custom";
+
+export type MCPConnectionState =
+  | "disconnected"
+  | "authRequired"
+  | "authPending"
+  | "connecting"
+  | "connected"
+  | "error";
+
+export type MCPToolInfo = {
+  name: string;
+  description?: string | undefined;
+  inputSchema: unknown;
+};
+
+export type MCPServerState = {
+  id: string;
+  kind: MCPServerKind;
+  name: string;
+  url: string;
+  icon?: string | undefined;
+  connectionState: MCPConnectionState;
+  lastError: { message: string } | null;
+  tools: MCPToolInfo[];
+  authorizationUrl: string | null;
+};
+
+export type MCPManagerState = {
+  servers: MCPServerState[];
+  connectors: MCPServerState[];
+  customServers: MCPServerState[];
+  isHydrated: boolean;
+};
+
+export type MCPServerMethods = {
+  getState: () => MCPServerState;
+  connect: () => Promise<void>;
+  disconnect: () => Promise<void>;
+  remove: () => Promise<void>;
+  callTool: (name: string, args: unknown) => Promise<unknown>;
+  /** Read a resource by URI. Returns the raw MCP `ReadResourceResult`. */
+  readResource: (uri: string) => Promise<unknown>;
+  /** OAuth only: pass full callback URL (e.g. window.location.href) */
+  completeAuth: (callbackUrl: string) => Promise<void>;
+};
+
+export type MCPServerQuery =
+  | { id: string }
+  | { kind: "connector"; index: number }
+  | { kind: "custom"; index: number };
+
+export type MCPManagerMethods = {
+  getState: () => MCPManagerState;
+  /** Look up a server by id, or by index within its kind. */
+  server: (query: MCPServerQuery) => MCPServerMethods;
+  /** Convenience: equivalent to `server({ kind: "connector", index })`. */
+  connector: (query: { index: number }) => MCPServerMethods;
+  /** Convenience: equivalent to `server({ kind: "custom", index })`. */
+  customServer: (query: { index: number }) => MCPServerMethods;
+  addCustomServer: (input: {
+    name: string;
+    url: string;
+    auth: MCPAuthConfig;
+  }) => Promise<string>;
+  removeServer: (id: string) => Promise<void>;
+};
+
+declare module "@assistant-ui/store" {
+  interface ScopeRegistry {
+    mcp: {
+      methods: MCPManagerMethods;
+    };
+    mcpServer: {
+      methods: MCPServerMethods;
+      meta: { source: "mcp"; query: MCPServerQuery };
+    };
+  }
+}

package/src/primitives/addForm/McpAddFormAuthFields.tsx

@@ -0,0 +1,51 @@
+import type { FC } from "react";
+import { type AddFormAuthType, useAddForm } from "./context";
+
+export namespace McpAddFormPrimitiveAuthFields {
+  export type Props = {
+    /**
+     * Optional render override. Receives the current auth type so apps can render
+     * fully custom inputs. Defaults to a minimal built-in for bearer / oauth.
+     */
+    children?: FC<{ authType: AddFormAuthType }>;
+  };
+}
+
+export const McpAddFormPrimitiveAuthFields: FC<
+  McpAddFormPrimitiveAuthFields.Props
+> = ({ children }) => {
+  const { state, setField } = useAddForm();
+
+  if (children) {
+    const Render = children;
+    return <Render authType={state.authType} />;
+  }
+
+  if (state.authType === "bearer") {
+    return (
+      <input
+        type="password"
+        placeholder="Bearer token"
+        value={state.bearerToken}
+        onChange={(e) => setField("bearerToken", e.target.value)}
+        data-mcp-auth-field="bearer-token"
+      />
+    );
+  }
+
+  if (state.authType === "oauth") {
+    return (
+      <input
+        type="text"
+        placeholder="Scopes (space-separated, optional)"
+        value={state.scopes}
+        onChange={(e) => setField("scopes", e.target.value)}
+        data-mcp-auth-field="oauth-scopes"
+      />
+    );
+  }
+
+  return null;
+};
+
+McpAddFormPrimitiveAuthFields.displayName = "McpAddFormPrimitive.AuthFields";