zudoku 0.0.0-fdf886de → 0.0.0-fe92c9e1

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

@@ -0,0 +1,273 @@
+import { CheckIcon, CopyIcon, ExternalLinkIcon } from "lucide-react";
+import { useState } from "react";
+import { InlineCode } from "../../components/InlineCode.js";
+import { Typography } from "../../components/Typography.js";
+import { Button } from "../../ui/Button.js";
+import { Callout } from "../../ui/Callout.js";
+import { Card } from "../../ui/Card.js";
+import { SyntaxHighlight } from "../../ui/SyntaxHighlight.js";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "../../ui/Tabs.js";
+import { cn } from "../../util/cn.js";
+
+export const MCPEndpoint = ({
+  serverUrl,
+  summary,
+  data,
+}: {
+  serverUrl?: string;
+  data?: boolean | Record<string, unknown>;
+  summary?: string;
+}) => {
+  const [isCopied, setIsCopied] = useState(false);
+  const mcpUrl = `${(serverUrl ?? "").replace(/\/+$/, "")}/mcp`;
+
+  const name =
+    typeof data === "boolean"
+      ? (summary ?? "mcp-server")
+      : (data?.name ?? summary ?? "mcp-server");
+
+  const claudeConfig = `{
+  "mcpServers": {
+    "${name}": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "${mcpUrl}"
+      ]
+    }
+  }
+}`;
+
+  const cursorConfig = `{
+  "mcpServers": {
+    "${name}": {
+      "url": "${mcpUrl}"
+    }
+  }
+}`;
+
+  const chatgptConfig = mcpUrl;
+
+  const vscodeConfig = `{
+  "servers": {
+    "${name}": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "${mcpUrl}"
+      ]
+    }
+  }
+}`;
+
+  const handleCopy = () => {
+    void navigator.clipboard.writeText(mcpUrl).then(() => {
+      setIsCopied(true);
+      setTimeout(() => setIsCopied(false), 2000);
+    });
+  };
+
+  return (
+    <Card className="p-6 mb-6 max-w-screen-md">
+      <div className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold mb-2">MCP Endpoint</h3>
+          <p className="text-sm text-muted-foreground mb-3">
+            Copy the url to connect any{" "}
+            <a
+              href="https://modelcontextprotocol.io/"
+              target="_blank"
+              rel="noopener"
+              className="text-primary hover:underline"
+            >
+              MCP
+            </a>
+            -compatible AI tool
+          </p>
+
+          <div
+            className={cn(
+              "relative flex items-center gap-2 p-3 rounded-md border border-primary/50",
+            )}
+          >
+            <InlineCode className="bg-primary/20 px-4 py-2 flex-1 border-none">
+              {mcpUrl}
+            </InlineCode>
+            <Button
+              onClick={handleCopy}
+              variant="ghost"
+              size="icon"
+              className="h-8 w-8"
+            >
+              {isCopied ? (
+                <CheckIcon className="h-4 w-4 text-green-600" />
+              ) : (
+                <CopyIcon className="h-4 w-4" />
+              )}
+            </Button>
+          </div>
+        </div>
+
+        <div>
+          <h3 className="text-lg font-semibold mb-2">AI Tool Configuration</h3>
+          <p className="text-sm text-muted-foreground mb-3">
+            Choose your AI tool and copy the configuration to get started.
+          </p>
+
+          <hr className="my-4" />
+
+          <Tabs defaultValue="claude" className="w-full">
+            <TabsList className="grid w-full grid-cols-4">
+              <TabsTrigger value="claude">Claude</TabsTrigger>
+              <TabsTrigger value="chatgpt">ChatGPT</TabsTrigger>
+              <TabsTrigger value="cursor">Cursor</TabsTrigger>
+              <TabsTrigger value="vscode">VS Code</TabsTrigger>
+            </TabsList>
+
+            <Typography className="text-sm max-w-full">
+              <TabsContent value="claude" className="space-y-3">
+                <ol>
+                  <li>
+                    Open Claude Desktop and click <strong>Settings</strong> in
+                    the lower corner
+                  </li>
+                  <li>
+                    Navigate to <strong>Developer</strong> tab →{" "}
+                    <strong>Edit Config</strong>
+                  </li>
+                  <li>
+                    <span>Add this configuration to </span>
+                    <InlineCode>claude_desktop_config.json</InlineCode>:
+                    <SyntaxHighlight
+                      showLanguageIndicator
+                      title="claude_desktop_config.json"
+                      language="json"
+                      code={claudeConfig}
+                      className="mt-2"
+                    />
+                  </li>
+                  <li>
+                    Save the file and restart Claude Desktop. Look for the 🔨
+                    icon in the bottom-right corner.
+                  </li>
+                </ol>
+                <p className="text-xs text-muted-foreground mt-2">
+                  macOS: ~/Library/Application
+                  Support/Claude/claude_desktop_config.json
+                  <br />
+                  Windows: %APPDATA%\Claude\claude_desktop_config.json
+                </p>
+                <a
+                  href="https://docs.mcp.run/mcp-clients/claude-desktop/"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1 text-sm text-primary hover:underline"
+                >
+                  View official docs
+                  <ExternalLinkIcon className="h-3 w-3" />
+                </a>
+              </TabsContent>
+
+              <TabsContent value="chatgpt" className="space-y-3">
+                <Callout type="note" title="Requirements">
+                  ChatGPT Pro, Team, Enterprise, or Edu subscription. Note: MCP
+                  support is limited to read-only operations through Deep
+                  Research.
+                </Callout>
+                <ol>
+                  <li>
+                    Go to <strong>Settings</strong> →{" "}
+                    <strong>Connectors</strong> → <strong>Connect</strong>
+                  </li>
+                  <li>
+                    Click <strong>Custom</strong> and add your MCP URL:
+                    <InlineCode className="ml-2">{chatgptConfig}</InlineCode>
+                  </li>
+                  <li>Provide a name and description for your connector</li>
+                  <li>
+                    Save and enable the connector. Users must authenticate with
+                    the connector before first use.
+                  </li>
+                  <li>Access through Deep Research in your chat interface</li>
+                </ol>
+
+                <a
+                  href="https://help.openai.com/en/articles/11487775-connectors-in-chatgpt"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1 text-sm text-primary hover:underline"
+                >
+                  View official docs
+                  <ExternalLinkIcon className="h-3 w-3" />
+                </a>
+              </TabsContent>
+
+              <TabsContent value="cursor" className="space-y-3">
+                <ol>
+                  <li>
+                    <span>Create or edit: </span>
+                    <InlineCode>~/.cursor/mcp.json</InlineCode>
+                    <span> (global) or </span>
+                    <InlineCode>.cursor/mcp.json</InlineCode>
+                    <span> (project)</span>
+                    <SyntaxHighlight
+                      showLanguageIndicator
+                      title="mcp.json"
+                      language="json"
+                      code={cursorConfig}
+                      className="mt-2"
+                    />
+                  </li>
+                  <li>Restart Cursor to apply the configuration</li>
+                </ol>
+                <a
+                  href="https://docs.cursor.com/en/context/mcp"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1 text-sm text-primary hover:underline"
+                >
+                  View official docs
+                  <ExternalLinkIcon className="h-3 w-3" />
+                </a>
+              </TabsContent>
+
+              <TabsContent value="vscode" className="space-y-3">
+                <Callout type="note" title="Requirements">
+                  VS Code with GitHub Copilot extension
+                </Callout>
+
+                <ol>
+                  <li>
+                    <span>Create </span>
+                    <InlineCode>.vscode/mcp.json</InlineCode>
+                    <span> in your workspace (or user-level mcp.json):</span>
+                    <SyntaxHighlight
+                      showLanguageIndicator
+                      title="mcp.json"
+                      language="json"
+                      code={vscodeConfig}
+                      className="mt-2"
+                    />
+                  </li>
+                  <li>Restart VS Code to apply the configuration</li>
+                  <li>
+                    Use MCP tools in GitHub Copilot Chat by selecting Agent mode
+                  </li>
+                </ol>
+                <a
+                  href="https://code.visualstudio.com/docs/copilot/chat/mcp-servers"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="inline-flex items-center gap-1 text-sm text-primary hover:underline"
+                >
+                  View official docs
+                  <ExternalLinkIcon className="h-3 w-3" />
+                </a>
+              </TabsContent>
+            </Typography>
+          </Tabs>
+        </div>
+      </div>
+    </Card>
+  );
+};

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

