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

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.36",
+  "version": "0.1.39",
   "description": "MCP server for assistant-ui documentation and examples",
   "keywords": [
     "mcp",
@@ -37,10 +37,10 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.0.0",
-    "tsx": "^4.22.4",
-    "vitest": "^4.1.9",
-    "@assistant-ui/x-buildutils": "0.0.16"
+    "@types/node": "^26.1.1",
+    "tsx": "^4.23.1",
+    "vitest": "^4.1.10",
+    "@assistant-ui/x-buildutils": "0.0.18"
   },
   "publishConfig": {
     "access": "public",

package/src/constants.ts

@@ -17,6 +17,8 @@ export const MD_EXTENSION = ".md";
 
 export const MAX_FILE_SIZE = 10 * 1024 * 1024;
 
+export const MAX_DIRECTORY_CONTENT_SIZE = 1024 * 1024;
+
 export const IS_PREPARE_MODE = process.argv[1]?.includes(
   "prepare-docs/prepare",
 );

package/src/index.ts

@@ -2,6 +2,14 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 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";
 
@@ -37,6 +45,65 @@ server.registerTool(
   },
   examplesTools.execute,
 );
+server.registerTool(
+  searchTools.name,
+  {
+    title: "Search assistant-ui Documentation",
+    description: searchTools.description,
+    inputSchema: searchTools.parameters,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  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() {
   try {

package/src/prepare-docs/copy-raw.ts

@@ -4,7 +4,6 @@ import { logger } from "../utils/logger.js";
 import { ROOT_DIR } from "../constants.js";
 
 const DOCS_SOURCE = join(ROOT_DIR, "apps/docs/content/docs");
-const BLOG_SOURCE = join(ROOT_DIR, "apps/docs/content/blog");
 const DOCS_DEST = join(ROOT_DIR, "packages/mcp-docs-server/.docs/raw");
 
 async function copyDir(src: string, dest: string): Promise<void> {
@@ -43,10 +42,6 @@ export async function copyRaw(): Promise<void> {
     await copyDir(DOCS_SOURCE, docsPath);
     logger.info(`Copied documentation to ${docsPath}`);
 
-    const blogPath = join(DOCS_DEST, "blog");
-    await copyDir(BLOG_SOURCE, blogPath);
-    logger.info(`Copied blog posts to ${blogPath}`);
-
     logger.info("Raw documentation copy complete");
   } catch (error) {
     logger.error("Failed to copy raw documentation", error);

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,
+};