@assistant-ui/mcp-docs-server 0.1.38 → 0.2.0

package/dist/xulux/fallback-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fallback-catalog.js","names":[],"sources":["../../src/xulux/fallback-catalog.ts"],"sourcesContent":["import {\n  XULUX_MCP_CATALOG_VERSION,\n  type XuluxCatalog,\n  type XuluxCatalogTemplate,\n} from \"./types.js\";\n\n// Minimal bundled fallback catalog for degraded mode. It supports discovery\n// (ids + names) only. Full authoring details and preview/download URLs\n// require the live catalog endpoint. Do NOT grow this into a copy of the\n// full template knowledge base — the docs endpoint owns freshness.\n\nexport const FALLBACK_NOTE =\n  \"The live assistant-ui template catalog could not be fetched, so this is minimal bundled fallback data. \" +\n  \"Template details, previews, and downloads require live catalog access. \" +\n  \"Check network access to the docs site or set XULUX_CATALOG_URL to a reachable catalog endpoint.\";\n\nconst fallbackTemplate = (\n  overrides: Pick<XuluxCatalogTemplate, \"id\" | \"kind\" | \"name\" | \"summary\">,\n): XuluxCatalogTemplate => ({\n  templateId: overrides.id,\n  versionId: null,\n  assistantPlacement: \"unavailable in fallback mode\",\n  features: [],\n  customizable: [],\n  versions: [],\n  ...overrides,\n});\n\nexport const FALLBACK_CATALOG: XuluxCatalog = {\n  version: XULUX_MCP_CATALOG_VERSION,\n  generatedAt: \"fallback\",\n  docsOrigin: \"https://www.assistant-ui.com\",\n  templates: [\n    fallbackTemplate({\n      id: \"base-assistant-ui\",\n      kind: \"template\",\n      name: \"Configurable Base Assistant UI\",\n      summary:\n        \"Hosted configurable assistant-ui Base chat template with threads, composer, suggestions, and no-key demo flows.\",\n    }),\n    fallbackTemplate({\n      id: \"webpage-assistant\",\n      kind: \"template\",\n      name: \"Webpage with Assistant\",\n      summary:\n        \"Docs/website layout with a sidebar or modal assistant grounded in configurable pages.\",\n    }),\n    fallbackTemplate({\n      id: \"product-page-assistant\",\n      kind: \"template\",\n      name: \"Product Page with Floating Assistant\",\n      summary:\n        \"Mock product dashboard with a floating modal support assistant and analyze-then-handoff flow.\",\n    }),\n    fallbackTemplate({\n      id: \"expo-react-native\",\n      kind: \"example\",\n      name: \"Expo React Native Assistant\",\n      summary:\n        \"Mobile AI chat app built with Expo and assistant-ui React Native primitives.\",\n    }),\n  ],\n};\n"],"mappings":";;AAWA,MAAa,gBACX;AAIF,MAAM,oBACJ,eAC0B;CAC1B,YAAY,UAAU;CACtB,WAAW;CACX,oBAAoB;CACpB,UAAU,CAAC;CACX,cAAc,CAAC;CACf,UAAU,CAAC;CACX,GAAG;AACL;AAEA,MAAa,mBAAiC;CAC5C,SAAA;CACA,aAAa;CACb,YAAY;CACZ,WAAW;EACT,iBAAiB;GACf,IAAI;GACJ,MAAM;GACN,MAAM;GACN,SACE;EACJ,CAAC;EACD,iBAAiB;GACf,IAAI;GACJ,MAAM;GACN,MAAM;GACN,SACE;EACJ,CAAC;EACD,iBAAiB;GACf,IAAI;GACJ,MAAM;GACN,MAAM;GACN,SACE;EACJ,CAAC;EACD,iBAAiB;GACf,IAAI;GACJ,MAAM;GACN,MAAM;GACN,SACE;EACJ,CAAC;CACH;AACF"}

package/dist/xulux/fetch-sandbox.d.ts

@@ -0,0 +1,5 @@
+//#region src/xulux/fetch-sandbox.d.ts
+declare function fetchSandboxResource(url: string | URL, init?: RequestInit): Promise<Response>;
+//#endregion
+export { fetchSandboxResource };
+//# sourceMappingURL=fetch-sandbox.d.ts.map