@@ -4,7 +4,7 @@ import { joinPath } from "../../util/joinPath.js";
 import type { GraphQLClient } from "./client/GraphQLClient.js";
 import { GraphQLProvider } from "./client/GraphQLContext.js";
 import { OasConfigProvider } from "./context.js";
-import { type OasPluginConfig } from "./interfaces.js";
+import type { OasPluginConfig } from "./interfaces.js";
 import { getVersions } from "./util/getRoutes.js";
 
 export const OasProvider = ({
@@ -25,6 +25,7 @@ export const OasProvider = ({
       config.type === "file"
         ? {
             type: config.type,
+            // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
             input: version ? config.input[version]! : firstVersion!,
           }
         : { type: config.type, input: config.input };

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

@@ -1,4 +1,3 @@
-import { type ResultOf } from "@graphql-typed-document-node/core";
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { Helmet } from "@zudoku/react-helmet-async";
 import { ChevronsDownUpIcon, ChevronsUpDownIcon } from "lucide-react";
@@ -16,16 +15,16 @@ import {
   SelectValue,
 } from "zudoku/ui/Select.js";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
+import { useApiIdentities } from "../../components/context/ZudokuContext.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
 import { Pagination } from "../../components/Pagination.js";
-import { useApiIdentities } from "../../components/context/ZudokuContext.js";
-import { Endpoint } from "./Endpoint.js";
-import { OperationListItem } from "./OperationListItem.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
+import { Endpoint } from "./Endpoint.js";
 import { graphql } from "./graphql/index.js";
 import { UNTAGGED_PATH } from "./index.js";
+import { OperationListItem } from "./OperationListItem.js";
 import { useSelectedServer } from "./state.js";
 import { sanitizeMarkdownForMetatag } from "./util/sanitizeMarkdownForMetatag.js";
 
@@ -40,6 +39,10 @@ export const OperationsFragment = graphql(/* GraphQL */ `
     path
     deprecated
     extensions
+    servers {
+      url
+      description
+    }
     parameters {
       name
       in
@@ -96,8 +99,6 @@ export const OperationsFragment = graphql(/* GraphQL */ `
   }
 `);
 
-export type OperationListItemResult = ResultOf<typeof OperationsFragment>;
-
 const SchemaWarmupQuery = graphql(/* GraphQL */ `
   query SchemaWarmup($input: JSON!, $type: SchemaType!) {
     schema(input: $input, type: $type) {
@@ -129,13 +130,16 @@ const OperationsForTagQuery = graphql(/* GraphQL */ `
           slug
           ...OperationsFragment
         }
+        extensions
         next {
           name
           slug
+          extensions
         }
         prev {
           name
           slug
+          extensions
         }
       }
     }
@@ -161,7 +165,10 @@ export const OperationList = ({
   const {
     data: { schema },
   } = result;
-  const { selectedServer } = useSelectedServer(schema.servers);
+  // Global server selection for the dropdown UI
+  const { selectedServer: globalSelectedServer } = useSelectedServer(
+    schema.servers,
+  );
   const title = schema.title;
   const summary = schema.summary;
   const description = schema.description;
@@ -193,6 +200,10 @@ export const OperationList = ({
 
   const { operations, next, prev, description: tagDescription } = schema.tag;
 
+  // Simple heuristic to determine if we should lazy highlight the code
+  // This is to avoid the performance issues when there are a lot of operations
+  const shouldLazyHighlight = operations.length > 30;
+
   // The summary property is preferable here as it is a short description of
   // the API, whereas the description property is typically longer and supports
   // commonmark formatting, making it ill-suited for use in the meta description
@@ -211,16 +222,25 @@ export const OperationList = ({
     (hasMultipleVersions && options?.showVersionSelect !== "hide");
 
   const paginationProps = {
-    prev: prev?.name ? { to: `../${prev.slug}`, label: prev.name } : undefined,
+    prev: prev
+      ? {
+          to: `../${prev.slug}`,
+          label: prev.extensions?.["x-displayName"] ?? prev.name,
+        }
+      : undefined,
     next: next
       ? {
           to: `../${next.slug ?? UNTAGGED_PATH}`,
-          label: next.name ?? "Other endpoints",
+          label:
+            next.extensions?.["x-displayName"] ??
+            next.name ??
+            "Other endpoints",
         }
       : undefined,
   };
 
-  const helmetTitle = [schema.tag.name, title].filter(Boolean).join(" - ");
+  const tagTitle = schema.tag.extensions?.["x-displayName"] ?? schema.tag.name;
+  const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
 
   return (
     <div
@@ -234,8 +254,12 @@ export const OperationList = ({
           <meta name="description" content={metaDescription} />
         )}
       </Helmet>
+
       <div className="mb-8">
-        <Collapsible className="w-full">
+        <Collapsible
+          className="w-full"
+          defaultOpen={options?.expandApiInformation}
+        >
           <div className="flex flex-col gap-y-4 sm:flex-row justify-around items-start sm:items-end">
             <div className="flex flex-col flex-1 gap-2">
               <CategoryHeading>{title}</CategoryHeading>
@@ -245,7 +269,7 @@ export const OperationList = ({
                 registerNavigationAnchor
                 className="mb-0"
               >
-                {schema.tag.name ?? "Documentation"}
+                {tagTitle}
                 {showVersions && (
                   <span className="text-xl text-muted-foreground ms-1.5">
                     {" "}
@@ -258,6 +282,7 @@ export const OperationList = ({
             <div className="flex flex-col gap-4 sm:items-end">
               {showVersions && (
                 <Select
+                  // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
                   onValueChange={(version) => navigate(versions[version]!)}
                   defaultValue={version}
                   disabled={!hasMultipleVersions}
@@ -314,8 +339,9 @@ export const OperationList = ({
         {operations.map((fragment) => (
           <div key={fragment.slug}>
             <OperationListItem
-              serverUrl={selectedServer}
               operationFragment={fragment}
+              globalSelectedServer={globalSelectedServer}
+              shouldLazyHighlight={shouldLazyHighlight}
             />
             <hr className="my-10" />
           </div>

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

@@ -6,13 +6,14 @@ import { Markdown } from "../../components/Markdown.js";
 import { cn } from "../../util/cn.js";
 import { groupBy } from "../../util/groupBy.js";
 import { renderIf } from "../../util/renderIf.js";
-import { OperationsFragment } from "./OperationList.js";
-import { ParameterList } from "./ParameterList.js";
-import { Sidecar } from "./Sidecar.js";
 import { ResponseContent } from "./components/ResponseContent.js";
 import { SelectOnClick } from "./components/SelectOnClick.js";
 import { useOasConfig } from "./context.js";
 import { type FragmentType, useFragment } from "./graphql/index.js";
+import { MCPEndpoint } from "./MCPEndpoint.js";
+import { OperationsFragment } from "./OperationList.js";
+import { ParameterList } from "./ParameterList.js";
+import { Sidecar } from "./Sidecar.js";
 import { SchemaView } from "./schema/SchemaView.js";
 import { methodForColor } from "./util/methodToColor.js";
 
@@ -21,10 +22,12 @@ export type ParameterGroup = (typeof PARAM_GROUPS)[number];
 
 export const OperationListItem = ({
   operationFragment,
-  serverUrl,
+  globalSelectedServer,
+  shouldLazyHighlight,
 }: {
   operationFragment: FragmentType<typeof OperationsFragment>;
-  serverUrl?: string;
+  globalSelectedServer?: string;
+  shouldLazyHighlight?: boolean;
 }) => {
   const operation = useFragment(OperationsFragment, operationFragment);
   const groupedParameters = groupBy(
@@ -33,8 +36,13 @@ export const OperationListItem = ({
   );
   const { options } = useOasConfig();
 
+  // Manual server selection takes precedence over the server hierarchy.
+  // If no manual selection, fall back to operation's first server (already respects operation > path > global hierarchy)
+  const displayServerUrl = globalSelectedServer || operation.servers.at(0)?.url;
+
   const first = operation.responses.at(0);
   const [selectedResponse, setSelectedResponse] = useState(first?.statusCode);
+  const isMCPEndpoint = operation.extensions?.["x-mcp-server"] !== undefined;
 
   return (
     <div>
@@ -58,37 +66,48 @@ export const OperationListItem = ({
         >
           {operation.summary}
         </Heading>
-        <div className="text-sm flex gap-2 font-mono col-span-full">
-          <span className={methodForColor(operation.method)}>
-            {operation.method.toUpperCase()}
-          </span>
-          <SelectOnClick className="max-w-full truncate flex cursor-pointer">
-            {serverUrl && (
-              <div className="text-neutral-400 dark:text-neutral-500 truncate">
-                {serverUrl.replace(/\/$/, "")}
+        {!isMCPEndpoint && (
+          <div className="text-sm flex gap-2 font-mono col-span-full">
+            <span className={methodForColor(operation.method)}>
+              {operation.method.toUpperCase()}
+            </span>
+            <SelectOnClick className="max-w-full truncate flex cursor-pointer">
+              {displayServerUrl && (
+                <div className="text-neutral-400 dark:text-neutral-500 truncate">
+                  {displayServerUrl.replace(/\/$/, "")}
+                </div>
+              )}
+              <div className="text-neutral-900 dark:text-neutral-200">
+                {operation.path}
               </div>
-            )}
-            <div className="text-neutral-900 dark:text-neutral-200">
-              {operation.path}
-            </div>
-          </SelectOnClick>
-        </div>
+            </SelectOnClick>
+          </div>
+        )}
 
-        <div
-          className={cn(
-            "flex flex-col gap-4",
-            options?.disableSidecar && "col-span-full",
-          )}
-        >
-          {operation.description && (
-            <Markdown
-              className="max-w-full prose-img:max-w-prose"
-              content={operation.description}
+        {isMCPEndpoint ? (
+          <div className="col-span-full">
+            <MCPEndpoint
+              serverUrl={displayServerUrl}
+              summary={operation.summary ?? undefined}
+              data={operation.extensions?.["x-mcp-server"]}
             />
-          )}
-          {operation.parameters && operation.parameters.length > 0 && (
-            <>
-              {PARAM_GROUPS.flatMap((group) =>
+          </div>
+        ) : (
+          <div
+            className={cn(
+              "flex flex-col gap-4",
+              options?.disableSidecar && "col-span-full",
+            )}
+          >
+            {operation.description && (
+              <Markdown
+                className="max-w-full prose-img:max-w-prose"
+                content={operation.description}
+              />
+            )}
+            {operation.parameters &&
+              operation.parameters.length > 0 &&
+              PARAM_GROUPS.flatMap((group) =>
                 groupedParameters[group]?.length ? (
                   <ParameterList
                     key={group}
@@ -101,54 +120,62 @@ export const OperationListItem = ({
                   []
                 ),
               )}
-            </>
-          )}
-          {renderIf(operation.requestBody?.content?.at(0)?.schema, (schema) => (
-            <div className="mt-4 flex flex-col gap-4">
-              <Heading
-                level={3}
-                className="capitalize flex items-center gap-2"
-                id={`${operation.slug}/request-body`}
-              >
-                {operation.summary && (
-                  <VisuallyHidden>{operation.summary} &rsaquo; </VisuallyHidden>
-                )}
-                Request Body{" "}
-                {operation.requestBody?.required === false ? (
-                  <Badge variant="muted">optional</Badge>
-                ) : (
-                  ""
-                )}
-              </Heading>
-              <SchemaView schema={schema} />
-            </div>
-          ))}
-          {operation.responses.length > 0 && (
-            <>
-              <Heading
-                level={3}
-                className="capitalize mt-8 pt-8 border-t"
-                id={`${operation.slug}/responses`}
-              >
-                {operation.summary && (
-                  <VisuallyHidden>{operation.summary} &rsaquo; </VisuallyHidden>
-                )}
-                Responses
-              </Heading>
-              <ResponseContent
-                responses={operation.responses}
-                selectedResponse={selectedResponse}
-                onSelectResponse={setSelectedResponse}
-              />
-            </>
-          )}
-        </div>
+            {renderIf(
+              operation.requestBody?.content?.at(0)?.schema,
+              (schema) => (
+                <div className="mt-4 flex flex-col gap-4">
+                  <Heading
+                    level={3}
+                    className="capitalize flex items-center gap-2"
+                    id={`${operation.slug}/request-body`}
+                  >
+                    {operation.summary && (
+                      <VisuallyHidden>
+                        {operation.summary} &rsaquo;{" "}
+                      </VisuallyHidden>
+                    )}
+                    Request Body{" "}
+                    {operation.requestBody?.required === false ? (
+                      <Badge variant="muted">optional</Badge>
+                    ) : (
+                      ""
+                    )}
+                  </Heading>
+                  <SchemaView schema={schema} />
+                </div>
+              ),
+            )}
+            {operation.responses.length > 0 && (
+              <>
+                <Heading
+                  level={3}
+                  className="capitalize mt-8 pt-8 border-t"
+                  id={`${operation.slug}/responses`}
+                >
+                  {operation.summary && (
+                    <VisuallyHidden>
+                      {operation.summary} &rsaquo;{" "}
+                    </VisuallyHidden>
+                  )}
+                  Responses
+                </Heading>
+                <ResponseContent
+                  responses={operation.responses}
+                  selectedResponse={selectedResponse}
+                  onSelectResponse={setSelectedResponse}
+                />
+              </>
+            )}
+          </div>
+        )}
 
-        {renderIf(!options?.disableSidecar, () => (
+        {renderIf(!options?.disableSidecar && !isMCPEndpoint, () => (
           <Sidecar
             selectedResponse={selectedResponse}
             onSelectResponse={setSelectedResponse}
             operation={operation}
+            globalSelectedServer={globalSelectedServer}
+            shouldLazyHighlight={shouldLazyHighlight}
           />
         ))}
       </div>