@mehdad67/apitogo 0.1.24

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

@@ -0,0 +1,74 @@
+import { useMemo } from "react";
+import { Outlet } from "react-router";
+import { joinUrl } from "../../util/joinUrl.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 { getVersionMetadata } from "./util/getRoutes.js";
+
+export const OasProvider = ({
+  basePath,
+  version,
+  config,
+  client,
+}: {
+  basePath: string;
+  version?: string;
+  config: OasPluginConfig;
+  client: GraphQLClient;
+}) => {
+  const value = useMemo(() => {
+    const { versions: availableVersions, versionMap } =
+      getVersionMetadata(config);
+    const currentVersion = version ?? availableVersions.at(0);
+
+    const versions = Object.fromEntries(
+      availableVersions.map((id) => {
+        const meta = versionMap[id];
+        return [
+          id,
+          {
+            path: joinUrl(basePath, id),
+            label: meta?.label ?? id,
+            downloadUrl: meta?.downloadUrl,
+            tagPages: meta?.tagPages,
+          },
+        ];
+      }),
+    );
+
+    const resolveInput = (): string | (() => Promise<unknown>) => {
+      if (!Array.isArray(config.input)) {
+        return config.input;
+      }
+
+      const versionConfig = currentVersion
+        ? config.input.find((v) => v.path === currentVersion)
+        : config.input[0];
+
+      if (!versionConfig) {
+        throw new Error(`No input found for version: ${currentVersion}`);
+      }
+
+      return versionConfig.input;
+    };
+
+    return {
+      config: {
+        ...config,
+        version: currentVersion,
+        versions,
+        input: resolveInput(),
+      },
+    };
+  }, [config, basePath, version]);
+
+  return (
+    <OasConfigProvider value={value}>
+      <GraphQLProvider client={client}>
+        <Outlet />
+      </GraphQLProvider>
+    </OasConfigProvider>
+  );
+};

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

