[docs][ui][fixes] - Fixes welcome/guides tabs, better components

docs/content/docs/(guides)/meta.json

@@ -44,6 +44,7 @@
     "others/self-host",
     "others/supabase",
     "others/convex",
+    "others/mcp-setup",
     "sdk",
     "components"
   ]

docs/content/docs/(guides)/others/mcp-setup.mdx

@@ -0,0 +1,240 @@
+---
+title: MCP Setup
+---
+
+<div className="flex items-center justify-center gap-8 mb-8">
+  <StackAuthIcon size={128} />
+  <div className="text-3xl font-light text-fd-muted-foreground">+</div>
+  <img src="/imgs/mcp.svg" alt="MCP" width="128" height="128" className="flex-shrink-0 dark:invert" />
+</div>
+
+Set up Stack Auth's Model Context Protocol (MCP) server to get intelligent code assistance in your development environment.
+
+<Tabs defaultValue="cursor">
+  <TabsList>
+    <TabsTrigger value="cursor">Cursor</TabsTrigger>
+    <TabsTrigger value="vscode">VS Code</TabsTrigger>
+    <TabsTrigger value="claudecode">Claude Code</TabsTrigger>
+    <TabsTrigger value="claudedesktop">Claude Desktop</TabsTrigger>
+    <TabsTrigger value="windsurf">Windsurf</TabsTrigger>
+    <TabsTrigger value="chatgpt">ChatGPT</TabsTrigger>
+    <TabsTrigger value="gemini">Gemini CLI</TabsTrigger>
+  </TabsList>
+
+  <TabsContent value="cursor">
+  Configure Stack Auth MCP in Cursor IDE for enhanced code assistance.
+
+  <Button href="cursor://anysphere.cursor-deeplink/mcp/install?name=stack-auth&config=eyJ1cmwiOiJodHRwczovL21jcC5zdGFjay1hdXRoLmNvbS8ifQ==" icon={<img src="/imgs/cursor.svg" alt="Cursor" width="14" height="14" className="w-full h-full object-contain" />}>Add to Cursor</Button>
+
+  **Manual Installation**
+
+  Add the following to your `mcp.json` file:
+
+  ```json title="mcp.json"
+      {
+        "mcpServers": {
+          "stack-auth": {
+            "url": "https://mcp.stack-auth.com/"
+          }
+        }
+      }
+    ```
+  </TabsContent>
+
+  <TabsContent value="vscode">
+    Configure Stack Auth MCP in VSCode IDE for enhanced code assistance.
+
+    <Button href="https://insiders.vscode.dev/redirect?url=vscode:mcp/install?%7B%22type%22%3A%22http%22%2C%22name%22%3A%22stack-auth%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.stack-auth.com%2F%22%7D" icon={<img src="/imgs/vscode.svg" alt="VSCode" width="14" height="14" className="w-full h-full object-contain" />}>Add to VS Code</Button>
+
+    **Manual Installation**
+
+    Open a terminal and run the following command:
+
+    ```sh title="Terminal"
+      code --add-mcp '{"type":"http","name":"stack-auth","url":"https://mcp.stack-auth.com/"}'
+      ```
+
+    Then, from inside VS Code, open the .vscode/mcp.json file and click "Start server".
+
+  </TabsContent>
+
+  <TabsContent value="claudecode">
+    Open a terminal and run the following command:
+
+    ```sh title="Terminal"
+      claude mcp add --transport http stack-auth https://mcp.stack-auth.com/
+      ```
+
+    From within Claude Code, you can use the /mcp command to get more information about the server.
+  </TabsContent>
+
+  <TabsContent value="claudedesktop">
+    Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector.
+
+    Enter the name as stack-auth and the remote MCP server URL as https://mcp.stack-auth.com/.
+  </TabsContent>
+
+  <TabsContent value="windsurf">
+  Copy the following JSON to your Windsurf MCP config file:
+
+  ```json title="mcp.json"
+      {
+        "mcpServers": {
+          "stack-auth": {
+            "serverUrl": "https://mcp.stack-auth.com/"
+          }
+        }
+      }
+    ```
+  </TabsContent>
+
+  <TabsContent value="chatgpt">
+   <Info>
+    In Team, Enterprise, and Edu workspaces, only workspace owners and admins have permission to set this.
+   </Info>
+    Navigate to **Settings > Connectors**
+    Add a custom connector with the server URL: `https://mcp.stack-auth.com`
+
+    After this, it should be visible in Composer > Deep research Tool.
+
+    <Info>
+    Connectors can only be used with **Deep Research**
+    </Info>
+  </TabsContent>
+
+  <TabsContent value="gemini">
+  Add the following JSON to your Gemini CLI configuration file (~/.gemini/settings.json):
+
+  ```json title="settings.json"
+      {
+        "mcpServers": {
+          "stack-auth": {
+           "httpUrl": "https://mcp.stack-auth.com/",
+           "headers": {
+            "Accept": "application/json, text/event-stream"
+           }
+          }
+        }
+      }
+    ```
+  </TabsContent>
+
+</Tabs>
+
+
+## Markdown Instructions
+
+If you want to include instructions for all clients in your project's README.md file, feel free to copy the following markdown:
+
+<pre className="bg-fd-muted/30 p-4 rounded-lg overflow-x-auto"><code className="text-sm">{`<details name="mcp-install-instructions">
+<summary>Cursor</summary>
+
+#### Installation Link
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=stack-auth&config=eyJ1cmwiOiJodHRwczovL21jcC5zdGFjay1hdXRoLmNvbS8ifQ==)
+
+#### Manual Installation
+Add the following to your \`mcp.json\` file:
+
+\`\`\`json
+{
+  "mcpServers": {
+    "stack-auth": {
+      "url": "https://mcp.stack-auth.com/"
+    }
+  }
+}
+\`\`\`
+</details>
+
+<details name="mcp-install-instructions">
+<summary>VSCode</summary>
+
+#### Installation Link
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visual-studio-code&logoColor=white)](https://insiders.vscode.dev/redirect?url=vscode:mcp/install?%7B%22type%22%3A%22http%22%2C%22name%22%3A%22stack-auth%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.stack-auth.com%2F%22%7D)
+
+#### Manual Installation
+Open a terminal and run the following command:
+
+\`\`\`
+code --add-mcp '{"type":"http","name":"stack-auth","url":"https://mcp.stack-auth.com/"}'
+\`\`\`
+
+Then, from inside VS Code, open the .vscode/mcp.json file and click "Start server".
+</details>
+
+<details name="mcp-install-instructions">
+<summary>Claude Code</summary>
+
+Open a terminal and run the following command:
+\`\`\`
+claude mcp add --transport http stack-auth https://mcp.stack-auth.com/
+\`\`\`
+From within Claude Code, you can use the \`/mcp\` command to get more information about the server.
+</details>
+
+<details name="mcp-install-instructions">
+<summary>Claude Desktop</summary>
+
+Open Claude Desktop and navigate to Settings > Connectors > Add Custom Connector.
+
+Enter the name as \`stack-auth\` and the remote MCP server URL as \`https://mcp.stack-auth.com/\`.
+</details>
+
+<details name="mcp-install-instructions">
+<summary>Windsurf</summary>
+
+Copy the following JSON to your Windsurf MCP config file:
+\`\`\`json
+{
+  "mcpServers": {
+    "stack-auth": {
+      "serverUrl": "https://mcp.stack-auth.com/"
+    }
+  }
+}
+\`\`\`
+</details>
+
+<details name="mcp-install-instructions">
+<summary>ChatGPT</summary>
+
+*Note: In Team, Enterprise, and Edu workspaces, only workspace owners and admins have permission*
+
+- Navigate to **Settings > Connectors**
+- Add a custom connector with the server URL: \`https://mcp.stack-auth.com/\`
+- It should then be visible in the Composer > Deep research tool
+- You may need to add the server as a source
+
+*Connectors can only be used with **Deep Research***
+</details>
+
+<details name="mcp-install-instructions">
+<summary>Gemini CLI</summary>
+
+Add the following JSON to your Gemini CLI configuration file (\`~/.gemini/settings.json\`):
+\`\`\`json
+{
+  "mcpServers": {
+    "stack-auth": {
+      "httpUrl": "https://mcp.stack-auth.com/",
+      "headers": {
+        "Accept": "application/json, text/event-stream"
+      }
+    }
+  }
+}
+\`\`\`
+</details>
+
+by [![Hypr MCP](https://hyprmcp.com/hyprmcp_20px.svg)](https://hyprmcp.com/)`}</code></pre>
+
+
+## Features
+
+The Stack Auth MCP server provides:
+
+- **Authentication Flow Assistance**: Get help implementing sign-in, sign-up, and user management
+- **API Documentation**: Access Stack Auth API documentation and examples
+- **Code Generation**: Generate boilerplate code for common authentication patterns
+- **Best Practices**: Receive guidance on security best practices and implementation patterns
+

docs/content/docs/(guides)/overview.mdx

@@ -6,40 +6,44 @@ Welcome to Stack Auth, the developer-friendly open-source authentication platfor
 
 You can get started in five minutes with our [setup guide](./getting-started/setup), or jump straight into the documentation.
 
-<CardGroup>
-  <Card 
+<QuickLinks>
+  <QuickLink 
     title="Setup & Installation"
     icon="fa-regular fa-play" 
     href="./getting-started/setup"
+    gradient={0}
   >
     Get started with Stack in 5 minutes
-  </Card>
+  </QuickLink>
   {/* IF_PLATFORM: react-like */}
-  <Card 
+  <QuickLink 
     title="Components"
     icon="fa-solid fa-puzzle"
     href="./components"
+    gradient={1}
   >
     Use our pre-built React components, or create your own
-  </Card>
+  </QuickLink>
   {/* END_PLATFORM */}
   {/* IF_PLATFORM: js-like */}
-  <Card 
+  <QuickLink 
     title="SDK Reference"
     icon="fa-regular fa-file-lines" 
     href="./sdk"
+    gradient={1}
   >
     Learn how to use Stack Auth's SDK
-  </Card>
+  </QuickLink>
   {/* END_PLATFORM */}
-  <Card 
+  <QuickLink 
     title="REST API Reference"
     icon="fa-solid fa-code" 
     href="/api/overview"
