zudoku 0.83.1 → 0.84.0

package/dist/cli/cli.js

@@ -3152,6 +3152,7 @@ var ApiOptionsSchema = z7.object({
   expandAllTags: z7.boolean(),
   showInfoPage: z7.boolean(),
   disableSecurity: z7.boolean(),
+  disableMcpAuthInstructions: z7.boolean(),
   schemaDownload: z7.object({
     enabled: z7.boolean(),
     fileName: z7.string().regex(/^[A-Za-z0-9_-]+$/).optional()
@@ -4178,6 +4179,7 @@ import fs2 from "node:fs/promises";
 import path12 from "node:path";
 import { deepEqual as deepEqual2 } from "fast-equals";
 import { runnerImport as runnerImport3 } from "vite";
+import { parse as parseYaml } from "yaml";
 
 // src/config/validators/BuildSchema.ts
 import path7 from "node:path";
@@ -5365,6 +5367,34 @@ builder.queryType({
 var schema = builder.toSchema();
 var createGraphQLServer = (options) => createYoga({ schema, batching: true, ...options });
 
+// src/lib/plugins/openapi/interfaces.ts
+var DOCUMENT_TYPE_EXTENSION = "x-zudoku-type";
+var MCP_CATALOG = "mcp-catalog";
+
+// src/lib/plugins/openapi/util/documentType.ts
+var MCP_SERVER_EXTENSION = "x-mcp-server";
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "patch",
+  "delete",
+  "options",
+  "head",
+  "trace"
+];
+var httpMethods = new Set(HTTP_METHODS);
+var KNOWN_DOCUMENT_TYPES = [MCP_CATALOG];
+var readDocumentType = (schema2) => schema2[DOCUMENT_TYPE_EXTENSION];
+var isKnownDocumentType = (value) => typeof value === "string" && KNOWN_DOCUMENT_TYPES.includes(value);
+var operationsOf = (schema2) => Object.values(schema2.paths ?? {}).flatMap(
+  (pathItem) => pathItem && typeof pathItem === "object" ? Object.entries(pathItem).filter(([method]) => httpMethods.has(method.toLowerCase())).map(([, operation]) => operation) : []
+);
+var countOperations = (schema2) => operationsOf(schema2).length;
+var countMcpServers = (schema2) => operationsOf(schema2).filter(
+  (operation) => !!operation && typeof operation === "object" && MCP_SERVER_EXTENSION in operation
+).length;
+
 // src/lib/util/ensureArray.ts
 var ensureArray = (value) => Array.isArray(value) ? value : [value];
 
@@ -6067,6 +6097,25 @@ var viteConfigReloadPlugin = () => ({
 
 // src/vite/plugin-api.ts
 var PROCESSED_STORE_SUBPATH = "node_modules/.zudoku/processed";
+var warn = (message) => {
+  console.warn(`[zudoku] ${message}`);
+};
+var resolveDocumentType = (schema2, apiPath = "<unknown>") => {
+  const value = readDocumentType(schema2);
+  if (value === void 0) return void 0;
+  if (isKnownDocumentType(value)) return value;
+  warn(
+    `Unknown "x-zudoku-type" value ${JSON.stringify(value)} in "${apiPath}". Rendering the default API view.`
+  );
+  return void 0;
+};
+var resolveRawDocumentType = (input, apiPath = "<unknown>") => {
+  try {
+    return resolveDocumentType(parseYaml(input), apiPath);
+  } catch {
+    return void 0;
+  }
+};
 var viteApiPlugin = async () => {
   const virtualModuleId4 = "virtual:zudoku-api-plugins";
   const resolvedVirtualModuleId4 = `\0${virtualModuleId4}`;
@@ -6167,28 +6216,12 @@ var viteApiPlugin = async () => {
         );
         const apis = ensureArray(config.apis);
         const apiMetadata = [];
-        const httpMethods = /* @__PURE__ */ new Set([
-          "get",
-          "post",
-          "put",
-          "patch",
-          "delete",
-          "options",
-          "head",
-          "trace"
-        ]);
         for (const apiConfig of apis) {
           if (apiConfig.type === "file" && apiConfig.path) {
             const latestSchema = schemaManager.getLatestSchema(apiConfig.path);
             if (!latestSchema?.schema.info) continue;
-            const operationCount = Object.values(
-              latestSchema.schema.paths ?? {}
-            ).reduce((sum, pathItem) => {
-              if (!pathItem || typeof pathItem !== "object") return sum;
-              return sum + Object.keys(pathItem).filter(
-                (m) => httpMethods.has(m.toLowerCase())
-              ).length;
-            }, 0);
+            const isCatalog = resolveDocumentType(latestSchema.schema, apiConfig.path) === MCP_CATALOG;
+            const operationCount = isCatalog ? countMcpServers(latestSchema.schema) : countOperations(latestSchema.schema);
             const rawVersion = latestSchema.schema.info.version;
             const version = rawVersion ? rawVersion.startsWith("v") || rawVersion.startsWith("V") ? rawVersion : `v${rawVersion}` : void 0;
             apiMetadata.push({
@@ -6197,7 +6230,8 @@ var viteApiPlugin = async () => {
               description: latestSchema.schema.info.description ?? "",
               categories: apiConfig.categories ?? [],
               version,
-              operationCount
+              operationCount,
+              countLabel: isCatalog ? operationCount === 1 ? "server" : "servers" : void 0
             });
           }
         }
@@ -6228,18 +6262,34 @@ var viteApiPlugin = async () => {
             });
             const tags = Array.from(allSlugs);
             const schemaImports = schemaManager.getSchemaImports();
+            const latest = schemas.at(0);
+            const documentType = latest ? resolveDocumentType(latest.schema, apiConfig.path) : void 0;
+            if (documentType === MCP_CATALOG) {
+              if (schemas.length > 1) {
+                warn(
+                  `"${apiConfig.path}" is an MCP catalog with ${schemas.length} versions. Only the latest is rendered; catalog documents do not support version switching.`
+                );
+              }
+              if (latest && countMcpServers(latest.schema) === 0) {
+                warn(
+                  `"${apiConfig.path}" is marked as an MCP catalog but has no operations with "x-mcp-server". The catalog will render empty.`
+                );
+              }
+            }
             code.push(
               "configuredApiPlugins.push(openApiPlugin({",
               `  type: "file",`,
               `  input: ${JSON.stringify(versionedInput)},`,
               `  path: ${JSON.stringify(apiConfig.path)},`,
               `  tagPages: ${JSON.stringify(tags)},`,
+              ...documentType ? [`  documentType: ${JSON.stringify(documentType)},`] : [],
               `  options: {`,
               `    examplesLanguage: config.defaults?.apis?.examplesLanguage ?? config.defaults?.examplesLanguage,`,
               `    supportedLanguages: config.defaults?.apis?.supportedLanguages,`,
               `    disablePlayground: config.defaults?.apis?.disablePlayground,`,
               `    disableSidecar: config.defaults?.apis?.disableSidecar,`,
               `    disableSecurity: config.defaults?.apis?.disableSecurity ?? true,`,
+              `    disableMcpAuthInstructions: config.defaults?.apis?.disableMcpAuthInstructions,`,
               `    showVersionSelect: config.defaults?.apis?.showVersionSelect ?? "if-available",`,
               `    expandAllTags: config.defaults?.apis?.expandAllTags ?? true,`,
               `    showInfoPage: config.defaults?.apis?.showInfoPage,`,
@@ -6256,15 +6306,18 @@ var viteApiPlugin = async () => {
               "}));"
             );
           } else {
+            const documentType = apiConfig.type === "raw" ? resolveRawDocumentType(apiConfig.input, apiConfig.path) : void 0;
             code.push(
               "configuredApiPlugins.push(openApiPlugin({",
               `  ...${JSON.stringify(apiConfig)},`,
+              ...documentType ? [`  documentType: ${JSON.stringify(documentType)},`] : [],
               "  options: {",
               `    examplesLanguage: config.defaults?.apis?.examplesLanguage ?? config.defaults?.examplesLanguage,`,
               `    supportedLanguages: config.defaults?.apis?.supportedLanguages,`,
               `    disablePlayground: config.defaults?.apis?.disablePlayground,`,
               `    disableSidecar: config.defaults?.apis?.disableSidecar,`,
               `    disableSecurity: config.defaults?.apis?.disableSecurity ?? true,`,
+              `    disableMcpAuthInstructions: config.defaults?.apis?.disableMcpAuthInstructions,`,
               `    showVersionSelect: config.defaults?.apis?.showVersionSelect ?? "if-available",`,
               `    expandAllTags: config.defaults?.apis?.expandAllTags ?? false,`,
               `    showInfoPage: config.defaults?.apis?.showInfoPage,`,

package/dist/cli/worker.js

@@ -2386,6 +2386,7 @@ var ApiOptionsSchema = z4.object({
   expandAllTags: z4.boolean(),
   showInfoPage: z4.boolean(),
   disableSecurity: z4.boolean(),
+  disableMcpAuthInstructions: z4.boolean(),
   schemaDownload: z4.object({
     enabled: z4.boolean(),
     fileName: z4.string().regex(/^[A-Za-z0-9_-]+$/).optional()

package/dist/declarations/app/notFoundRoute.d.ts

@@ -0,0 +1,2 @@
+import type { RouteObject } from "react-router";
+export declare const notFoundRoute: RouteObject;

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

@@ -57,6 +57,7 @@ declare const ApiOptionsSchema: z.ZodObject<{
     expandAllTags: z.ZodOptional<z.ZodBoolean>;
     showInfoPage: z.ZodOptional<z.ZodBoolean>;
     disableSecurity: z.ZodOptional<z.ZodBoolean>;
+    disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
     schemaDownload: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7297,6 +7298,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
             disableSecurity: z.ZodOptional<z.ZodBoolean>;
+            disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7333,6 +7335,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
             disableSecurity: z.ZodOptional<z.ZodBoolean>;
+            disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7369,6 +7372,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
             disableSecurity: z.ZodOptional<z.ZodBoolean>;
+            disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7401,6 +7405,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
             disableSecurity: z.ZodOptional<z.ZodBoolean>;
+            disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7437,6 +7442,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
             disableSecurity: z.ZodOptional<z.ZodBoolean>;
+            disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7473,6 +7479,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
             disableSecurity: z.ZodOptional<z.ZodBoolean>;
+            disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;
@@ -7574,6 +7581,7 @@ export declare const ZudokuConfig: z.ZodObject<{
             expandAllTags: z.ZodOptional<z.ZodBoolean>;
             showInfoPage: z.ZodOptional<z.ZodBoolean>;
             disableSecurity: z.ZodOptional<z.ZodBoolean>;
+            disableMcpAuthInstructions: z.ZodOptional<z.ZodBoolean>;
             schemaDownload: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
                 fileName: z.ZodOptional<z.ZodOptional<z.ZodString>>;

package/dist/declarations/lib/components/context/RenderContext.d.ts

@@ -9,3 +9,6 @@ export type RenderContextValue = {
     ssrAuth?: SSRAuthState;
 };
 export declare const RenderContext: import("react").Context<RenderContextValue>;
+export declare const setSsrStatus: (renderContext: RenderContextValue, status: number, { onlyIfUnset }?: {
+    onlyIfUnset?: boolean;
+}) => void;

package/dist/declarations/lib/plugins/api-catalog/index.d.ts

@@ -7,6 +7,7 @@ export type ApiCatalogItem = {
     categories: CatalogCategory[];
     version?: string;
     operationCount?: number;
+    countLabel?: string;
 };
 export type CatalogCategory = {
     label: string;

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

@@ -1,7 +1,8 @@
 import { type McpServerData } from "./mcp-configs.js";
-export declare const MCPEndpoint: ({ serverUrl, operationPath, summary, data, }: {
+export declare const MCPEndpoint: ({ serverUrl, operationPath, summary, data, disableAuthInstructions, }: {
     serverUrl?: string;
     operationPath?: string;
     data?: McpServerData;
     summary?: string;
+    disableAuthInstructions?: boolean;
 }) => import("react").JSX.Element;

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

@@ -0,0 +1,5 @@
+export declare const GetMcpCatalogQuery: import("./graphql/graphql.js").TypedDocumentString<import("./graphql/graphql.js").GetMcpCatalogQuery, {
+    input: any;
+    type: import("./graphql/graphql.js").SchemaType;
+}>;
+export declare const McpCatalog: () => import("react").JSX.Element;

package/dist/declarations/lib/plugins/openapi/components/SelectOnClick.d.ts

@@ -1,5 +1,6 @@
 import { type SlotProps } from "@radix-ui/react-slot";
-export declare const SelectOnClick: ({ asChild, onClick, enabled, ...props }: {
+export declare const SelectOnClick: ({ asChild, onClick, copyValue, enabled, ...props }: {
     asChild?: boolean;
     enabled?: boolean;
+    copyValue?: string;
 } & SlotProps) => import("react").JSX.Element;

package/dist/declarations/lib/plugins/openapi/graphql/gql.d.ts

@@ -1,4 +1,5 @@
 export declare function graphql(source: "\n  query ServersQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n"): typeof import("./graphql.js").ServersQueryDocument;
+export declare function graphql(source: "\n  query GetMcpCatalog($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      title\n      description\n      tags {\n        name\n        slug\n        operations {\n          slug\n          summary\n          description\n          operationId\n          path\n          extensions\n          servers {\n            url\n          }\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetMcpCatalogDocument;
 export declare function graphql(source: "\n  fragment OperationsFragment on OperationItem {\n    slug\n    summary\n    method\n    description\n    operationId\n    contentTypes\n    path\n    deprecated\n    extensions\n    servers {\n      url\n      description\n    }\n    parameters {\n      name\n      in\n      description\n      required\n      schema\n      style\n      explode\n      allowReserved\n      examples {\n        name\n        description\n        externalValue\n        value\n        summary\n      }\n    }\n    security {\n      schemes {\n        scopes\n        scheme {\n          name\n          type\n          description\n          in\n          paramName\n          scheme\n          bearerFormat\n          openIdConnectUrl\n          flows {\n            implicit {\n              authorizationUrl\n              scopes {\n                name\n                description\n              }\n            }\n            password {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            clientCredentials {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            authorizationCode {\n              authorizationUrl\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n          }\n        }\n      }\n    }\n    requestBody {\n      content {\n        mediaType\n        encoding {\n          name\n        }\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        schema\n      }\n      description\n      required\n    }\n    responses {\n      statusCode\n      links\n      description\n      content {\n        examples {\n          name\n          description\n          externalValue\n          value\n          summary\n        }\n        mediaType\n        encoding {\n          name\n        }\n        schema\n      }\n    }\n  }\n"): typeof import("./graphql.js").OperationsFragmentFragmentDoc;
 export declare function graphql(source: "\n  query OperationsForTag(\n    $input: JSON!\n    $type: SchemaType!\n    $tag: String\n    $untagged: Boolean\n  ) {\n    schema(input: $input, type: $type) {\n      servers {\n        url\n      }\n      description\n      summary\n      title\n      url\n      version\n      tag(slug: $tag, untagged: $untagged) {\n        name\n        description\n        operations {\n          slug\n          ...OperationsFragment\n        }\n        extensions\n        next {\n          name\n          slug\n          extensions\n        }\n        prev {\n          name\n          slug\n          extensions\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").OperationsForTagDocument;
 export declare function graphql(source: "\n  query SchemaInfo($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      servers {\n        url\n        description\n      }\n      license {\n        name\n        url\n        identifier\n      }\n      termsOfService\n      externalDocs {\n        description\n        url\n      }\n      contact {\n        name\n        url\n        email\n      }\n      description\n      summary\n      title\n      url\n      version\n      tags {\n        name\n        description\n        extensions\n      }\n      components {\n        securitySchemes {\n          name\n          type\n          description\n          in\n          paramName\n          scheme\n          bearerFormat\n          openIdConnectUrl\n          flows {\n            implicit {\n              authorizationUrl\n              scopes {\n                name\n                description\n              }\n            }\n            password {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            clientCredentials {\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n            authorizationCode {\n              authorizationUrl\n              tokenUrl\n              scopes {\n                name\n                description\n              }\n            }\n          }\n        }\n      }\n      webhooks {\n        name\n        method\n        summary\n        description\n      }\n    }\n  }\n"): typeof import("./graphql.js").SchemaInfoDocument;

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

@@ -23,6 +23,31 @@ export type ServersQueryQuery = {
         }>;
     };
 };
+export type GetMcpCatalogQueryVariables = Exact<{
+    input: any;
+    type: SchemaType;
+}>;
+export type GetMcpCatalogQuery = {
+    schema: {
+        title: string;
+        description: string | null;
+        tags: Array<{
+            name: string | null;
+            slug: string | null;
+            operations: Array<{
+                slug: string;
+                summary: string | null;
+                description: string | null;
+                operationId: string | null;
+                path: string;
+                extensions: any;
+                servers: Array<{
+                    url: string;
+                }>;
+            }>;
+        }>;
+    };
+};
 export type OperationsFragmentFragment = {
     slug: string;
     summary: string | null;
@@ -342,6 +367,7 @@ export declare class TypedDocumentString<TResult, TVariables> extends String imp
 }
 export declare const OperationsFragmentFragmentDoc: TypedDocumentString<OperationsFragmentFragment, unknown>;
 export declare const ServersQueryDocument: TypedDocumentString<ServersQueryQuery, ServersQueryQueryVariables>;
+export declare const GetMcpCatalogDocument: TypedDocumentString<GetMcpCatalogQuery, GetMcpCatalogQueryVariables>;
 export declare const OperationsForTagDocument: TypedDocumentString<OperationsForTagQuery, OperationsForTagQueryVariables>;
 export declare const SchemaInfoDocument: TypedDocumentString<SchemaInfoQuery, SchemaInfoQueryVariables>;
 export declare const GetSchemasDocument: TypedDocumentString<GetSchemasQuery, GetSchemasQueryVariables>;

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

@@ -1,6 +1,6 @@
 import type { ZudokuPlugin } from "../../core/plugins.js";
 import type { GetNavigationOperationsQuery as GetNavigationOperationsQueryResult } from "./graphql/graphql.js";
-import type { OasPluginConfig } from "./interfaces.js";
+import { type OasPluginConfig } from "./interfaces.js";
 export declare const GetNavigationOperationsQuery: import("./graphql/graphql.js").TypedDocumentString<GetNavigationOperationsQueryResult, {
     input: any;
     type: import("./graphql/graphql.js").SchemaType;

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

@@ -58,12 +58,16 @@ export type GenerateCodeSnippetFn = (options: {
     example?: any | null;
     resolvedAuth?: ResolvedAuth;
 }) => string | false;
+export declare const DOCUMENT_TYPE_EXTENSION = "x-zudoku-type";
+export declare const MCP_CATALOG = "mcp-catalog";
+export type OasDocumentType = typeof MCP_CATALOG;
 type BaseOasConfig = {
     server?: string;
     path?: string;
     skipPreload?: boolean;
     tagPages?: Array<string>;
     schemaImports?: SchemaImports;
+    documentType?: OasDocumentType;
     options?: {
         examplesLanguage?: string;
         supportedLanguages?: {
@@ -73,6 +77,7 @@ type BaseOasConfig = {
         disablePlayground?: boolean;
         disableSidecar?: boolean;
         disableSecurity?: boolean;
+        disableMcpAuthInstructions?: boolean;
         showVersionSelect?: "always" | "if-available" | "hide";
         expandAllTags?: boolean;
         showInfoPage?: boolean;

package/dist/declarations/lib/plugins/openapi/mcp-configs.d.ts

@@ -6,6 +6,12 @@ export interface AuthHeader {
 export type AuthType = "none" | "apiKey" | "oauth";
 export declare const getAuthType: (data?: McpServerData) => AuthType;
 export declare const getAuthHeader: (data?: McpServerData) => AuthHeader | undefined;
+export declare const resolveMcpAuth: (data?: McpServerData, options?: {
+    disableAuthInstructions?: boolean;
+}) => {
+    authType: AuthType;
+    auth?: AuthHeader;
+};
 export interface McpSubApp {
     id: string;
     label: string;
@@ -19,6 +25,14 @@ export interface McpApp {
 export declare const MCP_APPS: McpApp[];
 export declare const getVisibleApps: (authType: AuthType) => McpApp[];
 export declare const getMcpServerName: (data?: McpServerData, summary?: string) => string;
+export type McpTool = {
+    name: string;
+    description?: string;
+};
+export declare const isMcpServerObject: (data?: McpServerData) => data is Record<string, unknown>;
+export declare const isMcpServerData: (value: unknown) => value is McpServerData;
+export declare const getMcpServerTitle: (data?: McpServerData, summary?: string | null, operationId?: string | null) => string;
+export declare const getMcpTools: (data?: McpServerData) => McpTool[];
 export declare const getMcpUrl: (serverUrl?: string, operationPath?: string, data?: McpServerData) => string;
 export declare const getClaudeCodeCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;
 export declare const getCodexCliCommand: (name: string, mcpUrl: string, auth?: AuthHeader) => string;

package/dist/declarations/lib/plugins/openapi/util/documentType.d.ts

@@ -0,0 +1,8 @@
+import type { OpenAPIDocument } from "../../../oas/parser/index.js";
+import { type OasDocumentType } from "../interfaces.js";
+export declare const MCP_SERVER_EXTENSION = "x-mcp-server";
+export declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
+export declare const readDocumentType: (schema: OpenAPIDocument) => unknown;
+export declare const isKnownDocumentType: (value: unknown) => value is OasDocumentType;
+export declare const countOperations: (schema: OpenAPIDocument) => number;
+export declare const countMcpServers: (schema: OpenAPIDocument) => number;

package/dist/declarations/lib/plugins/openapi/util/getRoutes.d.ts

@@ -1,7 +1,7 @@
 import { type RouteObject } from "react-router";
 import type { GraphQLClient } from "../client/GraphQLClient.js";
 import { type OpenApiPluginOptions } from "../index.js";
-import type { OasPluginConfig, VersionEntry } from "../interfaces.js";
+import { type OasPluginConfig, type VersionEntry } from "../interfaces.js";
 export declare const getVersionMetadata: (config: OasPluginConfig) => {
     versions: string[];
     versionMap: Record<string, {

package/dist/declarations/lib/plugins/openapi/util/sanitizeMarkdownForMetatag.d.ts

@@ -1 +1,2 @@
+export declare function stripMarkdown(description: string, maxLength?: number): string;
 export declare function sanitizeMarkdownForMetatag(description: string, maxLength?: number): string;

package/dist/flat-config.d.ts

@@ -521,6 +521,7 @@ export interface _Schema20 {
   expandAllTags?: boolean
   showInfoPage?: boolean
   disableSecurity?: boolean
+  disableMcpAuthInstructions?: boolean
   schemaDownload?: {
     enabled?: boolean
     fileName?: string

package/docs/configuration/api-reference.md

@@ -207,6 +207,7 @@ const config = {
       disablePlayground: false, // Disable the interactive API playground
       disableSidecar: false, // Disable the sidecar completely
       disableSecurity: true, // Disable security scheme display and playground auth (default)
+      disableMcpAuthInstructions: false, // Hide auth steps in the MCP server card
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: true, // Control initial expanded state of tag categories
       showInfoPage: true, // Always show the info page (unset = show only if a description is set)
@@ -229,6 +230,11 @@ Available options:
 - `disableSecurity`: Disable OpenAPI security scheme display (auth badges on operations, security
   schemes section on the info page, and the Authorize dialog in the playground). Disabled by default
   (`true`). Set to `false` to enable security scheme support
+- `disableMcpAuthInstructions`: Hide the authentication instructions on
+  [MCP server](../guides/mcp-servers.md) endpoints. The MCP card normally derives a credential
+  header from the operation's security scheme and shows it in every install snippet. Set to `true`
+  to render the server as unauthenticated instead — no header snippets and no "replace
+  `YOUR_API_KEY`" steps
 - `showVersionSelect`: Control version selector visibility
   - `"if-available"`: Show version selector only when multiple versions exist (default)
   - `"always"`: Always show version selector (disabled if only one version)
@@ -260,6 +266,7 @@ const config = {
       disablePlayground: false, // Disable the interactive API playground
       disableSidecar: false, // Disable the sidecar completely
       disableSecurity: true, // Disable security scheme display and playground auth (default)
+      disableMcpAuthInstructions: false, // Hide auth steps in the MCP server card
       showVersionSelect: "if-available", // Control version selector visibility
       expandAllTags: false, // Control initial expanded state of tag categories
       showInfoPage: true, // Always show the info page (unset = show only if a description is set)

package/docs/guides/mcp-servers.md

@@ -107,6 +107,39 @@ server dropdown. A value without a scheme (such as `/v2/mcp`) is treated as a pa
 instead. See the
 [`x-mcp-server` reference](/docs/openapi-extensions/x-mcp-server#overriding-the-url) for details.
 
+## Authentication instructions
+
+When the `x-mcp-server` extension carries `security` and `securitySchemes` (Zuplo adds these
+automatically for authenticated routes), the card derives the credential header from the first
+scheme and threads it through every install snippet — for example an
+`Authorization: Bearer YOUR_API_KEY` header in the `mcp.json` samples, plus a step telling users to
+replace the placeholder with their key. API key auth also hides the clients that cannot send custom
+headers (Claude Desktop and ChatGPT), and the one-click install buttons for Cursor and VS Code,
+since those links cannot carry a secret.
+
+If your users get their credentials some other way — the key is injected by a proxy, handled by your
+own login flow, or simply documented elsewhere — turn the authentication instructions off in your
+Zudoku config:
+
+```tsx title="zudoku.config.tsx"
+const config: ZudokuConfig = {
+  apis: [
+    {
+      type: "file",
+      input: "./mcp-api.json",
+      path: "mcp",
+      options: {
+        disableMcpAuthInstructions: true,
+      },
+    },
+  ],
+};
+```
+
+The card then renders the server as if it were unauthenticated, whatever its security says: no
+header in the snippets, no placeholder step, and every client available again. Set it under
+`defaults.apis` instead to apply it to all APIs.
+
 ## Complete example
 
 This is a minimal but complete OpenAPI spec that produces an MCP endpoint page:

package/docs/openapi-extensions/x-mcp-server.md

@@ -130,5 +130,14 @@ When detected, the operation page shows:
 The standard method badge, request body, parameters, and sidecar panels are hidden for MCP
 endpoints.
 
+When the extension carries `security` and `securitySchemes`, the card also documents the credential
+header and adds it to every install snippet. Set the
+[`disableMcpAuthInstructions`](/docs/configuration/api-reference#options) API option to render the
+server as unauthenticated instead.
+
 For a full walkthrough including Zudoku configuration, see the
 [Documenting MCP Servers guide](/docs/guides/mcp-servers).
+
+If a document describes several MCP servers, mark it with
+[`x-zudoku-type: mcp-catalog`](./x-zudoku-type) to render them as a searchable catalog instead of
+individual operation pages.

package/docs/openapi-extensions/x-zudoku-type.md

@@ -0,0 +1,80 @@
+---
+title: x-zudoku-type
+sidebar_icon: layout-grid
+---
+
+Use `x-zudoku-type` to change how Zudoku renders an entire OpenAPI document, instead of the default
+REST API view.
+
+## Location
+
+The extension is added at the **Root Object** level — the outermost level of the OpenAPI
+description.
+
+| Option          | Type     | Description                            |
+| --------------- | -------- | -------------------------------------- |
+| `x-zudoku-type` | `string` | The renderer to use for this document. |
+
+| Value           | Renders as                                                      |
+| --------------- | --------------------------------------------------------------- |
+| `"mcp-catalog"` | A searchable, filterable catalog of the document's MCP servers. |
+
+Values Zudoku does not recognise are ignored with a build warning, and the document falls back to
+the default API view. This keeps a description written for a newer version of Zudoku building
+against an older one.
+
+## `mcp-catalog`
+
+A catalog document renders as a **single page** listing every operation marked with
+[`x-mcp-server`](./x-mcp-server) as a card, in one grid that can be searched and filtered by tag.
+Selecting a card opens the server's install instructions and its tool list.
+
+Because the whole document becomes a catalog, a few things change:
+
+- **Only MCP servers are rendered.** Operations without `x-mcp-server` are not shown, and the
+  document contributes no sidebar entries, tag pages, or schema page. If you also want to document
+  plain REST endpoints, put them in a separate OpenAPI document with its own `apis` entry.
+- **Tags become filters** rather than pages or headings. Each tag appears as a filter chip and as a
+  badge on its servers' cards; the grid itself stays flat. Servers without a tag are filed under
+  "Other". The active filter is kept in the URL as `?tag=`, so a filtered view can be linked.
+- **Only the latest version is rendered.** Catalog documents do not support version switching; a
+  versioned API marked as a catalog warns at build time.
+
+The extension is read while your schema is processed, so it applies to `type: "file"` and
+`type: "raw"` APIs. `type: "url"` schemas are fetched in the browser after routing is decided, so
+the flag has no effect on them.
+
+## Example
+
+```yaml
+openapi: 3.1.0
+x-zudoku-type: mcp-catalog
+info:
+  title: Employee MCP Servers
+  version: 1.0.0
+servers:
+  - url: https://mcp.example.com
+tags:
+  - name: CRM & Customer Operations
+paths:
+  /v1/salesforce/sales-cloud/mcp:
+    post:
+      summary: Salesforce Sales Cloud
+      description: Read-only access to accounts, opportunities and contacts.
+      tags:
+        - CRM & Customer Operations
+      x-mcp-server:
+        name: salesforce-sales-cloud
+        version: 1.0.0
+        tools:
+          - name: searchAccounts
+            description: Find accounts by name, domain or owner.
+```
+
+This renders one catalog page with a single `Salesforce Sales Cloud` card, reachable via a
+`CRM & Customer Operations` filter chip. The card opens install snippets for Claude, ChatGPT,
+Cursor, VS Code and Codex, alongside the server's tools.
+
+## Related
+
+- [`x-mcp-server`](./x-mcp-server) — mark an individual operation as an MCP server

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.83.1",
+  "version": "0.84.0",
   "type": "module",
   "engines": {
     "node": ">=22.22.0"

package/src/app/main.tsx

@@ -29,6 +29,7 @@ import { RouteGuard } from "../lib/core/RouteGuard.js";
 import type { ZudokuContextOptions } from "../lib/core/ZudokuContext.js";
 import { RouterError } from "../lib/errors/RouterError.js";
 import { ZuploEnv } from "./env.js";
+import { notFoundRoute } from "./notFoundRoute.js";
 import { processRoutes } from "./processRoutes.js";
 import { createRedirectRoutes } from "./utils/createRedirectRoutes.js";
 import {
@@ -109,7 +110,7 @@ export const getRoutesByOptions = (
           }))
         : [],
     )
-    .concat([{ path: "*", element: <StatusPage statusCode={404} /> }])
+    .concat([notFoundRoute])
     .map((route) => ({
       ...route,
       errorElement: <RouterError className="w-full m-0" />,