@assistant-ui/mcp-docs-server 0.1.36 → 0.1.39

package/src/xulux/template-service.ts

@@ -0,0 +1,406 @@
+import { fetchSandboxResource } from "./fetch-sandbox.js";
+import type {
+  XuluxCatalog,
+  XuluxCatalogTemplate,
+  XuluxCatalogVersion,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Local, catalog-backed template operations for the assistant-ui template MCP tools.
+// These functions never mutate any UI. Preview operations only return URLs.
+// ---------------------------------------------------------------------------
+
+export interface ResolvedTemplate {
+  template: XuluxCatalogTemplate;
+  version: XuluxCatalogVersion | null;
+}
+
+/**
+ * Resolves a template by id, preserving the app-route semantics:
+ * - exact `templateId` match wins
+ * - version-specific entry ids (e.g. `webpage-assistant-product-docs`)
+ *   remain valid inputs
+ * - explicit `versionId` wins when provided
+ * - otherwise the template's default version is used
+ */
+export function resolveTemplate(
+  catalog: XuluxCatalog,
+  templateId: string,
+  versionId?: string | undefined,
+): ResolvedTemplate | null {
+  let template = catalog.templates.find(
+    (t) => t.templateId === templateId || t.id === templateId,
+  );
+  let impliedVersionId: string | undefined;
+
+  if (!template) {
+    // Version-specific entry id such as `webpage-assistant-product-docs`.
+    template = catalog.templates.find((t) =>
+      t.versions.some((v) => v.entryId === templateId),
+    );
+    if (template) {
+      impliedVersionId = template.versions.find(
+        (v) => v.entryId === templateId,
+      )?.id;
+    }
+  }
+
+  if (!template) return null;
+
+  const effectiveVersionId =
+    versionId ?? impliedVersionId ?? template.versionId;
+  const version = effectiveVersionId
+    ? (template.versions.find((v) => v.id === effectiveVersionId) ?? null)
+    : null;
+
+  return { template, version };
+}
+
+export interface TemplateListItem {
+  id: string;
+  name: string;
+  summary: string;
+  assistantPlacement: string;
+  features: string[];
+  customizable: string[];
+  versions: Array<{ id: string; name: string; description: string }>;
+  kind: "template" | "example";
+}
+
+export function listTemplates(catalog: XuluxCatalog): {
+  templates: TemplateListItem[];
+} {
+  return {
+    templates: catalog.templates.map((t) => ({
+      id: t.templateId,
+      name: t.name,
+      summary: t.summary,
+      assistantPlacement: t.assistantPlacement,
+      features: t.features,
+      customizable: t.customizable,
+      versions: t.versions.map((v) => ({
+        id: v.id,
+        name: v.name,
+        description: v.description,
+      })),
+      kind: t.kind,
+    })),
+  };
+}
+
+async function fetchTemplateContract(
+  sandboxBaseUrl: string,
+  versionId: string | null,
+): Promise<Record<string, unknown> | null> {
+  try {
+    const url = new URL("/api/template/contract", sandboxBaseUrl);
+    if (versionId) url.searchParams.set("v", versionId);
+    const res = await fetchSandboxResource(url.toString());
+    if (!res.ok) return null;
+    return (await res.json()) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export interface TemplateDetails {
+  id: string;
+  name: string;
+  selectedVersionId: string | null;
+  summary: string;
+  assistantPlacement: string;
+  configRoots?: Record<string, unknown>;
+  rules: {
+    required: string[];
+    unsupported?: string[];
+  };
+  tools: {
+    builtIn: unknown[];
+    customToolSupported: boolean;
+    renderers: unknown[];
+  };
+  exampleConfig: Record<string, unknown> | null;
+  previewUrl?: string;
+  downloadUrl?: string;
+  warnings?: string[];
+  exampleConfigNote?: string;
+}
+
+export interface TemplateError {
+  error: string;
+  retryHint?: string;
+}
+
+export async function getTemplateDetails(
+  catalog: XuluxCatalog,
+  input: { templateId: string; versionId?: string | undefined },
+): Promise<TemplateDetails | TemplateError> {
+  const resolved = resolveTemplate(catalog, input.templateId, input.versionId);
+  if (!resolved) {
+    return {
+      error: `Template "${input.templateId}" not found.`,
+      retryHint:
+        "Call assistantUITemplates and use one of the returned template ids.",
+    };
+  }
+
+  const { template, version } = resolved;
+
+  if (template.kind === "example") {
+    return {
+      id: template.templateId,
+      name: template.name,
+      selectedVersionId: null,
+      summary: template.summary,
+      assistantPlacement: template.assistantPlacement,
+      rules: template.rules ?? {
+        required: [
+          "This entry is a fixed demo and is not schema-customizable.",
+          "Preview and download it as-is. Do not pass a config for this entry.",
+        ],
+      },
+      tools: { builtIn: [], customToolSupported: false, renderers: [] },
+      exampleConfig: null,
+      ...(template.previewUrl ? { previewUrl: template.previewUrl } : {}),
+      ...(template.downloadUrl ? { downloadUrl: template.downloadUrl } : {}),
+    };
+  }
+
+  const selectedVersionId = version?.id ?? template.versionId;
+
+  if (!template.configRoots || !template.tools) {
+    return {
+      error: `No authoring schema found for template "${template.templateId}".`,
+      retryHint:
+        "The catalog may be in degraded fallback mode. Retry when live catalog access is restored.",
+    };
+  }
+
+  let exampleConfig: Record<string, unknown> | null = null;
+  let exampleConfigNote: string;
+  if (template.sandboxBaseUrl) {
+    const contract = await fetchTemplateContract(
+      template.sandboxBaseUrl,
+      selectedVersionId,
+    );
+    exampleConfig =
+      (contract?.exampleCompleteConfig as Record<string, unknown> | null) ??
+      null;
+    exampleConfigNote = exampleConfig
+      ? `Resolved defaults for version "${selectedVersionId}". Use as a complete working starting point.`
+      : "Could not reach the template sandbox to resolve exampleConfig. Use configRoots schemas and defaults to author config manually.";
+  } else {
+    exampleConfigNote =
+      "This template has no sandbox URL in the catalog, so exampleConfig is unavailable. Use configRoots schemas and defaults.";
+  }
+
+  return {
+    id: template.templateId,
+    name: template.name,
+    selectedVersionId,
+    summary: template.summary,
+    assistantPlacement: template.assistantPlacement,
+    configRoots: template.configRoots,
+    rules: template.rules ?? { required: [] },
+    tools: template.tools,
+    exampleConfig,
+    exampleConfigNote,
+    ...(version?.previewUrl
+      ? { previewUrl: version.previewUrl }
+      : template.previewUrl
+        ? { previewUrl: template.previewUrl }
+        : {}),
+    ...(version?.downloadUrl
+      ? { downloadUrl: version.downloadUrl }
+      : template.downloadUrl
+        ? { downloadUrl: template.downloadUrl }
+        : {}),
+  };
+}
+
+function toAbsolute(baseUrl: string, url: string): string {
+  if (/^https?:\/\//.test(url)) return url;
+  return `${baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
+}
+
+function withVersion(url: string, versionId: string | undefined): string {
+  if (!versionId) return url;
+  const [path, query = ""] = url.split("?");
+  const params = new URLSearchParams(query);
+  if (!params.has("v")) params.set("v", versionId);
+  return `${path}?${params.toString()}`;
+}
+
+function hasConfig(config: Record<string, unknown> | undefined): boolean {
+  return !!config && Object.keys(config).length > 0;
+}
+
+export interface TemplatePreviewResult {
+  success: boolean;
+  templateId: string;
+  versionId: string | null;
+  previewUrl?: string;
+  downloadUrl?: string;
+  title?: string;
+  customized?: boolean;
+  validationWarnings?: unknown[];
+  error?: string;
+  retryHint?: string;
+  details?: string;
+  summary?: string;
+}
+
+export async function createTemplatePreview(
+  catalog: XuluxCatalog,
+  input: {
+    templateId: string;
+    versionId?: string | undefined;
+    config?: Record<string, unknown> | undefined;
+  },
+): Promise<TemplatePreviewResult> {
+  const resolved = resolveTemplate(catalog, input.templateId, input.versionId);
+  if (!resolved) {
+    return {
+      success: false,
+      templateId: input.templateId,
+      versionId: input.versionId ?? null,
+      error: `Template "${input.templateId}" not found.`,
+      retryHint:
+        "Call assistantUITemplates and use one of the returned template ids.",
+    };
+  }
+
+  const { template, version } = resolved;
+  const tid = template.templateId;
+
+  if (template.kind === "example") {
+    if (hasConfig(input.config)) {
+      return {
+        success: false,
+        templateId: tid,
+        versionId: null,
+        error: `Template "${tid}" is a fixed demo and does not support config.`,
+        retryHint:
+          "Call assistantUITemplateDetails for this template. If no configRoots are returned, call assistantUITemplatePreview again without config or choose a configurable hosted template.",
+      };
+    }
+
+    if (!template.previewUrl) {
+      return {
+        success: false,
+        templateId: tid,
+        versionId: null,
+        error: `Fixed demo "${tid}" has no preview URL in the catalog.`,
+        retryHint:
+          "The catalog may be in degraded fallback mode. Retry when live catalog access is restored.",
+      };
+    }
+
+    return {
+      success: true,
+      templateId: tid,
+      versionId: null,
+      previewUrl: template.previewUrl,
+      ...(template.downloadUrl ? { downloadUrl: template.downloadUrl } : {}),
+      title: template.name,
+      customized: false,
+      summary: `Resolved ${template.name} as a fixed demo. Preview and download URLs point at hosted resources; nothing was opened in any UI.`,
+    };
+  }
+
+  const baseUrl = template.sandboxBaseUrl;
+  if (!baseUrl) {
+    return {
+      success: false,
+      templateId: tid,
+      versionId: version?.id ?? template.versionId,
+      error: `Template "${tid}" has no sandbox URL in the catalog.`,
+      retryHint:
+        "The catalog may be in degraded fallback mode. Retry when live catalog access is restored.",
+    };
+  }
+
+  const effectiveVersionId = version?.id ?? template.versionId;
+
+  if (hasConfig(input.config)) {
+    try {
+      const sessionUrl = new URL("/api/preview/session", baseUrl);
+      if (effectiveVersionId)
+        sessionUrl.searchParams.set("v", effectiveVersionId);
+      const res = await fetchSandboxResource(sessionUrl.toString(), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(input.config),
+      });
+      if (!res.ok) {
+        const details = await res.text();
+        return {
+          success: false,
+          templateId: tid,
+          versionId: effectiveVersionId,
+          error: `Preview session failed: HTTP ${res.status}`,
+          details,
+          retryHint:
+            "Check validationWarnings for the specific fields that failed. " +
+            "Call assistantUITemplateDetails for this template and use configRoots schemas to correct the config. " +
+            "Pass only hostUi, assistant, and brandTheme at the top level.",
+        };
+      }
+      const data = (await res.json()) as {
+        previewUrl?: string;
+        downloadUrl?: string;
+        validationWarnings?: unknown[];
+      };
+      if (!data.previewUrl) {
+        return {
+          success: false,
+          templateId: tid,
+          versionId: effectiveVersionId,
+          error: "Session endpoint did not return a previewUrl.",
+        };
+      }
+      return {
+        success: true,
+        templateId: tid,
+        versionId: effectiveVersionId,
+        previewUrl: toAbsolute(
+          baseUrl,
+          withVersion(data.previewUrl, effectiveVersionId ?? undefined),
+        ),
+        downloadUrl: toAbsolute(
+          baseUrl,
+          withVersion(
+            data.downloadUrl ?? "/api/download",
+            effectiveVersionId ?? undefined,
+          ),
+        ),
+        title: version?.name ?? template.name,
+        customized: true,
+        summary: `Created a configured preview session for ${template.name}. URLs point at the hosted sandbox; nothing was opened in any UI.`,
+        validationWarnings: data.validationWarnings ?? [],
+      };
+    } catch (err) {
+      return {
+        success: false,
+        templateId: tid,
+        versionId: effectiveVersionId,
+        error: err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  const previewUrl = version?.previewUrl ?? template.previewUrl;
+  const downloadUrl =
+    version?.downloadUrl ?? template.downloadUrl ?? `${baseUrl}/api/download`;
+
+  return {
+    success: true,
+    templateId: tid,
+    versionId: effectiveVersionId,
+    previewUrl: previewUrl ?? baseUrl,
+    downloadUrl,
+    title: version?.name ?? template.name,
+    customized: false,
+    summary: `Resolved preview and download URLs for ${template.name}. Nothing was opened in any UI.`,
+  };
+}

package/src/xulux/types.ts

@@ -0,0 +1,60 @@
+// MCP-safe assistant-ui template catalog types. These mirror the payload served by the docs
+// app at GET /api/xulux/mcp-catalog. The MCP package never imports docs-app
+// internals; the endpoint payload is the contract.
+
+export const XULUX_MCP_CATALOG_VERSION = 1;
+
+export interface XuluxCatalogVersion {
+  id: string;
+  entryId: string;
+  name: string;
+  description: string;
+  previewUrl: string;
+  downloadUrl: string;
+}
+
+export interface XuluxCatalogTemplate {
+  id: string;
+  templateId: string;
+  versionId: string | null;
+  kind: "template" | "example";
+  name: string;
+  summary: string;
+  assistantPlacement: string;
+  features: string[];
+  customizable: string[];
+  versions: XuluxCatalogVersion[];
+  previewUrl?: string;
+  downloadUrl?: string;
+  sandboxBaseUrl?: string;
+  configRoots?: Record<string, unknown>;
+  rules?: {
+    required: string[];
+    unsupported?: string[];
+  };
+  tools?: {
+    builtIn: unknown[];
+    customToolSupported: boolean;
+    renderers: unknown[];
+  };
+}
+
+export interface XuluxCatalog {
+  version: number;
+  generatedAt: string;
+  docsOrigin: string;
+  templates: XuluxCatalogTemplate[];
+}
+
+export interface XuluxCatalogResult {
+  catalog: XuluxCatalog;
+  /** True when the bundled fallback catalog was used instead of live data. */
+  degraded: boolean;
+  /** Present when the live fetch failed and the fallback was used. */
+  degradedReason?: string;
+}
+
+export interface XuluxCatalogError {
+  error: string;
+  hint?: string;
+}

package/.docs/raw/blog/2024-07-29-hello/index.mdx

@@ -1,64 +0,0 @@
----
-title: Hello, assistant-ui
-description: assistant-ui is an open-source AI chat component for React.
-author: Simon Farshid
-date: 2024-07-29T12:00:00
----
-
-import Image from "next/image";
-import { TestimonialContainer } from "@/components/home/testimonials/testimonials";
-import { BLOG_TESTIMONIALS } from "@/components/home/testimonials/data";
-import npmDownloads from "./npm-downloads.png";
-import assistantUi from "./assistant-ui-screenshot.png";
-
-After spending the last two years building Gen-AI prototypes and products, I realized that all software will soon have a natural language interface. OpenAI's ChatGPT sets the quality bar high and I wanted to have a similar UX in my own apps. No solution on the market came anywhere close, so I built assistant-ui.
-
-assistant-ui is an open-source, embeddable, customizable AI chat component for React web apps. You can use it to build GPT wrappers, in-app copilots, or agentic systems. It supports rich content (markdown, code highlighting, charts, tables), generative UI, message editing, ..., across all the major model providers.
-
-<Image
-  src={assistantUi}
-  alt="screenshot of assistant-ui"
-  width={398}
-  height={498}
-  className="mx-auto rounded-xl border drop-shadow"
-/>
-
-Earlier last month, I released the project to the world. The feedback from early adopters has been overwhelmingly positive:
-
-<div className="not-prose mx-auto max-w-md">
-  <TestimonialContainer testimonials={BLOG_TESTIMONIALS} />
-</div>
-
-It didn't take long for developers to start building with assistant-ui. Here are some of my favorite products from the community:
-
-- [Helicone](https://helicone.ai/) - open-source LLM observability platform
-- [screenpipe](https://screenpi.pe/) - AI to remember everything you see, say or hear
-- [myresume.guru](http://myresume.guru) - AI resume optimizer to land your dream job
-
-With 250+ stars on [GitHub](https://github.com/assistant-ui/assistant-ui) and over 1k [npm](https://www.npmjs.com/package/@assistant-ui/react) weekly downloads, we got a vibrant growing community of developers who care about the user experience.
-
-<Image
-  src={npmDownloads}
-  alt="graph showing 1355 weekly npm downloads"
-  width={381}
-  height={94}
-  className="mx-auto dark:hue-rotate-180 dark:invert"
-/>
-
-I want to thank the following contributors who got the project to where it is today:
-
-- [@m13v](https://github.com/m13v) for contributing two examples and several how-to videos
-- [@okisdev](https://github.com/okisdev) for multiple bugfixes
-- [@Rajaniraiyn](https://github.com/Rajaniraiyn) for improving streaming support for REST APIs
-- @ccbkai for integrating Chrome's `window.ai` with assistant-ui
-- [@stingfeng](https://github.com/stingfeng/dify-extensions) for building a [Dify](https://dify.ai) integration
-- [@Ephibbs](https://github.com/Ephibbs/flowtoken) for building a Perplexity-style text streaming library ([Demo](https://assistant-ui-flowtoken-demo.vercel.app/))
-- … and so many others
-
-assistant-ui builds on top of [Radix UI](https://www.radix-ui.com/), [Tailwind](https://tailwindcss.com/), [shadcn/ui](https://ui.shadcn.com/), [Vercel AI SDK](https://sdk.vercel.ai/docs/introduction) and other amazing open-source projects.
-
-Over the coming month, I'll be rolling out multimodal support, so you can use your voice and upload images. There's so much more in the pipeline that I can't wait to unveil!
-
-Today, several companies like [Helicone (YC W23)](https://x.com/justinstorre/status/1816849882612904156) are using assistant-ui to power a core part of their product. If your company wants to do the same, please [get in touch](https://cal.com/simon-farshid/assistant-ui).
-
-If you're building conversational AI, join us on [Discord](https://discord.gg/S9dwgCNEFs). If you're technical and want to shape how we interact with AIs of the future, [send me an email](mailto:simon@assistant-ui.com).

package/.docs/raw/blog/2024-09-11/index.mdx

@@ -1,10 +0,0 @@
----
-title: Build conversational AI agents with LangGraph and assistant-ui
-description: Announcing our collaboration with LangChain
-author: Harrison Chase
-date: 2024-09-11T12:00:00
----
-
-import { Redirect } from "./redirect";
-
-<Redirect />

package/.docs/raw/blog/2024-12-15/index.mdx

@@ -1,10 +0,0 @@
----
-title: Announcing github-assistant
-description: github-assistant answers questions about your GitHub repositories.
-author: Amir Zohrenejad
-date: 2024-12-15T12:00:00
----
-
-import { Redirect } from "./redirect";
-
-<Redirect />

package/.docs/raw/blog/2025-01-31-changelog/index.mdx

@@ -1,127 +0,0 @@
----
-title: January 2025 Changelog
-description: shadcn/ui, Thread Management, Improvements to AI SDK and LangGraph support
-author: Simon Farshid
-date: 2025-01-31T12:00:00
----
-
-<Callout emoji="🎉">
-  This is the first edition of our changelog. We post these updates on a monthly
-  basis. If you want more frequent updates about our new features, join our
-  Discord where we have a `#changelog` channel that is updated on a daily basis.
-</Callout>
-
-## Summary
-
-In January, we shipped 36 new versions of our package `@assistant-ui/react`. We also crossed 10k weekly downloads on npm for the first time. 🎉
-
-## shadcn/ui CLI support
-
-You can now install all components using the shadcn CLI, e.g.
-
-```sh
-npx shadcn@latest add "https://r.assistant-ui.com/thread"
-```
-
-We began a migration towards distributing our components as unstyled primitives and using the shadcn CLI to drop styles in your project.
-
-## Styled components moved to @assistant-ui/react-ui
-
-All styled components (Thread, ThreadList, AssistantModal, makeMarkdownText, etc.) have been moved to a new package, `@assistant-ui/ui`.
-
-To ease the migration, we added a migration codemod:
-
-```sh
-npx assistant-ui upgrade
-```
-
-This will update your codebase to use the new package. This new package remains supported, however, based on the learnings from existing users, we recommend all new projects to use our shadcn/ui CLI instead.
-
-## Customizing the max-width of the Thread
-
-You can now customize the max-width of the thread via `--aui-thread-max-width` CSS variable.
-
-## Thread Management
-
-One of our main focus areas in this month was on the new Thread Management API. The new ThreadList API is available under `runtime.threads`. It allows you to create, switch to, rename, archive, and delete threads.
-
-We shipped a `<ThreadList />` component which gives the user the UI to manage their threads.
-
-We also shipped a few hooks `useThreadListItem()`, `useThreadListItemRuntime()`, `useRemoteThreadListRuntime()` and `useCloudThreadListRuntime()`.
-
-## Assistant Cloud
-
-We rolled out the new Assistant Cloud service to early users. This is a managed service for persistence, chat history, and thread management.
-Our runtimes are being upgraded to support Assistant Cloud natively by letting you pass a `cloud` object to the runtime hook.
-
-Keep an eye out for the public announcement of Assistant Cloud in a few days.
-
-## Improvements to our LangGraph Integration
-
-- We now have full support for LangGraph's `interrupt()`/`Command` API. You can check out the new example repository [here](https://github.com/assistant-ui/assistant-ui-langgraph-interrupt).
-- We now also support starting LangGraph runs without a user message (based on button input or other events).
-- Cancellation of runs is now supported via an `abortSignal` being passed to the LangGraph runtime adapter.
-
-## Improvements to our AI SDK Integration
-
-We now give you access to annotations and data packets in the assistant message:
-
-```tsx
-type AssistantMessage = {
-  metadata: {
-    unstable_annotations: [...],
-    unstable_data: [...],
-  }
-}
-```
-
-## AI SDK recommended for new projects
-
-For new projects, we recommend using the AI SDK integration. Previously, we recommended our custom SDK called `useEdgeRuntime`.  
-With our improved AI SDK integration, we believe it is time to recommend AI SDK for new projects, giving you access to the AI SDK ecosystem.
-
-The edge runtime remains maintained and supported for existing projects.
-
-## Misc
-
-- **Refactors & API Enhancements**:
-
-  - Renamed `ModelConfig` to `ModelContext`.
-  - Moved `switchToThread / switchToNewThread` under `runtime.threads`.
-  - Deprecated `UIContentPart`.
-  - `ToolCallContentPart.args` is now a `JSONObject`.
-  - `MessagePrimitive.tools.Override` introduced.
-  - Added `AppendMessage.sourceId` to provide better tracking.
-  - Reverse order of threads in `useRemoteThreadListRuntime` for better visibility.
-  - Added `threads.getById` and `threads.main` APIs.
-  - Introduced `AssistantCloudThreadHistoryAdapter` to handle cloud-based thread history.
-  - Auto-injection of history adapter in the local runtime.
-  - Tool call `id` + `args` are now optional in `ThreadMessageLike`.
-  - Added `ThreadListPrimitive.Root`.
-  - `ComposerRuntime.clearAttachments` API added.
-  - Improved input support for IME keyboards (e.g., Chinese, Japanese, Korean).
-  - Moved repository to a new GitHub organization (`assistant-ui/assistant-ui`).
-
-- **External Store & Data Handling**:
-
-  - Enhanced `ExternalStoreAdapter` to support metadata and attachments.
-  - Renamed `getExternalStoreMessage` to `getExternalStoreMessages`.
-  - Tool call `args` streaming support in our Python SDK.
-
-- **User Interface & Styling**:
-
-  - Styled UI assistant message footer.
-  - Improved attachment filename handling to prevent overflow.
-  - Renamed CSS class to `aui-thread-welcome-suggestions`.
-
-- **Performance Optimizations**:
-
-  - Memoized `MessageRepository.getMessages()` for better efficiency.
-  - Marked `ChatAdapter` types as readonly.
-
-- **Bug Fixes**:
-
-  - Fixed event subscription issues in thread lists.
-  - Fixed import errors in React server environments.
-  - Prevented excessive classes being included via TailwindCSS.
-  - Fixed AI SDK annotation packet errors.