zudoku 0.83.0 → 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";
@@ -5104,6 +5106,11 @@ var OperationItem = builder.objectRef("OperationItem").implement({
     operationId: t.exposeString("operationId", { nullable: true }),
     summary: t.exposeString("summary", { nullable: true }),
     description: t.exposeString("description", { nullable: true }),
+    // Lean flag so consumers (e.g. the sidebar) can tell an MCP server
+    // endpoint apart without pulling in the whole `x-mcp-server` extension.
+    isMcpServer: t.boolean({
+      resolve: (parent) => resolveExtensions(parent)["x-mcp-server"] !== void 0
+    }),
     contentTypes: t.stringList({
       resolve: (parent) => Object.keys(parent.requestBody?.content ?? {})
     }),
@@ -5360,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];
 
@@ -6062,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}`;
@@ -6162,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({
@@ -6192,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
             });
           }
         }
@@ -6223,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,`,
@@ -6251,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/Search.d.ts

@@ -1,3 +1,5 @@
+import { type PropsWithChildren } from "react";
+export declare const SearchProvider: ({ children }: PropsWithChildren) => import("react").JSX.Element;
 export declare const Search: ({ className }: {
     className?: string;
 }) => import("react").JSX.Element | null;

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/core/plugins.d.ts

@@ -23,6 +23,7 @@ export interface ApiIdentityPlugin {
 export interface SearchProviderPlugin {
     renderSearch: (o: {
         isOpen: boolean;
+        onOpen: () => void;
         onClose: () => void;
     }) => React.JSX.Element | null;
 }

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,8 +1,9 @@
 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;
 export declare function graphql(source: "\n  query GetSchemas($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      title\n      description\n      summary\n      components {\n        schemas {\n          name\n          schema\n          extensions\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetSchemasDocument;
 export declare function graphql(source: "\n  query getServerQuery($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      url\n      servers {\n        url\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetServerQueryDocument;
-export declare function graphql(source: "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetNavigationOperationsDocument;
+export declare function graphql(source: "\n  query GetNavigationOperations($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      extensions\n      description\n      tags {\n        slug\n        name\n        extensions\n        operations {\n          summary\n          slug\n          method\n          operationId\n          path\n          isMcpServer\n        }\n      }\n      components {\n        schemas {\n          __typename\n        }\n      }\n    }\n  }\n"): typeof import("./graphql.js").GetNavigationOperationsDocument;
 export declare function graphql(source: "\n  query SchemaWarmup($input: JSON!, $type: SchemaType!) {\n    schema(input: $input, type: $type) {\n      openapi\n    }\n  }\n"): typeof import("./graphql.js").SchemaWarmupDocument;

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;
@@ -314,6 +339,7 @@ export type GetNavigationOperationsQuery = {
                 method: string;
                 operationId: string | null;
                 path: string;
+                isMcpServer: boolean;
             }>;
         }>;
         components: {
@@ -341,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,7 +25,15 @@ 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 declare const getMcpUrl: (serverUrl?: string, operationPath?: 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;
 export declare const getCursorConfig: (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/configuration/search.md

@@ -182,6 +182,11 @@ You can also pass
 Zudoku's defaults and passed through to Inkeep as-is, so any option Inkeep supports can be used —
 including ones added after this Zudoku version was released.
 
+Zudoku owns the search modal's open state, so `modalSettings.isOpen` is managed for you. The
+<kbd>⌘</kbd>+<kbd>K</kbd> / <kbd>Ctrl</kbd>+<kbd>K</kbd> shortcut is handled by Zudoku's search
+button as well, which is why Inkeep's own `shortcutKey` is disabled by default. Setting it adds an
+additional shortcut rather than replacing it.
+
 For example, to categorize results into tabs based on their URL:
 
 ```typescript

package/docs/guides/mcp-servers.md

@@ -59,6 +59,7 @@ metadata. In this case, the operation's `summary` is used as the server name.
 | --------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `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)                                                   |
+| `url`     | `string` | No       | Overrides the endpoint URL shown in the card and install snippets                                                            |
 | `tools`   | `array`  | No       | Tools metadata (used by Zuplo enrichment; not currently rendered in UI)                                                      |
 
 Each tool in the `tools` array has:
@@ -92,6 +93,53 @@ For example, with this configuration:
 
 The displayed MCP URL will be `https://api.example.com/mcp/docs`.
 
+If your MCP server lives on its own hostname, set `url` on the extension to override the derived
+endpoint:
+
+```json
+{
+  "x-mcp-server": { "name": "docs-mcp", "url": "https://mcp.example.com/mcp" }
+}
+```
+
+An absolute URL is used verbatim everywhere the endpoint appears, and takes precedence over the
+server dropdown. A value without a scheme (such as `/v2/mcp`) is treated as a path on the server URL
+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: