zudoku 0.72.0 → 0.73.1

package/dist/cli/cli.js

@@ -3276,7 +3276,10 @@ var init_ZudokuConfig = __esm({
       keywords: z7.array(z7.string()),
       authors: z7.array(z7.string()),
       creator: z7.string(),
-      publisher: z7.string()
+      publisher: z7.string(),
+      robots: z7.string().describe(
+        'Sets the contents of the `meta[name="robots"]` tag. For example: `noindex, nofollow`.'
+      )
     }).partial();
     FontConfigSchema = z7.union([
       z7.enum(GOOGLE_FONTS),
@@ -3810,7 +3813,7 @@ import {
 // package.json
 var package_default = {
   name: "zudoku",
-  version: "0.71.10",
+  version: "0.73.0",
   type: "module",
   sideEffects: [
     "**/*.css",

package/dist/declarations/config/validators/ZudokuConfig.d.ts

@@ -6652,6 +6652,7 @@ export declare const ZudokuConfig: z.ZodObject<{
         authors: z.ZodOptional<z.ZodArray<z.ZodString>>;
         creator: z.ZodOptional<z.ZodString>;
         publisher: z.ZodOptional<z.ZodString>;
+        robots: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     authentication: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"clerk">;

package/dist/declarations/lib/core/ZudokuContext.d.ts

@@ -45,6 +45,7 @@ type Metadata = Partial<{
     authors: string[];
     creator: string;
     publisher: string;
+    robots: string;
 }>;
 type Site = Partial<{
     dir?: "ltr" | "rtl";

package/dist/declarations/lib/plugins/openapi/MCPEndpoint.d.ts

@@ -1,5 +1,6 @@
-export declare const MCPEndpoint: ({ serverUrl, summary, data, }: {
+export declare const MCPEndpoint: ({ serverUrl, operationPath, summary, data, }: {
     serverUrl?: string;
+    operationPath?: string;
     data?: boolean | Record<string, unknown>;
     summary?: string;
 }) => import("react/jsx-runtime").JSX.Element;

package/dist/flat-config.d.ts

@@ -236,6 +236,10 @@ export interface FlatZudokuConfig {
     authors?: string[]
     creator?: string
     publisher?: string
+    /**
+     * Sets the contents of the `meta[name="robots"]` tag. For example: `noindex, nofollow`.
+     */
+    robots?: string
   }
   authentication?: ({
     type: "clerk"

package/docs/configuration/navigation.mdx

@@ -11,7 +11,8 @@ import { Book, Code, FileText } from "zudoku/icons";
 
 Zudoku uses a single `navigation` array to control both the top navigation tabs and the sidebar.
 Items at the root of this array appear as tabs, and nested items build the sidebar tree. Navigation
-entries can be links, document references, categories or custom pages.
+entries can be links, document references, categories, custom pages, separators, sections, or
+filters.
 
 ## Basic configuration
 
@@ -45,7 +46,6 @@ one of several types. At the simplest level you may only have links and categori
       "to": "/api",
       "label": "API Reference",
       "icon": "code",
-      "description": "Complete API documentation",
       "badge": {
         "label": "v2.0",
         "color": "blue"
@@ -58,13 +58,18 @@ one of several types. At the simplest level you may only have links and categori
 
 ## Navigation Items
 
-Navigation items can be of these types: `category`, `doc`, `link`, or `custom-page`.
+Navigation items can be of these types: `category`, `doc`, `link`, `custom-page`, `separator`,
+`section`, or `filter`.
 
 - `link`: A direct link to a page or external URL.
 - `category`: A group of links that can be expanded or collapsed.
-- `doc`: A reference to a document by it's file path: `file`.
-- `custom-pages`: A custom page that is made of a React component, see
+- `doc`: A reference to a document by its file path: `file`.
+- `custom-page`: A custom page that is made of a React component, see
   [Custom Pages](../guides/custom-pages.md)
+- `separator`: A horizontal line to visually divide sidebar items.
+- `section`: A non-interactive heading label to group sidebar items.
+- `filter`: An inline search input that filters navigation items. Multiple filter inputs share the
+  same search query.
 
 ### `type: link`
 
@@ -87,10 +92,10 @@ type NavigationLink = {
   to: string;
   label: string;
   icon?: string; // Lucide icon name
-  description?: string;
   badge?: {
     label: string;
     color: "green" | "blue" | "yellow" | "red" | "purple" | "indigo" | "gray" | "outline";
+    invert?: boolean;
   };
   display?:
     | "auth"
@@ -106,7 +111,8 @@ type NavigationLink = {
 ### `type: category`
 
 The `category` type groups related items under a collapsible section. The `label` is the displayed
-text, and the `items` array contains `id`s of documents, links, or other categories.
+text, and the `items` array can contain any navigation item type (documents, links, categories,
+custom pages, separators, sections, and filters).
 
 ```json
 {
@@ -131,11 +137,11 @@ text, and the `items` array contains `id`s of documents, links, or other categor
 type NavigationCategory = {
   type: "category";
   icon?: string; // Lucide icon name
-  items: Array<NavigationDoc | NavigationLink | NavigationCategory | NavigationCustomPage>;
+  items: Array<NavigationItem>; // any navigation item type, including string shorthands for docs
   label: string;
   collapsible?: boolean;
   collapsed?: boolean;
-  link?: string | { type: "doc"; file: string; label?: string };
+  link?: string | { type: "doc"; file: string; label?: string; path?: string };
   display?:
     | "auth"
     | "anon"
@@ -147,6 +153,50 @@ type NavigationCategory = {
 
 </details>
 
+#### Category links
+
+A category can have a `link` property that makes the category label itself clickable, navigating to
+a document. This is useful when you want a category that acts as both a group and a landing page.
+
+The `link` can be a simple string pointing to a file path, or an object for more control:
+
+```tsx title="String shorthand"
+{
+  type: "category",
+  label: "Configuration",
+  link: "docs/configuration/overview",
+  items: [
+    "docs/configuration/navigation",
+    "docs/configuration/site",
+  ],
+}
+```
+
+```tsx title="Object form with custom path"
+{
+  type: "category",
+  label: "Documentation",
+  link: {
+    type: "doc",
+    file: "home.md",
+    path: "/",
+  },
+  items: [
+    "guides/getting-started",
+    "guides/advanced",
+  ],
+}
+```
+
+The object form supports these properties:
+
+| Property | Type     | Description                                              |
+| -------- | -------- | -------------------------------------------------------- |
+| `type`   | `"doc"`  | Must be `"doc"`                                          |
+| `file`   | `string` | Path to the markdown file                                |
+| `label`  | `string` | Override the label (defaults to the document title)      |
+| `path`   | `string` | Custom URL path (overrides the default file-based route) |
+
 ### `type: doc`
 
 Doc is used to reference markdown files. The `label` is the text that will be displayed, and the
@@ -173,6 +223,7 @@ type NavigationDoc = {
   badge?: {
     label: string;
     color: "green" | "blue" | "yellow" | "red" | "purple" | "indigo" | "gray" | "outline";
+    invert?: boolean;
   };
   display?:
     | "auth"
@@ -223,6 +274,37 @@ Learn more in the [Markdown documentation](/docs/markdown/overview)
 The `path` property allows you to customize the URL path for a document. By default, Zudoku uses the
 file path to generate the URL, but you can override this behavior by specifying a custom path.
 
+```tsx title="Serving a doc at the root URL"
+{
+  type: "doc",
+  file: "home.md",
+  path: "/",
+  label: "Home",
+}
+```
+
+```tsx title="Custom slug"
+{
+  type: "doc",
+  file: "guides/getting-started.md",
+  path: "/start-here",
+  label: "Start Here",
+}
+```
+
+When a file has a custom path, it will only be accessible at that custom path, not at its original
+file-based path. See [Documentation - Custom Paths](/docs/configuration/docs#custom-paths) for more
+details.
+
+:::note
+
+Avoid naming files `index.md` or `index.mdx` and relying on their default path. Some hosting
+providers (e.g. Vercel) automatically strip `/index` from URLs with a redirect, which can cause
+routing issues. Instead, give files descriptive names and use the `path` property to serve them at
+the desired URL.
+
+:::
+
 ### `type: custom-page`
 
 Custom pages allow you to create standalone pages that are not tied to a Markdown document. This is
@@ -247,6 +329,7 @@ type NavigationCustomPage = {
   label?: string;
   element: any;
   icon?: string; // Lucide icon name
+  layout?: "default" | "none";
   badge?: {
     label: string;
     color: "green" | "blue" | "yellow" | "red" | "purple" | "indigo" | "gray" | "outline";
@@ -263,6 +346,120 @@ type NavigationCustomPage = {
 
 </details>
 
+Set `layout: "none"` to render the page without the default Zudoku layout (header, sidebar, footer).
+This is useful for fully custom landing pages.
+
+### `type: separator`
+
+A visual divider line in the sidebar. Use separators to create visual breaks between groups of
+items.
+
+```tsx
+{
+  type: "category",
+  label: "Documentation",
+  items: [
+    "guides/getting-started",
+    "guides/installation",
+    { type: "separator" },
+    "guides/advanced",
+    "guides/troubleshooting",
+  ],
+}
+```
+
+<details>
+<summary>**TypeScript type declaration**</summary>
+
+```ts
+type NavigationSeparator = {
+  type: "separator";
+  display?:
+    | "auth"
+    | "anon"
+    | "always"
+    | "hide"
+    | ((params: { context: ZudokuContext; auth: UseAuthReturn }) => boolean);
+};
+```
+
+</details>
+
+### `type: section`
+
+A non-interactive heading label in the sidebar. Sections are rendered as small uppercase text and
+are useful for labeling groups of items without adding a collapsible wrapper.
+
+```tsx
+{
+  type: "category",
+  label: "Documentation",
+  items: [
+    { type: "section", label: "Getting Started" },
+    "guides/quickstart",
+    "guides/installation",
+    { type: "section", label: "Advanced" },
+    "guides/plugins",
+    "guides/deployment",
+  ],
+}
+```
+
+<details>
+<summary>**TypeScript type declaration**</summary>
+
+```ts
+type NavigationSection = {
+  type: "section";
+  label: string;
+  display?:
+    | "auth"
+    | "anon"
+    | "always"
+    | "hide"
+    | ((params: { context: ZudokuContext; auth: UseAuthReturn }) => boolean);
+};
+```
+
+</details>
+
+### `type: filter`
+
+An inline search input that updates the shared navigation filter. When the user types, the query is
+applied across the sidebar so that only matching items remain visible.
+
+```tsx
+{
+  type: "category",
+  label: "Documentation",
+  items: [
+    { type: "filter", placeholder: "Filter documentation" },
+    "guides/getting-started",
+    "guides/installation",
+    "guides/authentication",
+    "guides/deployment",
+  ],
+}
+```
+
+<details>
+<summary>**TypeScript type declaration**</summary>
+
+```ts
+type NavigationFilter = {
+  type: "filter";
+  placeholder?: string;
+  display?:
+    | "auth"
+    | "anon"
+    | "always"
+    | "hide"
+    | ((params: { context: ZudokuContext; auth: UseAuthReturn }) => boolean);
+};
+```
+
+</details>
+
 ## Display Control
 
 All navigation items support a `display` property that controls when the item should be visible:
@@ -363,6 +560,94 @@ sidebar_label: Short Title
 In this example, the document's title remains "My Long Title," but the sidebar displays "Short
 Title."
 
+For the complete list of supported frontmatter properties, see
+[Frontmatter](/docs/markdown/frontmatter).
+
+## Common Patterns
+
+### Serving a document at the root URL
+
+To make a markdown document accessible at `/`, use the `path` property to override the default
+file-based route:
+
+```tsx title="Standalone root doc"
+navigation: [
+  {
+    type: "doc",
+    file: "home.md",
+    path: "/",
+    label: "Home",
+  },
+],
+```
+
+```tsx title="Category with root landing page"
+navigation: [
+  {
+    type: "category",
+    label: "Documentation",
+    link: {
+      type: "doc",
+      file: "home.md",
+      path: "/",
+    },
+    items: [
+      "guides/getting-started",
+      "guides/installation",
+    ],
+  },
+],
+```
+
+### Landing page with hidden tab
+
+Use a `custom-page` with `display: "hide"` and `layout: "none"` to create a full-page landing
+experience that doesn't appear in the navigation tabs:
+
+```tsx
+navigation: [
+  {
+    type: "custom-page",
+    path: "/",
+    display: "hide",
+    layout: "none",
+    element: <LandingPage />,
+  },
+  {
+    type: "category",
+    label: "Documentation",
+    items: ["docs/quickstart", "docs/installation"],
+  },
+],
+```
+
+### Organized sidebar with sections and separators
+
+Combine `section`, `separator`, and `filter` items to create a well-structured sidebar:
+
+```tsx
+navigation: [
+  {
+    type: "category",
+    label: "Documentation",
+    items: [
+      { type: "filter", placeholder: "Filter documentation" },
+      { type: "section", label: "Getting Started" },
+      "guides/quickstart",
+      "guides/installation",
+      { type: "separator" },
+      { type: "section", label: "Advanced" },
+      {
+        type: "category",
+        label: "Plugins",
+        icon: "blocks",
+        items: ["plugins/overview", "plugins/custom"],
+      },
+    ],
+  },
+],
+```
+
 ## Navigation Rules
 
 Plugins generate sidebar navigation automatically (e.g. from OpenAPI tags). Navigation rules let you

package/docs/guides/mcp-servers.md

@@ -0,0 +1,189 @@
+---
+title: Documenting MCP Servers
+sidebar_icon: bot
+zuplo: false
+---
+
+Zudoku can render a dedicated [MCP](https://modelcontextprotocol.io/) endpoint UI for any OpenAPI
+operation that has the `x-mcp-server` extension. When detected, the operation page replaces the
+standard request/response view with an MCP card showing the endpoint URL, a copy button, and tabbed
+installation instructions for Claude, ChatGPT, Cursor, VS Code, and a generic config.
+
+## Adding the extension
+
+Add the `x-mcp-server` extension to an operation in your OpenAPI spec. While MCP servers typically
+use `POST`, the extension works on any HTTP method:
+
+```json title="openapi.json (paths section)"
+{
+  "paths": {
+    "/mcp": {
+      "post": {
+        "summary": "My MCP Server",
+        "description": "MCP endpoint for querying documentation.",
+        "operationId": "mcpEndpoint",
+        "x-mcp-server": {
+          "name": "my-mcp-server",
+          "version": "1.0.0",
+          "tools": [
+            {
+              "name": "search_docs",
+              "description": "Search the documentation"
+            },
+            {
+              "name": "get_page",
+              "description": "Retrieve a specific documentation page"
+            }
+          ]
+        },
+        "responses": {
+          "200": {
+            "description": "MCP response"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+The UI will display beneath the operation heading, showing the full MCP URL derived from the server
+URL and the operation path.
+
+You can also use the shorthand `"x-mcp-server": true` to enable the MCP UI without specifying any
+metadata. In this case, the operation's `summary` is used as the server name.
+
+## Extension properties
+
+| Property  | Type     | Required | Description                                                                                                                  |
+| --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `name`    | `string` | No       | Display name used in the generated client configuration snippets. Falls back to the operation `summary`, then `"mcp-server"` |
+| `version` | `string` | No       | Version metadata (included for completeness; not currently rendered in UI)                                                   |
+| `tools`   | `array`  | No       | Tools metadata (used by Zuplo enrichment; not currently rendered in UI)                                                      |
+
+Each tool in the `tools` array has:
+
+| Property      | Type     | Required | Description                     |
+| ------------- | -------- | -------- | ------------------------------- |
+| `name`        | `string` | Yes      | Tool name                       |
+| `description` | `string` | No       | Human-readable tool description |
+
+## MCP URL resolution
+
+The displayed MCP URL is constructed from the **server URL** of the API and the **path** of the
+operation. The server URL comes from the OpenAPI `servers` array (or the operation-level `servers`
+override if present).
+
+For example, with this configuration:
+
+```json
+{
+  "servers": [{ "url": "https://api.example.com" }],
+  "paths": {
+    "/mcp/docs": {
+      "post": {
+        "x-mcp-server": { "name": "docs-mcp" },
+        "responses": { "200": { "description": "OK" } }
+      }
+    }
+  }
+}
+```
+
+The displayed MCP URL will be `https://api.example.com/mcp/docs`.
+
+## Complete example
+
+This is a minimal but complete OpenAPI spec that produces an MCP endpoint page:
+
+```json title="mcp-api.json"
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Documentation MCP Server",
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.example.com",
+      "description": "Production"
+    }
+  ],
+  "paths": {
+    "/mcp": {
+      "post": {
+        "tags": ["MCP"],
+        "summary": "Documentation MCP Server",
+        "description": "MCP endpoint powered by Inkeep for searching and querying documentation.",
+        "operationId": "mcpEndpoint",
+        "x-mcp-server": {
+          "name": "example-docs",
+          "version": "1.0.0",
+          "tools": [
+            {
+              "name": "search_docs",
+              "description": "Search the documentation"
+            }
+          ]
+        },
+        "responses": {
+          "200": {
+            "description": "MCP response"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Then reference this spec in your Zudoku config (see
+[API Reference](/docs/configuration/api-reference) for full `apis` configuration):
+
+```tsx title="zudoku.config.tsx"
+import type { ZudokuConfig } from "zudoku";
+
+const config: ZudokuConfig = {
+  apis: [
+    {
+      type: "file",
+      input: "./mcp-api.json",
+      path: "mcp",
+    },
+  ],
+  navigation: [
+    {
+      type: "link",
+      label: "MCP Server",
+      to: "/mcp",
+      icon: "bot",
+    },
+  ],
+};
+
+export default config;
+```
+
+You can see a live example of this in the
+[Cosmo Cargo demo](https://www.cosmocargo.dev/catalog/api-ai-cargo/ai-operations#universal-mcp-endpoint).
+
+## Generated UI
+
+When Zudoku detects the `x-mcp-server` extension on an operation, the page shows:
+
+- **MCP Endpoint card** with the full URL and a copy button
+- **AI Tool Configuration** tabs with setup instructions for:
+  - **Claude** — `claude_desktop_config.json` using native HTTP transport
+  - **ChatGPT** — connector setup via Settings
+  - **Cursor** — `mcp.json` configuration (global or project-level)
+  - **VS Code** — `.vscode/mcp.json` for GitHub Copilot
+  - **Generic** — standard `mcp.json` format compatible with most MCP clients
+
+The standard method badge, request body, parameters, and sidecar panels are hidden for MCP endpoints
+since they use a different interaction model.
+
+## Using with Zuplo
+
+If you are using [Zuplo](https://zuplo.com) to host your API, the `x-mcp-server` extension is
+automatically added to POST operations that use the `mcpServerHandler`. No manual schema changes are
+needed. See the [Zuplo MCP documentation](https://zuplo.com/docs/handlers/mcp-handler) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.72.0",
+  "version": "0.73.1",
   "type": "module",
   "sideEffects": [
     "**/*.css",
@@ -283,7 +283,7 @@
     "@types/unist": "3.0.3",
     "@types/yargs": "17.0.35",
     "@vitest/coverage-v8": "4.0.18",
-    "happy-dom": "20.8.3",
+    "happy-dom": "20.8.9",
     "oxc-parser": "^0.119.0",
     "react": "19.2.4",
     "react-dom": "19.2.4",

package/src/config/validators/ZudokuConfig.ts

@@ -506,6 +506,11 @@ const MetadataSchema = z
     authors: z.array(z.string()),
     creator: z.string(),
     publisher: z.string(),
+    robots: z
+      .string()
+      .describe(
+        'Sets the contents of the `meta[name="robots"]` tag. For example: `noindex, nofollow`.',
+      ),
   })
   .partial();
 

package/src/lib/components/Meta.tsx

@@ -39,6 +39,7 @@ export const Meta = ({ children }: PropsWithChildren) => {
         ))}
         {meta?.creator && <meta name="creator" content={meta.creator} />}
         {meta?.publisher && <meta name="publisher" content={meta.publisher} />}
+        {meta?.robots && <meta name="robots" content={meta.robots} />}
       </Helmet>
       {children}
     </>

package/src/lib/core/ZudokuContext.ts

@@ -65,6 +65,7 @@ type Metadata = Partial<{
   authors: string[];
   creator: string;
   publisher: string;
+  robots: string;
 }>;
 
 type Site = Partial<{

package/src/lib/plugins/openapi/MCPEndpoint.tsx

@@ -11,15 +11,17 @@ import { cn } from "../../util/cn.js";
 
 export const MCPEndpoint = ({
   serverUrl,
+  operationPath,
   summary,
   data,
 }: {
   serverUrl?: string;
+  operationPath?: string;
   data?: boolean | Record<string, unknown>;
   summary?: string;
 }) => {
   const [isCopied, setIsCopied] = useState(false);
-  const mcpUrl = `${(serverUrl ?? "").replace(/\/+$/, "")}/mcp`;
+  const mcpUrl = `${(serverUrl ?? "").replace(/\/+$/, "")}${operationPath ?? "/mcp"}`;
 
   const name =
     typeof data === "boolean"
@@ -29,11 +31,8 @@ export const MCPEndpoint = ({
   const claudeConfig = `{
   "mcpServers": {
     "${name}": {
-      "command": "npx",
-      "args": [
-        "mcp-remote",
-        "${mcpUrl}"
-      ]
+      "type": "http",
+      "url": "${mcpUrl}"
     }
   }
 }`;
@@ -48,6 +47,14 @@ export const MCPEndpoint = ({
 
   const chatgptConfig = mcpUrl;
 
+  const genericConfig = `{
+  "mcpServers": {
+    "${name}": {
+      "url": "${mcpUrl}"
+    }
+  }
+}`;
+
   const vscodeConfig = `{
   "servers": {
     "${name}": {
@@ -117,11 +124,12 @@ export const MCPEndpoint = ({
           <hr className="my-4" />
 
           <Tabs defaultValue="claude" className="w-full">
-            <TabsList className="grid w-full grid-cols-4">
+            <TabsList className="grid w-full grid-cols-5">
               <TabsTrigger value="claude">Claude</TabsTrigger>
               <TabsTrigger value="chatgpt">ChatGPT</TabsTrigger>
               <TabsTrigger value="cursor">Cursor</TabsTrigger>
               <TabsTrigger value="vscode">VS Code</TabsTrigger>
+              <TabsTrigger value="generic">Generic</TabsTrigger>
             </TabsList>
 
             <Typography className="text-sm max-w-full">
@@ -264,6 +272,34 @@ export const MCPEndpoint = ({
                   <ExternalLinkIcon className="h-3 w-3" />
                 </a>
               </TabsContent>
+
+              <TabsContent value="generic" className="space-y-3">
+                <p>
+                  Generic <InlineCode>.mcp.json</InlineCode> configuration
+                  format that works with most MCP-compatible AI tools.
+                </p>
+                <SyntaxHighlight
+                  showLanguageIndicator
+                  title=".mcp.json"
+                  language="json"
+                  code={genericConfig}
+                  className="mt-2"
+                />
+                <p className="text-sm text-muted-foreground">
+                  Place this file in your project root or the appropriate
+                  configuration directory for your AI tool. The exact location
+                  depends on your specific tool.
+                </p>
+                <a
+                  href="https://modelcontextprotocol.io/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1 text-sm text-primary hover:underline"
+                >
+                  Learn more about MCP
+                  <ExternalLinkIcon className="h-3 w-3" />
+                </a>
+              </TabsContent>
             </Typography>
           </Tabs>
         </div>

package/src/lib/plugins/openapi/OperationListItem.tsx

@@ -88,6 +88,7 @@ export const OperationListItem = ({
           <div className="col-span-full">
             <MCPEndpoint
               serverUrl={displayServerUrl}
+              operationPath={operation.path}
               summary={operation.summary ?? undefined}
               data={operation.extensions?.["x-mcp-server"]}
             />