v0.5.7 (#411)

* feat: introducing customHome config option (#397)

* fix: include tsx files in tsconfig for gpt-apps and mcp-apps default templates

The default templates for both GPT apps and MCP apps contained .tsx files but their tsconfig.json was only including .ts files. Added jsx compiler option and .tsx file pattern to match the tailwind template configuration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* unit tests for updateTsConfig function and support updating path aliases on setup (#399)

* feat: skip type check on nextjs adapter mode (#400)

* feat: upd adapter mode tool gen syntax (#401)

* feat: add CSS module type declarations for zero-config ts support

* feat: docs sidebar w/ toggleable func (#403)

* apply font-family once on body

* add CSS documentation to core concepts

* improve CSS docs and ordering

* feat: example initialization via cli (#406)

* feat: example initialization via cli

* remove templates parent directory + upd next steps

* rmv auto-detection

* next steps to handle directory

* add globals.css auto-detection and update docs

* ignore example metadata folder (#408)

* add engineering category

* add blog post on MCP UI components (#409)

* add blog post on MCP UI components

* always bet on react

* copywriting nitpicks

* upload image + upd date

---------

Co-authored-by: Francisco Veiras <74626997+francisco-svg761@users.noreply.github.com>
Co-authored-by: valebearzotti <valebearzotti1@gmail.com>

* downloadTarStream handle download status (#412)

* add safety checks to the --example path (#413)

---------

Co-authored-by: Mauricio Dottavio <dottavio@gmail.com>
Co-authored-by: Francisco Veiras <74626997+francisco-svg761@users.noreply.github.com>
Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>
Co-authored-by: Francisco Veiras <74626997+fveiraswww@users.noreply.github.com>

Author: 4 people

apps/website/components/layout/docs.tsx

@@ -1,12 +1,52 @@
 "use client";
 import type * as PageTree from "fumadocs-core/page-tree";
-import { type ReactNode, useMemo } from "react";
+import { type ReactNode, useEffect, useMemo, useState } from "react";
 import { cn } from "../../lib/cn";
 import { TreeContextProvider, useTreeContext } from "fumadocs-ui/contexts/tree";
 import Link from "fumadocs-core/link";
 import { useSidebar } from "fumadocs-ui/contexts/sidebar";
 import { cva } from "class-variance-authority";
 import { usePathname } from "fumadocs-core/framework";
+import {
+  getSeparatorId,
+  useSidebarOpenState,
+} from "@/hooks/use-sidebar-open-state";
+import { Icons } from "../icons";
+
+type SeparatorNode = Extract<PageTree.Node, { type: "separator" }>;
+type GroupedItem =
+  | { type: "group"; separator: SeparatorNode; items: PageTree.Node[] }
+  | { type: "item"; item: PageTree.Node };
+
+function groupBySeparator(items: PageTree.Node[]): GroupedItem[] {
+  const grouped: GroupedItem[] = [];
+  let currentGroup: {
+    separator: SeparatorNode;
+    items: PageTree.Node[];
+  } | null = null;
+
+  for (const item of items) {
+    if (item.type === "separator") {
+      if (currentGroup) {
+        grouped.push({ type: "group", ...currentGroup });
+      }
+      currentGroup = { separator: item, items: [] };
+      continue;
+    }
+
+    if (currentGroup) {
+      currentGroup.items.push(item);
+    } else {
+      grouped.push({ type: "item", item });
+    }
+  }
+
+  if (currentGroup) {
+    grouped.push({ type: "group", ...currentGroup });
+  }
+
+  return grouped;
+}
 
 export interface DocsLayoutProps {
   tree: PageTree.Root;
@@ -30,20 +70,54 @@ export function DocsLayout({ tree, children }: DocsLayoutProps) {
 function Sidebar() {
   const { root } = useTreeContext();
   const { open } = useSidebar();
+  const { openState, toggle, initialOpenSnapshot } = useSidebarOpenState(root);
 
   const children = useMemo(() => {
     function renderItems(items: PageTree.Node[]) {
-      return items.map((item) => {
+      return groupBySeparator(items).map((entry, index) => {
+        if (entry.type === "group") {
+          const separatorId = getSeparatorId(entry.separator, index);
+          const isOpen = openState[separatorId] ?? false;
+          const disableInitialAnimation =
+            initialOpenSnapshot[separatorId] ?? false;
+
+          const childContent = renderItems(entry.items);
+
+          return (
+            <SidebarSeparator
+              key={separatorId}
+              item={entry.separator}
+              itemId={separatorId}
+              isOpen={isOpen}
+              onToggle={toggle}
+              disableInitialAnimation={disableInitialAnimation}
+            >
+              {childContent}
+            </SidebarSeparator>
+          );
+        }
+
+        const item = entry.item;
+        const itemId =
+          item.$id ?? `${item.type}-${index}-${String(item.name ?? "item")}`;
+        const isOpen = openState[itemId] ?? false;
+
         return (
-          <SidebarItem key={item.$id} item={item}>
+          <SidebarItem
+            key={itemId}
+            item={item}
+            itemId={itemId}
+            isOpen={isOpen}
+            onToggle={toggle}
+          >
             {item.type === "folder" ? renderItems(item.children) : null}
           </SidebarItem>
         );
       });
     }
 
     return renderItems(root.children);
-  }, [root]);
+  }, [openState, root, toggle, initialOpenSnapshot]);
   return (
     <aside
       className={cn(
@@ -72,9 +146,15 @@ const linkVariants = cva(
 function SidebarItem({
   item,
   children,
+  itemId,
+  isOpen,
+  onToggle,
 }: {
   item: PageTree.Node;
   children: ReactNode;
+  itemId: string;
+  isOpen?: boolean;
+  onToggle?: (id: string) => void;
 }) {
   const pathname = usePathname();
 
@@ -86,40 +166,129 @@ function SidebarItem({
           active: pathname === item.url,
         })}
       >
-        {item.icon}
         {item.name}
       </Link>
     );
   }
 
   if (item.type === "separator") {
-    return (
-      <p className="text-brand-white mt-6 mb-1 first:mt-0 text-sm font-medium">
-        {item.icon}
-        {item.name}
-      </p>
-    );
+    return null;
   }
 
   return (
     <div>
-      {item.index ? (
-        <Link
-          className={linkVariants({
-            active: pathname === item.index.url,
-          })}
-          href={item.index.url}
+      <div className="flex items-center gap-2">
+        <button
+          type="button"
+          aria-label={isOpen ? "Collapse section" : "Expand section"}
+          aria-expanded={isOpen}
+          onClick={() => onToggle?.(itemId)}
+          className="rounded px-1 text-xs text-brand-neutral-100 hover:text-brand-white"
         >
-          {item.index.icon}
-          {item.index.name}
-        </Link>
-      ) : (
-        <p className={cn(linkVariants(), "text-start")}>
-          {item.icon}
-          {item.name}
-        </p>
+          <Icons.arrowDown
+            className={cn(
+              "size-4 transition-transform duration-200 ease-in-out group-hover:rotate-180",
+              isOpen ? "rotate-0" : "-rotate-90"
+            )}
+          />
+        </button>
+        {item.index ? (
+          <Link
+            className={linkVariants({
+              active: pathname === item.index.url,
+            })}
+            href={item.index.url}
+          >
+            {item.index.icon}
+            {item.index.name}
+          </Link>
+        ) : (
+          <p className={cn(linkVariants(), "text-start")}>
+            {item.icon}
+            {item.name}
+          </p>
+        )}
+      </div>
+      {isOpen ? (
+        <div className="pl-4 border-l flex flex-col">{children}</div>
+      ) : null}
+    </div>
+  );
+}
+
+function SidebarSeparator({
+  item,
+  children,
+  itemId,
+  isOpen,
+  onToggle,
+  disableInitialAnimation,
+}: {
+  item: Extract<PageTree.Node, { type: "separator" }>;
+  children: ReactNode;
+  itemId: string;
+  isOpen?: boolean;
+  onToggle?: (id: string) => void;
+  disableInitialAnimation?: boolean;
+}) {
+  return (
+    <div className="mt-4 first:mt-0">
+      <button
+        type="button"
+        aria-label={isOpen ? "Collapse section" : "Expand section"}
+        aria-expanded={isOpen}
+        onClick={() => onToggle?.(itemId)}
+        className="group flex w-full items-center gap-2 text-start text-sm font-medium text-brand-white cursor-pointer"
+      >
+        <span className="rounded text-xs text-brand-neutral-100 transition-colors duration-200 group-hover:text-brand-white">
+          <Icons.arrowDown
+            className={cn(
+              "size-4 transition-transform duration-200 ease-in-out",
+              isOpen ? "rotate-0" : "-rotate-90"
+            )}
+          />
+        </span>
+        <span className="mt-[2px]">{item.name}</span>
+      </button>
+      <AnimatedGroup
+        isOpen={isOpen}
+        disableInitialAnimation={disableInitialAnimation}
+      >
+        <div className="mt-1 pl-8 flex flex-col gap-1">{children}</div>
+      </AnimatedGroup>
+    </div>
+  );
+}
+
+function AnimatedGroup({
+  isOpen,
+  children,
+  disableInitialAnimation,
+}: {
+  isOpen?: boolean;
+  children: ReactNode;
+  disableInitialAnimation?: boolean;
+}) {
+  const [initialized, setInitialized] = useState(!disableInitialAnimation);
+
+  useEffect(() => {
+    if (!initialized) {
+      setInitialized(true);
+    }
+  }, [initialized]);
+
+  return (
+    <div
+      aria-hidden={!isOpen}
+      className={cn(
+        "grid transition-[grid-template-rows,opacity] duration-200 ease-in-out",
+        disableInitialAnimation && !initialized && isOpen
+          ? "transition-none"
+          : null,
+        isOpen ? "opacity-100 grid-rows-[1fr]" : "opacity-0 grid-rows-[0fr]"
       )}
-      <div className="pl-4 border-l flex flex-col">{children}</div>
+    >
+      <div className="overflow-hidden">{children}</div>
     </div>
   );
 }

apps/website/components/layout/navigation-link.tsx

@@ -1,6 +1,5 @@
 import Link from "next/link";
 import { cn } from "@/lib/cn";
-import { Icons } from "../icons";
 import type * as PageTree from "fumadocs-core/page-tree";
 
 export function NavigationLink({
@@ -22,9 +21,7 @@ export function NavigationLink({
       )}
     >
       <span className="text-sm text-brand-neutral-100 flex items-center gap-2">
-        {isPrevious && <Icons.arrowDown className="size-3 rotate-90" />}
         {label}
-        {!isPrevious && <Icons.arrowDown className="size-3 rotate-270" />}
       </span>
       <span className="text-brand-white font-medium group-hover:text-fd-primary transition-colors">
         {item.name}

apps/website/content/blog/react-client-components.mdx

@@ -0,0 +1,60 @@
+---
+title: "When tools need UIs"
+description: "Our philosophy on bringing UI components to MCP tools."
+summary: "Our philosophy on bringing UI components to MCP tools."
+category: "engineering"
+date: "2026-01-06"
+order: 2
+previewImage: "/blog/react-client-components.png"
+authors:
+  - fveiras_
+---
+
+In recent years, modern frameworks have brought backend and frontend together. The client and server environments have different capabilities,
+but the developer experience feels monolithic.
+
+xmcp started on the server side: that's where MCP began. But things are evolving fast. Our mission is to lower the barrier to entry for developers to build and ship MCP servers without thinking about all the complexity and friction that comes with it.
+
+With the latest [MCP apps](https://modelcontextprotocol.github.io/ext-apps/api/) proposal, we're getting closer to a more unified experience for developers: a standard inspired by [MCP-UI](https://mcpui.dev/) and [OpenAI's Apps SDK](https://developers.openai.com/apps-sdk/) to allow MCP Servers to display interactive UI elements in conversational MCP clients and chatbots.
+
+You shouldn't need to think about complex config or set up. Instead, you can use [template literals](/docs/core-concepts/tools#2-template-literal-handlers) or [React Client Components](/docs/core-concepts/tools#3-react-component-handlers) directly, and it just works.
+
+## Always bet on React
+
+It's the most popular JavaScript UI framework out there, massive community, extensive ecosystem,
+and widespread adoption by major companies. When you already know React, you shouldn't have to learn something new just to return UI from your tools.
+
+We aimed to make it as easy as possible to return React Client components. You only need to convert your handlers from `.ts` to `.tsx`.
+We prioritize speed and keeping the framework lightweight, so for this reason React is an optional peer dependency. You only install it if you need it.
+
+![File Extension Diagram - converting .ts to .tsx](https://j2fbnka41vq9pfap.public.blob.vercel-storage.com/images/diagram-1-169%20%281%29.svg)
+
+## Simplicity over complexity
+
+For client-side components, React is all you need to get up and running quickly and efficiently.
+
+For cases where you need to manage complex interactions between client and server components, like hydration or caching, you can use a framework
+like Next.js with our [adapter](/docs/adapters/nextjs) that would also allow you to convert Next.js application into compatible MCP apps.
+
+<Callout variant="info">
+  Check out our [ChatGPT App with Next.js](/blog/doom-with-xmcp) that runs DOOM
+  for an example of how to use Next.js with xmcp.
+</Callout>
+
+## Styling that just works
+
+Under the hood, xmcp compiles using [rspack](https://rspack.rs/), a fast Rust-based web bundler.
+When the framework detects JSX, it bundles CSS alongside your JavaScript into the dist directory.
+Tailwind, CSS Modules, and standard CSS imports work out of the box.
+
+![Styling Diagram - CSS, CSS Modules, and Tailwind](https://j2fbnka41vq9pfap.public.blob.vercel-storage.com/images/diagram-2-169.svg)
+
+If you want to learn more, you can find additional details and how to get started [here](/docs/core-concepts/css).
+
+## Looking forward
+
+The protocol and ext-apps specification will continue evolving, and sometimes this natural progression brings additional complexity.
+Our commitment is to reduce that complexity as much as we can, by actively contributing to the protocol development, carefully following all the latest updates,
+and ensuring our framework abstracts away unnecessary complications while maintaining full compatibility with the standard.
+
+If you're building your MCP server using our [Next.js adapter](/docs/adapters/nextjs) or [React Client Components](/docs/core-concepts/tools#3-react-component-handlers), we'd love to hear about your experience. Join us on [Discord](https://discord.gg/d9a7JBBxV9).