+    gradient={3}
   >
     Explore Stack's REST APIs
-  </Card>
-</CardGroup>
+  </QuickLink>
+</QuickLinks>
 
 ## Apps
 

docs/src/components/layouts/docs.tsx

@@ -139,7 +139,7 @@ function DocsSidebarLink({
   return (
     <Link
       href={href}
-      className={`flex items-center gap-2 px-2 py-1.5 rounded-md text-xs transition-colors ${
+      className={`flex items-center gap-2 px-2 py-1.5 rounded-lg text-xs transition-colors ${
         isActive
           ? 'bg-fd-primary/10 text-fd-primary font-medium'
           : 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50'
@@ -228,7 +228,7 @@ function ClickableCollapsibleSection({
       <div className="group">
         <Link
           href={href}
-          className={`flex items-center justify-between w-full px-2 py-1.5 rounded-md text-xs transition-colors ${
+          className={`flex items-center justify-between w-full px-2 py-1.5 rounded-lg text-xs transition-colors ${
             isActive
               ? 'bg-fd-primary/10 text-fd-primary font-medium'
               : 'text-fd-muted-foreground hover:text-fd-foreground hover:bg-fd-muted/50'
@@ -320,9 +320,34 @@ function renderSidebarContent(tree: PageTree.Root, pathname: string) {
     return null;
   }
 
+  const overviewItem = tree.children.find(
+    (item) =>
+      item.type === 'page' &&
+      (item.url.endsWith('/overview') || item.name === 'Overview')
+  );
+  const faqItem = tree.children.find(
+    (item) =>
+      item.type === 'page' &&
+      (item.url.endsWith('/faq') || item.name === 'FAQ')
+  );
+
+  const specialItems = [overviewItem, faqItem].filter(
+    (item): item is PageTree.Node => !!item
+  );
+  const otherItems = tree.children.filter(
+    (item) => !specialItems.includes(item)
+  );
+
   return (
     <>
-      {tree.children.map((item, index) => (
+      {specialItems.length > 0 && (
+        <div className="mb-4 rounded-xl border border-fd-border/80 bg-fd-muted/10 p-1">
+          {specialItems.map((item, index) => (
+            <PageTreeItem key={item.type === 'page' ? item.url : index} item={item} />
+          ))}
+        </div>
+      )}
+      {otherItems.map((item, index) => (
         <PageTreeItem key={item.type === 'page' ? item.url : index} item={item} />
       ))}
     </>

docs/src/components/layouts/shared-header.tsx

@@ -50,7 +50,7 @@ export function isInApiSection(pathname: string): boolean {
  */
 function isNavLinkActive(pathname: string, navLink: NavLink): boolean {
   // More specific matches first
-  if (navLink.label === 'Welcome' && pathname === '/docs/overview') {
+  if (navLink.label === 'Welcome' && (pathname === '/docs/overview' || pathname === '/docs/faq')) {
     return true;
   }
   if (navLink.label === 'SDK' && isInSdkSection(pathname)) {
@@ -63,7 +63,7 @@ function isNavLinkActive(pathname: string, navLink: NavLink): boolean {
     return true;
   }
   if (navLink.label === 'Guides' && pathname.startsWith('/docs') &&
-      !isInComponentsSection(pathname) && !isInSdkSection(pathname) && pathname !== '/docs/overview') {
+      !isInComponentsSection(pathname) && !isInSdkSection(pathname) && pathname !== '/docs/overview' && pathname !== '/docs/faq') {
     return true;
   }
   return false;

docs/src/components/mdx/app-card.tsx

@@ -109,10 +109,12 @@ export function AppGrid({ appIds, className }: {
   className?: string,
 }) {
   return (
-    <div className={cn("flex gap-1 lg:gap-8 flex-wrap", className)}>
-      {appIds.map(appId => (
-        <AppCard key={appId} appId={appId} />
-      ))}
+    <div className="max-w-3xl mx-auto">
+      <div className={cn("flex gap-1 lg:gap-8 flex-wrap justify-center", className)}>
+        {appIds.map(appId => (
+          <AppCard key={appId} appId={appId} />
+        ))}
+      </div>
     </div>
   );
 }