package/dist/xulux/fetch-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-sandbox.d.ts","names":[],"sources":["../../src/xulux/fetch-sandbox.ts"],"mappings":";iBAgCsB,qBACpB,cAAc,KACd,OAAO,cACN,QAAQ"}

package/dist/xulux/fetch-sandbox.js

@@ -0,0 +1,40 @@
+//#region src/xulux/fetch-sandbox.ts
+const SANDBOX_FETCH_HEADERS = {
+	Accept: "application/json, application/zip, application/octet-stream, */*",
+	"User-Agent": "curl/8.7.1"
+};
+const MAX_ATTEMPTS = 3;
+const RETRY_DELAY_MS = 300;
+function isRetryableFetchError(error) {
+	if (!(error instanceof Error)) return false;
+	const code = error.cause?.code ?? error.message;
+	return code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ECONNREFUSED" || code === "fetch failed";
+}
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function mergeHeaders(headers) {
+	const merged = new Headers(SANDBOX_FETCH_HEADERS);
+	if (!headers) return merged;
+	new Headers(headers).forEach((value, key) => merged.set(key, value));
+	return merged;
+}
+async function fetchSandboxResource(url, init) {
+	let lastError;
+	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) try {
+		return await fetch(url, {
+			...init,
+			cache: "no-store",
+			headers: mergeHeaders(init?.headers)
+		});
+	} catch (error) {
+		lastError = error;
+		if (!isRetryableFetchError(error) || attempt === MAX_ATTEMPTS) throw error;
+		await sleep(RETRY_DELAY_MS * attempt);
+	}
+	throw lastError;
+}
+//#endregion
+export { fetchSandboxResource };
+
+//# sourceMappingURL=fetch-sandbox.js.map

package/dist/xulux/fetch-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-sandbox.js","names":[],"sources":["../../src/xulux/fetch-sandbox.ts"],"sourcesContent":["const SANDBOX_FETCH_HEADERS = {\n  Accept: \"application/json, application/zip, application/octet-stream, */*\",\n  // Blaxel preview hosts intermittently reset Node's default fetch path.\n  \"User-Agent\": \"curl/8.7.1\",\n};\n\nconst MAX_ATTEMPTS = 3;\nconst RETRY_DELAY_MS = 300;\n\nfunction isRetryableFetchError(error: unknown) {\n  if (!(error instanceof Error)) return false;\n  const cause = error.cause as { code?: string } | undefined;\n  const code = cause?.code ?? error.message;\n  return (\n    code === \"ECONNRESET\" ||\n    code === \"ETIMEDOUT\" ||\n    code === \"ECONNREFUSED\" ||\n    code === \"fetch failed\"\n  );\n}\n\nfunction sleep(ms: number) {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\nfunction mergeHeaders(headers?: HeadersInit): Headers {\n  const merged = new Headers(SANDBOX_FETCH_HEADERS);\n  if (!headers) return merged;\n  new Headers(headers).forEach((value, key) => merged.set(key, value));\n  return merged;\n}\n\nexport async function fetchSandboxResource(\n  url: string | URL,\n  init?: RequestInit,\n): Promise<Response> {\n  let lastError: unknown;\n\n  for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {\n    try {\n      return await fetch(url, {\n        ...init,\n        cache: \"no-store\",\n        headers: mergeHeaders(init?.headers),\n      });\n    } catch (error) {\n      lastError = error;\n      if (!isRetryableFetchError(error) || attempt === MAX_ATTEMPTS) {\n        throw error;\n      }\n      await sleep(RETRY_DELAY_MS * attempt);\n    }\n  }\n\n  throw lastError;\n}\n"],"mappings":";AAAA,MAAM,wBAAwB;CAC5B,QAAQ;CAER,cAAc;AAChB;AAEA,MAAM,eAAe;AACrB,MAAM,iBAAiB;AAEvB,SAAS,sBAAsB,OAAgB;CAC7C,IAAI,EAAE,iBAAiB,QAAQ,OAAO;CAEtC,MAAM,OADQ,MAAM,OACA,QAAQ,MAAM;CAClC,OACE,SAAS,gBACT,SAAS,eACT,SAAS,kBACT,SAAS;AAEb;AAEA,SAAS,MAAM,IAAY;CACzB,OAAO,IAAI,SAAS,YAAY,WAAW,SAAS,EAAE,CAAC;AACzD;AAEA,SAAS,aAAa,SAAgC;CACpD,MAAM,SAAS,IAAI,QAAQ,qBAAqB;CAChD,IAAI,CAAC,SAAS,OAAO;CACrB,IAAI,QAAQ,OAAO,CAAC,CAAC,SAAS,OAAO,QAAQ,OAAO,IAAI,KAAK,KAAK,CAAC;CACnE,OAAO;AACT;AAEA,eAAsB,qBACpB,KACA,MACmB;CACnB,IAAI;CAEJ,KAAK,IAAI,UAAU,GAAG,WAAW,cAAc,WAAW,GACxD,IAAI;EACF,OAAO,MAAM,MAAM,KAAK;GACtB,GAAG;GACH,OAAO;GACP,SAAS,aAAa,MAAM,OAAO;EACrC,CAAC;CACH,SAAS,OAAO;EACd,YAAY;EACZ,IAAI,CAAC,sBAAsB,KAAK,KAAK,YAAY,cAC/C,MAAM;EAER,MAAM,MAAM,iBAAiB,OAAO;CACtC;CAGF,MAAM;AACR"}

