zudoku 0.71.10 → 0.73.0

package/dist/cli/cli.js

@@ -3810,7 +3810,7 @@ import {
 // package.json
 var package_default = {
   name: "zudoku",
-  version: "0.71.9",
+  version: "0.72.0",
   type: "module",
   sideEffects: [
     "**/*.css",
@@ -3871,7 +3871,6 @@ var package_default = {
     "./vite": "./src/vite/index.ts",
     "./app/*": "./src/app/*",
     "./hooks": "./src/lib/hooks/index.ts",
-    "./main.css": "./src/app/main.css",
     "./processors/*": "./src/lib/plugins/openapi/processors/*.ts",
     "./with-zuplo": "./src/zuplo/with-zuplo.ts",
     "./testing": "./src/lib/testing/index.tsx"
@@ -3882,7 +3881,7 @@ var package_default = {
     typecheck: "tsc --project tsconfig.app.json --noEmit",
     "generate:types": "tsx scripts/generate-types.js && tsx scripts/generate-flat-config.js",
     "build:standalone": "vite build --mode standalone --config vite.standalone.config.ts --log-level=error",
-    prepublishOnly: "tsx scripts/generate-publish-exports.ts",
+    prepublishOnly: "tsx scripts/generate-publish-exports.ts && publint .",
     postpublish: "git checkout -- package.json",
     clean: "rm -rf dist",
     codegen: "graphql-codegen --config ./src/codegen.ts"
@@ -4002,10 +4001,10 @@ var package_default = {
     vaul: "1.1.2",
     vfile: "6.0.3",
     vite: "7.3.1",
-    yaml: "2.8.2",
+    yaml: "2.8.3",
     yargs: "18.0.0",
     zod: "4.3.6",
-    zustand: "5.0.11"
+    zustand: "5.0.12"
   },
   devDependencies: {
     "@clerk/clerk-js": "^5.125.3",
@@ -6606,6 +6605,10 @@ ${markdownContent}`;
     description: frontmatter.description
   };
 };
+var getMarkdownOutputPath = (distDir, routePath) => {
+  const segments = routePath === "/" ? ["index"] : routePath.split("/").filter(Boolean);
+  return `${path14.join(distDir, ...segments)}.md`;
+};
 var viteMarkdownExportPlugin = () => {
   let markdownFiles = {};
   let markdownFileInfos = [];
@@ -6699,8 +6702,7 @@ var viteMarkdownExportPlugin = () => {
             description,
             content: finalMarkdown
           });
-          const segments = routePath === "/" ? ["index"] : routePath.split("/").filter(Boolean);
-          const outputPath = `${path14.join(distDir, ...segments)}.md`;
+          const outputPath = getMarkdownOutputPath(distDir, routePath);
           await mkdir2(path14.dirname(outputPath), { recursive: true });
           await writeFile2(outputPath, finalMarkdown, "utf-8");
         } catch (error) {
@@ -7896,8 +7898,14 @@ var prerender = async ({
     }
     if (!docsConfig.publishMarkdown) {
       await Promise.all(
-        markdownFileInfos.map((info) => rm(info.filePath).catch(() => {
-        }))
+        markdownFileInfos.map((info) => {
+          const outputPath = getMarkdownOutputPath(distDir, info.routePath);
+          if (!path21.resolve(outputPath).startsWith(path21.resolve(distDir))) {
+            return;
+          }
+          return rm(outputPath).catch(() => {
+          });
+        })
       );
     }
   }

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/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.71.10",
+  "version": "0.73.0",
   "type": "module",
   "sideEffects": [
     "**/*.css",
@@ -130,7 +130,6 @@
       "types": "./dist/declarations/lib/hooks/index.d.ts",
       "default": "./src/lib/hooks/index.ts"
     },
-    "./main.css": "./src/app/main.css",
     "./processors/*": {
       "types": "./dist/declarations/lib/plugins/openapi/processors/*.d.ts",
       "default": "./src/lib/plugins/openapi/processors/*.ts"
@@ -259,10 +258,10 @@
     "vaul": "1.1.2",
     "vfile": "6.0.3",
     "vite": "7.3.1",
-    "yaml": "2.8.2",
+    "yaml": "2.8.3",
     "yargs": "18.0.0",
     "zod": "4.3.6",
-    "zustand": "5.0.11"
+    "zustand": "5.0.12"
   },
   "devDependencies": {
     "@clerk/clerk-js": "^5.125.3",

package/src/lib/authentication/components/OAuthErrorPage.tsx

@@ -13,19 +13,17 @@ const errorDetailsMap: Record<string, { message: string }> = {
       "The authentication request was invalid. Please try signing in again.",
   },
   unauthorized_client: {
-    message:
-      "This application is not authorized to access your account. Please contact support.",
+    message: "This application is not authorized to access your account.",
   },
   access_denied: {
     message:
       "You denied access to this application. To continue, please sign in and grant access.",
   },
   unsupported_response_type: {
-    message:
-      "The authentication method is not supported. Please contact support.",
+    message: "The authentication method is not supported.",
   },
   invalid_scope: {
-    message: "The requested permissions are invalid. Please contact support.",
+    message: "The requested permissions are invalid.",
   },
   server_error: {
     message:
@@ -37,15 +35,14 @@ const errorDetailsMap: Record<string, { message: string }> = {
   },
   // Token errors
   invalid_client: {
-    message: "Invalid application credentials. Please contact support.",
+    message: "Invalid application credentials.",
   },
   invalid_grant: {
     message:
       "The authentication code has expired or is invalid. Please sign in again.",
   },
   unsupported_grant_type: {
-    message:
-      "The authentication method is not supported. Please contact support.",
+    message: "The authentication method is not supported.",
   },
   // Custom errors
   invalid_state: {
@@ -64,8 +61,7 @@ const errorDetailsMap: Record<string, { message: string }> = {
     message: "Your authentication session has expired. Please sign in again.",
   },
   configuration_error: {
-    message:
-      "There is an issue with the authentication configuration. Please contact support.",
+    message: "There is an issue with the authentication configuration.",
   },
   unknown_error: {
     message:

package/src/lib/authentication/providers/openid.tsx

@@ -13,7 +13,7 @@ import type {
 import { CoreAuthenticationPlugin } from "../AuthenticationPlugin.js";
 import { CallbackHandler } from "../components/CallbackHandler.js";
 import { OAuthErrorPage } from "../components/OAuthErrorPage.js";
-import { AuthorizationError } from "../errors.js";
+import { AuthorizationError, OAuthAuthorizationError } from "../errors.js";
 import { type UserProfile, useAuthState } from "../state.js";
 
 const CODE_VERIFIER_KEY = "code-verifier";
@@ -106,6 +106,19 @@ export class OpenIDAuthenticationProvider
       throw new AuthorizationError("No expires_in in response");
     }
 
+    const accessToken = response.access_token;
+    if (accessToken.split(".").length !== 3) {
+      throw new OAuthAuthorizationError(
+        "The access token received is not a valid JWT.",
+        {
+          error: "configuration_error",
+          error_description:
+            "The authentication provider is issuing opaque tokens instead of JWTs. " +
+            "Ensure you have configured the correct `audience` in your authentication settings.",
+        },
+      );
+    }
+
     const claims = response.id_token
       ? oauth.getValidatedIdTokenClaims(response)
       : undefined;

package/src/lib/components/DeveloperHint.tsx

@@ -17,7 +17,7 @@ export const DeveloperHint = ({
   if (process.env.NODE_ENV !== "development") return null;
 
   return (
-    <Alert variant="info" className={className}>
+    <Alert variant="info" className={className} fit="loose">
       <InfoIcon />
       <AlertTitle>Developer hint</AlertTitle>
       <AlertDescription>

package/src/lib/components/Layout.tsx

@@ -12,9 +12,9 @@ import { Slot } from "./Slot.js";
 import { Spinner } from "./Spinner.js";
 
 const LoadingFallback = () => (
-  <main className="col-span-full row-span-full grid place-items-center">
+  <div className="col-span-full row-span-full grid place-items-center">
     <Spinner />
-  </main>
+  </div>
 );
 
 export const Layout = ({ children }: { children?: ReactNode }) => {

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"]}
             />

package/src/lib/plugins/openapi/playground/Playground.tsx

@@ -256,12 +256,13 @@ export const Playground = ({
           break;
       }
 
+      const upperMethod = method.toUpperCase();
       const request = new Request(
         createUrl(server ?? selectedServer, url, data),
         {
-          method,
+          method: upperMethod,
           headers,
-          body: ["GET", "HEAD"].includes(method.toUpperCase()) ? null : body,
+          body: ["GET", "HEAD"].includes(upperMethod) ? null : body,
         },
       );
 

package/src/lib/plugins/openapi/schema/SchemaView.tsx

@@ -153,7 +153,7 @@ const ObjectSchemaView = ({
     return properties ? { group, properties } : [];
   });
 
-  const deprecatedProperties = groupedProperties["deprecated"];
+  const deprecatedProperties = groupedProperties.deprecated;
 
   const additionalObjectProperties = typeof schema.additionalProperties ===
     "object" && <SchemaView schema={schema.additionalProperties} embedded />;

package/src/lib/testing/index.tsx

@@ -120,7 +120,7 @@ const StaticZudoku = ({
         ],
       },
     ],
-    { initialEntries: [path] },
+    { initialEntries: [path], basename: options.basePath },
   );
 
   return (

package/src/lib/util/problemJson.ts

@@ -41,6 +41,26 @@ const normalizeProblemJson = (data: unknown): ProblemJson | undefined => {
   } as ProblemJson;
 };
 
+/** Some gateways return RFC 7807-shaped bodies with `application/json`. */
+const normalizeProblemJsonIfProblemLike = (
+  data: unknown,
+): ProblemJson | undefined => {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return;
+  }
+
+  const record = data as Record<string, unknown>;
+  const hasDetail = typeof record.detail === "string";
+  const hasTitle = typeof record.title === "string";
+  const hasStatus = typeof record.status === "number";
+
+  if (!hasDetail && !(hasTitle && hasStatus)) {
+    return;
+  }
+
+  return normalizeProblemJson(data);
+};
+
 export const getProblemJson = async (
   response: Response,
 ): Promise<ProblemJson | undefined> => {
@@ -54,10 +74,25 @@ export const getProblemJson = async (
 };
 
 export const throwIfProblemJson = async (response: Response) => {
-  if (!response.ok) {
+  if (response.ok) {
+    return;
+  }
+
+  const contentType = response.headers.get("content-type") ?? "";
+
+  if (isProblemJsonContentType(response)) {
     const problem = await getProblemJson(response);
     if (problem) {
       throw new Error(problem.detail ?? problem.title ?? "Unknown error");
     }
+    return;
+  }
+
+  if (contentType.includes("application/json")) {
+    const data = await parseJsonSafe(response.clone());
+    const problem = normalizeProblemJsonIfProblemLike(data);
+    if (problem) {
+      throw new Error(problem.detail ?? problem.title ?? "Unknown error");
+    }
   }
 };

package/src/vite/plugin-markdown-export.ts

@@ -49,6 +49,12 @@ const processMarkdownFile = async (
  *
  * It also writes metadata to markdown-info.json used by the llms.txt generator.
  */
+export const getMarkdownOutputPath = (distDir: string, routePath: string) => {
+  const segments =
+    routePath === "/" ? ["index"] : routePath.split("/").filter(Boolean);
+  return `${path.join(distDir, ...segments)}.md`;
+};
+
 const viteMarkdownExportPlugin = (): Plugin => {
   let markdownFiles: Record<string, string> = {};
   let markdownFileInfos: MarkdownFileInfo[] = [];
@@ -180,12 +186,7 @@ const viteMarkdownExportPlugin = (): Plugin => {
             content: finalMarkdown,
           });
 
-          const segments =
-            routePath === "/"
-              ? ["index"]
-              : routePath.split("/").filter(Boolean);
-
-          const outputPath = `${path.join(distDir, ...segments)}.md`;
+          const outputPath = getMarkdownOutputPath(distDir, routePath);
 
           await mkdir(path.dirname(outputPath), { recursive: true });
 

package/src/vite/prerender/prerender.ts

@@ -13,7 +13,10 @@ import type { ZudokuConfig } from "../../config/validators/ZudokuConfig.js";
 import { runPluginTransformConfig } from "../../lib/core/transform-config.js";
 import invariant from "../../lib/util/invariant.js";
 import { joinUrl } from "../../lib/util/joinUrl.js";
-import type { MarkdownFileInfo } from "../plugin-markdown-export.js";
+import {
+  getMarkdownOutputPath,
+  type MarkdownFileInfo,
+} from "../plugin-markdown-export.js";
 import { isTTY, throttle, writeLine } from "../reporter.js";
 import { generateSitemap } from "../sitemap.js";
 import { routesToPaths, routesToRewrites } from "./utils.js";
@@ -224,7 +227,13 @@ export const prerender = async ({
 
     if (!docsConfig.publishMarkdown) {
       await Promise.all(
-        markdownFileInfos.map((info) => rm(info.filePath).catch(() => {})),
+        markdownFileInfos.map((info) => {
+          const outputPath = getMarkdownOutputPath(distDir, info.routePath);
+          if (!path.resolve(outputPath).startsWith(path.resolve(distDir))) {
+            return;
+          }
+          return rm(outputPath).catch(() => {});
+        }),
       );
     }
   }