@@ -0,0 +1,275 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { Navigate, useParams } from "react-router";
+import { useApiIdentities } from "../../components/context/ZudokuContext.js";
+import { Markdown } from "../../components/Markdown.js";
+import { usePrevNext } from "../../components/navigation/utils.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
+import { Pagination } from "../../components/Pagination.js";
+import { ApiHeader } from "./ApiHeader.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";
+import { useWarmupSchema } from "./util/useWarmupSchema.js";
+
+export const OperationsFragment = graphql(/* GraphQL */ `
+  fragment OperationsFragment on OperationItem {
+    slug
+    summary
+    method
+    description
+    operationId
+    contentTypes
+    path
+    deprecated
+    extensions
+    servers {
+      url
+      description
+    }
+    parameters {
+      name
+      in
+      description
+      required
+      schema
+      style
+      explode
+      allowReserved
+      examples {
+        name
+        description
+        externalValue
+        value
+        summary
+      }
+    }
+    requestBody {
+      content {
+        mediaType
+        encoding {
+          name
+        }
+        examples {
+          name
+          description
+          externalValue
+          value
+          summary
+        }
+        schema
+      }
+      description
+      required
+    }
+    responses {
+      statusCode
+      links
+      description
+      content {
+        examples {
+          name
+          description
+          externalValue
+          value
+          summary
+        }
+        mediaType
+        encoding {
+          name
+        }
+        schema
+      }
+    }
+  }
+`);
+
+const OperationsForTagQuery = graphql(/* GraphQL */ `
+  query OperationsForTag(
+    $input: JSON!
+    $type: SchemaType!
+    $tag: String
+    $untagged: Boolean
+  ) {
+    schema(input: $input, type: $type) {
+      servers {
+        url
+      }
+      description
+      summary
+      title
+      url
+      version
+      tag(slug: $tag, untagged: $untagged) {
+        name
+        description
+        operations {
+          slug
+          ...OperationsFragment
+        }
+        extensions
+        next {
+          name
+          slug
+          extensions
+        }
+        prev {
+          name
+          slug
+          extensions
+        }
+      }
+    }
+  }
+`);
+
+const LAZY_OPERATION_LIST_THRESHOLD = 30;
+
+export const OperationList = ({
+  tag,
+  untagged,
+}: {
+  tag?: string;
+  untagged?: boolean;
+}) => {
+  const { input, type } = useOasConfig();
+  const { tag: tagFromParams } = useParams<"tag">();
+  const query = useCreateQuery(OperationsForTagQuery, {
+    input,
+    type,
+    tag: tag ?? tagFromParams,
+    untagged,
+  });
+  const schema = useSuspenseQuery(query).data.schema;
+  const { selectedServer: globalSelectedServer } = useSelectedServer(
+    schema.servers,
+  );
+  const title = schema.title;
+  const summary = schema.summary;
+  const description = schema.description;
+  const { prev: navPrev, next: navNext } = usePrevNext();
+
+  useWarmupSchema();
+
+  // Prefetch for Playground
+  useApiIdentities();
+
+  if (!schema.tag) {
+    // Route targets a tag or untagged ops that don't exist in this version
+    if (tag || tagFromParams || untagged) {
+      return <Navigate to=".." replace />;
+    }
+
+    return (
+      <div
+        className="flex flex-col h-full items-center justify-center text-center"
+        data-pagefind-ignore="all"
+      >
+        <div className="text-muted-foreground font-medium">
+          No operations found
+        </div>
+        <div className="mt-2 text-sm text-muted-foreground">
+          This API doesn't have any operations defined yet.
+        </div>
+      </div>
+    );
+  }
+
+  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 > LAZY_OPERATION_LIST_THRESHOLD;
+
+  // 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
+  const metaDescription = tagDescription
+    ? sanitizeMarkdownForMetatag(tagDescription)
+    : summary
+      ? summary
+      : description
+        ? sanitizeMarkdownForMetatag(description)
+        : undefined;
+
+  const paginationProps = {
+    prev: prev
+      ? {
+          to: `../${prev.slug}`,
+          label: prev.extensions?.["x-displayName"] ?? prev.name,
+        }
+      : navPrev
+        ? { to: navPrev.id, label: navPrev.label }
+        : undefined,
+    next: next
+      ? {
+          to: `../${next.slug ?? UNTAGGED_PATH}`,
+          label:
+            next.extensions?.["x-displayName"] ??
+            next.name ??
+            "Other endpoints",
+        }
+      : navNext
+        ? { to: navNext.id, label: navNext.label }
+        : undefined,
+  };
+
+  const tagTitle = untagged
+    ? "Other endpoints"
+    : (schema.tag.extensions?.["x-displayName"] ?? schema.tag.name);
+
+  const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
+
+  return (
+    <div
+      className="pt-(--padding-content-top)"
+      data-pagefind-filter="section:openapi"
+      data-pagefind-meta="section:openapi"
+    >
+      <PagefindSearchMeta name="category">{title}</PagefindSearchMeta>
+      <Helmet>
+        {helmetTitle && <title>{helmetTitle}</title>}
+        {metaDescription && (
+          <meta name="description" content={metaDescription} />
+        )}
+      </Helmet>
+
+      <div className="mb-8">
+        <ApiHeader
+          title={title}
+          heading={tagTitle}
+          headingId="description"
+          tag={tag ?? tagFromParams}
+        >
+          <Endpoint />
+        </ApiHeader>
+        {tagDescription && (
+          <Markdown
+            className="my-4 max-w-full prose-img:max-w-prose"
+            content={tagDescription}
+          />
+        )}
+      </div>
+      <hr />
+      {/* px, -mx is so that `content-visibility` doesn't cut off overflown heading anchor links '#' */}
+      <div className="px-6 mt-6 -mx-6 [content-visibility:auto]">
+        {operations.map((fragment) => (
+          <div key={fragment.slug}>
+            <OperationListItem
+              operationFragment={fragment}
+              globalSelectedServer={globalSelectedServer}
+              shouldLazyHighlight={shouldLazyHighlight}
+            />
+            <hr className="my-10" />
+          </div>
+        ))}
+        <Pagination className="mb-4" {...paginationProps} />
+      </div>
+    </div>
+  );
+};