package/dist/xulux/template-service.d.ts

@@ -0,0 +1,84 @@
+import { XuluxCatalog, XuluxCatalogTemplate, XuluxCatalogVersion } from "./types.js";
+//#region src/xulux/template-service.d.ts
+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
+ */
+declare function resolveTemplate(catalog: XuluxCatalog, templateId: string, versionId?: string | undefined): ResolvedTemplate | null;
+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";
+}
+declare function listTemplates(catalog: XuluxCatalog): {
+  templates: TemplateListItem[];
+};
+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;
+}
+interface TemplateError {
+  error: string;
+  retryHint?: string;
+}
+declare function getTemplateDetails(catalog: XuluxCatalog, input: {
+  templateId: string;
+  versionId?: string | undefined;
+}): Promise<TemplateDetails | TemplateError>;
+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;
+}
+declare function createTemplatePreview(catalog: XuluxCatalog, input: {
+  templateId: string;
+  versionId?: string | undefined;
+  config?: Record<string, unknown> | undefined;
+}): Promise<TemplatePreviewResult>;
+//#endregion
+export { ResolvedTemplate, TemplateDetails, TemplateError, TemplateListItem, TemplatePreviewResult, createTemplatePreview, getTemplateDetails, listTemplates, resolveTemplate };
+//# sourceMappingURL=template-service.d.ts.map

package/dist/xulux/template-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-service.d.ts","names":[],"sources":["../../src/xulux/template-service.ts"],"mappings":";;UAYiB;EACf,UAAU;EACV,SAAS;;;;;;;;;;iBAWK,gBACd,SAAS,cACT,oBACA,iCACC;UA6Bc;EACf;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;IAAQ;IAAY;IAAc;;EAC5C;;iBAGc,cAAc,SAAS;EACrC,WAAW;;UAmCI;EACf;EACA;EACA;EACA;EACA;EACA,cAAc;EACd;IACE;IACA;;EAEF;IACE;IACA;IACA;;EAEF,eAAe;EACf;EACA;EACA;EACA;;UAGe;EACf;EACA;;iBAGoB,mBACpB,SAAS,cACT;EAAS;EAAoB;IAC5B,QAAQ,kBAAkB;UAqGZ;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;iBAGoB,sBACpB,SAAS,cACT;EACE;EACA;EACA,SAAS;IAEV,QAAQ"}

package/dist/xulux/template-service.js

