zudoku 0.0.0-fdfe742 → 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,17 +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, ProseClasses } from "../../components/Markdown.js";
+import { Markdown } from "../../components/Markdown.js";
 import { Pagination } from "../../components/Pagination.js";
-import { useApiIdentities } from "../../components/context/ZudokuContext.js";
-import { cn } from "../../util/cn.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";
 
@@ -41,6 +39,10 @@ export const OperationsFragment = graphql(/* GraphQL */ `
     path
     deprecated
     extensions
+    servers {
+      url
+      description
+    }
     parameters {
       name
       in
@@ -97,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) {
@@ -130,13 +130,16 @@ const OperationsForTagQuery = graphql(/* GraphQL */ `
           slug
           ...OperationsFragment
         }
+        extensions
         next {
           name
           slug
+          extensions
         }
         prev {
           name
           slug
+          extensions
         }
       }
     }
@@ -162,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;
@@ -194,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
@@ -212,15 +222,26 @@ 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 tagTitle = schema.tag.extensions?.["x-displayName"] ?? schema.tag.name;
+  const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
+
   return (
     <div
       className="pt-(--padding-content-top)"
@@ -228,23 +249,27 @@ export const OperationList = ({
       data-pagefind-meta="section:openapi"
     >
       <Helmet>
-        <title>{[schema.tag.name, title].filter(Boolean).join(" - ")}</title>
+        {helmetTitle && <title>{helmetTitle}</title>}
         {metaDescription && (
           <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>
               <Heading
                 level={1}
                 id="description"
-                registerSidebarAnchor
+                registerNavigationAnchor
                 className="mb-0"
               >
-                {schema.tag.name ?? "Other endpoints"}
+                {tagTitle}
                 {showVersions && (
                   <span className="text-xl text-muted-foreground ms-1.5">
                     {" "}
@@ -257,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}
@@ -291,14 +317,9 @@ export const OperationList = ({
           </div>
           {schema.description && (
             <CollapsibleContent className="CollapsibleContent">
-              <div
-                className={cn(
-                  ProseClasses,
-                  "pt-4 max-w-full prose-img:max-w-prose",
-                )}
-              >
+              <div className="mt-4 max-w-full border rounded-sm bg-muted/25">
                 <Markdown
-                  className="border rounded-sm bg-muted/25 border-border px-2.5 md:px-4"
+                  className="max-w-full prose-img:max-w-prose border-border p-3 lg:p-5"
                   content={schema.description}
                 />
               </div>
@@ -306,14 +327,10 @@ export const OperationList = ({
           )}
         </Collapsible>
         {tagDescription && (
-          <div
-            className={cn(
-              ProseClasses,
-              "my-4 max-w-full prose-img:max-w-prose",
-            )}
-          >
-            <Markdown content={tagDescription} />
-          </div>
+          <Markdown
+            className="my-4 max-w-full prose-img:max-w-prose"
+            content={tagDescription}
+          />
         )}
       </div>
       <hr />
@@ -322,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>