@@ -0,0 +1,223 @@
+import { fetchSandboxResource } from "./fetch-sandbox.js";
+//#region src/xulux/template-service.ts
+/**
+* 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
+*/
+function resolveTemplate(catalog, templateId, versionId) {
+	let template = catalog.templates.find((t) => t.templateId === templateId || t.id === templateId);
+	let impliedVersionId;
+	if (!template) {
+		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
+	};
+}
+function listTemplates(catalog) {
+	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, versionId) {
+	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();
+	} catch {
+		return null;
+	}
+}
+async function getTemplateDetails(catalog, input) {
+	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 = null;
+	let exampleConfigNote;
+	if (template.sandboxBaseUrl) {
+		exampleConfig = (await fetchTemplateContract(template.sandboxBaseUrl, selectedVersionId))?.exampleCompleteConfig ?? 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, url) {
+	if (/^https?:\/\//.test(url)) return url;
+	return `${baseUrl}${url.startsWith("/") ? "" : "/"}${url}`;
+}
+function withVersion(url, versionId) {
+	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) {
+	return !!config && Object.keys(config).length > 0;
+}
+async function createTemplatePreview(catalog, input) {
+	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();
+		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 ?? void 0)),
+			downloadUrl: toAbsolute(baseUrl, withVersion(data.downloadUrl ?? "/api/download", effectiveVersionId ?? void 0)),
+			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.`
+	};
+}
+//#endregion
+export { createTemplatePreview, getTemplateDetails, listTemplates, resolveTemplate };
+
+//# sourceMappingURL=template-service.js.map

package/dist/xulux/template-service.js.map

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

package/dist/xulux/types.d.ts

@@ -0,0 +1,55 @@
+//#region src/xulux/types.d.ts
+declare const XULUX_MCP_CATALOG_VERSION = 1;
+interface XuluxCatalogVersion {
+  id: string;
+  entryId: string;
+  name: string;
+  description: string;
+  previewUrl: string;
+  downloadUrl: string;
+}
+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[];
+  };
+}
+interface XuluxCatalog {
+  version: number;
+  generatedAt: string;
+  docsOrigin: string;
+  templates: XuluxCatalogTemplate[];
+}
+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;
+}
+interface XuluxCatalogError {
+  error: string;
+  hint?: string;
+}
+//#endregion
+export { XULUX_MCP_CATALOG_VERSION, XuluxCatalog, XuluxCatalogError, XuluxCatalogResult, XuluxCatalogTemplate, XuluxCatalogVersion };
+//# sourceMappingURL=types.d.ts.map

package/dist/xulux/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/xulux/types.ts"],"mappings":";cAIa;UAEI;EACf;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,UAAU;EACV;EACA;EACA;EACA,cAAc;EACd;IACE;IACA;;EAEF;IACE;IACA;IACA;;;UAIa;EACf;EACA;EACA;EACA,WAAW;;UAGI;EACf,SAAS;;EAET;;EAEA;;UAGe;EACf;EACA"}

package/dist/xulux/types.js

@@ -0,0 +1,6 @@
+//#region src/xulux/types.ts
+const XULUX_MCP_CATALOG_VERSION = 1;
+//#endregion
+export { XULUX_MCP_CATALOG_VERSION };
+
+//# sourceMappingURL=types.js.map

package/dist/xulux/types.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/mcp-docs-server",
-  "version": "0.1.38",
+  "version": "0.2.0",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -32,15 +32,16 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/server": "^2.0.0",
     "gray-matter": "^4.0.3",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0",
-    "tsx": "^4.22.4",
-    "vitest": "^4.1.9",
-    "@assistant-ui/x-buildutils": "0.0.17"
+    "@modelcontextprotocol/core": "^2.0.0",
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "vitest": "^4.1.10",
+    "@assistant-ui/x-buildutils": "0.0.20"
   },
   "publishConfig": {
     "access": "public",

package/src/index.ts

@@ -1,8 +1,14 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { docsTools } from "./tools/docs.js";
 import { examplesTools } from "./tools/examples.js";
 import { searchTools } from "./tools/search.js";
+import {
+  xuluxTemplatesListTool,
+  xuluxTemplateDetailsTool,
+  xuluxTemplatePreviewTool,
+} from "./tools/xulux-templates.js";
+import { xuluxPlaygroundPrompt } from "./prompts/xulux-playground.js";
 import { registerResources } from "./tools/resources.js";
 import { logger } from "./utils/logger.js";
 import { PACKAGE_DIR } from "./constants.js";
@@ -50,6 +56,53 @@ server.registerTool(
   searchTools.execute,
 );
 
+server.registerTool(
+  xuluxTemplatesListTool.name,
+  {
+    title: "assistant-ui Templates",
+    description: xuluxTemplatesListTool.description,
+    inputSchema: xuluxTemplatesListTool.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  xuluxTemplatesListTool.execute,
+);
+server.registerTool(
+  xuluxTemplateDetailsTool.name,
+  {
+    title: "assistant-ui Template Details",
+    description: xuluxTemplateDetailsTool.description,
+    inputSchema: xuluxTemplateDetailsTool.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  xuluxTemplateDetailsTool.execute,
+);
+server.registerTool(
+  xuluxTemplatePreviewTool.name,
+  {
+    title: "assistant-ui Template Preview URLs",
+    description: xuluxTemplatePreviewTool.description,
+    inputSchema: xuluxTemplatePreviewTool.parameters,
+    annotations: { readOnlyHint: false, openWorldHint: true },
+  },
+  xuluxTemplatePreviewTool.execute,
+);
+
+server.registerPrompt(
+  xuluxPlaygroundPrompt.name,
+  {
+    title: "assistant-ui Template Workflow",
+    description: xuluxPlaygroundPrompt.description,
+  },
+  () => ({
+    messages: [
+      {
+        role: "user" as const,
+        content: { type: "text" as const, text: xuluxPlaygroundPrompt.text },
+      },
+    ],
+  }),
+);
+
 registerResources(server);
 
 export async function runServer() {

package/src/prompts/xulux-playground.ts

@@ -0,0 +1,36 @@
+// Skill-style MCP prompt teaching agents the assistant-ui template workflow.
+// Adapted for MCP clients: tools return URLs and data only; there is no
+// browser canvas UI here.
+
+export const XULUX_PLAYGROUND_PROMPT_NAME = "assistant-ui-template-workflow";
+
+export const XULUX_PLAYGROUND_PROMPT_DESCRIPTION =
+  "How to use the assistant-ui template tools to discover hosted templates, inspect their customization contracts, and retrieve preview/download URLs.";
+
+export const XULUX_PLAYGROUND_PROMPT = `You have access to assistant-ui template tools for hosted app templates.
+
+<workflow>
+Follow this template-first workflow for any assistant-ui app-building request:
+
+1. Call **assistantUITemplates** FIRST. Never decide on a template or claim one exists without listing.
+2. Call **assistantUITemplateDetails** on any candidate template before deciding whether it fits.
+   - Review the whole template shape: features, assistantPlacement, configRoots schemas, rules, built-in tools, renderers, and exampleConfig.
+   - If \`customizable\` is empty, the entry is a fixed demo. Use it as-is; never pass a config for it.
+3. Decide one of three paths:
+   - The template fits as-is: call **assistantUITemplatePreview** with templateId and optional versionId.
+   - The template fits with supported customization: author a config using the configRoots schemas and rules from assistantUITemplateDetails, then call **assistantUITemplatePreview** with that config.
+   - No template fits: do NOT call assistantUITemplatePreview. Do not force the request into a template or fake domain content with mock config. Instead, ground yourself in the assistant-ui docs (assistantUIDocs, assistantUISearch, assistantUIExamples) and produce an honest, docs-grounded build guide or prompt for the user.
+</workflow>
+
+<important_constraints>
+- Only use URLs copied exactly from tool results. Never guess, fabricate, or use placeholder URLs.
+- If assistantUITemplatePreview returns validationWarnings or an error, call assistantUITemplateDetails again and correct the config against configRoots. Pass only the documented top-level config roots.
+- Customization is for supported adaptation within a template's shape, not for turning it into a completely different kind of product.
+- Responses may include \`catalogDegraded: true\` when the live template catalog is unreachable. In that mode, template details and preview URLs may be unavailable; tell the user rather than improvising.
+</important_constraints>`;
+
+export const xuluxPlaygroundPrompt = {
+  name: XULUX_PLAYGROUND_PROMPT_NAME,
+  description: XULUX_PLAYGROUND_PROMPT_DESCRIPTION,
+  text: XULUX_PLAYGROUND_PROMPT,
+};