@redocly/theme 0.69.0-next.1 → 0.69.0-next.3

package/lib/markdoc/tags/connect-mcp.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.connectMcp = void 0;
+const constants_1 = require("../../core/constants");
 exports.connectMcp = {
     schema: {
         render: 'ConnectMCP',
@@ -17,7 +18,7 @@ exports.connectMcp = {
             },
             options: {
                 type: Array,
-                default: ['cursor', 'vscode', 'copy'],
+                default: constants_1.DEFAULT_MCP_OPTIONS,
             },
         },
         selfClosing: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redocly/theme",
-  "version": "0.69.0-next.1",
+  "version": "0.69.0-next.3",
   "description": "Shared UI components lib",
   "keywords": [
     "theme",
@@ -68,7 +68,7 @@
     "vitest": "4.1.10",
     "vitest-when": "0.6.2",
     "webpack": "5.105.2",
-    "@redocly/realm-asyncapi-sdk": "0.15.0-next.0"
+    "@redocly/realm-asyncapi-sdk": "0.15.0-next.2"
   },
   "dependencies": {
     "@tanstack/react-query": "5.62.3",

package/src/components/Badge/Badge.tsx

@@ -11,9 +11,18 @@ export type BadgeProps = PropsWithChildren<{
   key?: string;
   className?: string;
   icon?: string;
+  /** Inline SVG content for the icon */
+  iconRawContent?: string;
 }>;
 
-export function Badge({ icon, children, deprecated, color, ...props }: BadgeProps): JSX.Element {
+export function Badge({
+  icon,
+  iconRawContent,
+  children,
+  deprecated,
+  color,
+  ...props
+}: BadgeProps): JSX.Element {
   return (
     <BadgeComponent
       {...props}
@@ -21,7 +30,7 @@ export function Badge({ icon, children, deprecated, color, ...props }: BadgeProp
       $deprecated={deprecated}
       data-component-name="Badge/Badge"
     >
-      {icon ? <BadgeIcon icon={icon} /> : null}
+      {icon || iconRawContent ? <BadgeIcon icon={icon} rawContent={iconRawContent} /> : null}
       {children}
     </BadgeComponent>
   );
@@ -54,4 +63,9 @@ const BadgeIcon = styled(GenericIcon)`
   margin-right: var(--spacing-xxs);
   flex-shrink: 0;
   vertical-align: middle;
+
+  /* For inline SVG to align properly */
+  svg {
+    display: block;
+  }
 `;

package/src/components/Buttons/ConnectMCPButton.tsx

@@ -9,11 +9,14 @@ import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMen
 import { Button } from '@redocly/theme/components/Button/Button';
 import { CursorIcon } from '@redocly/theme/icons/CursorIcon/CursorIcon';
 import { VSCodeIcon } from '@redocly/theme/icons/VSCodeIcon/VSCodeIcon';
+import { ClaudeIcon } from '@redocly/theme/icons/ClaudeIcon/ClaudeIcon';
+import { CodexIcon } from '@redocly/theme/icons/CodexIcon/CodexIcon';
 import { CopyIcon } from '@redocly/theme/icons/CopyIcon/CopyIcon';
 import { CheckmarkFilledIcon } from '@redocly/theme/icons/CheckmarkFilledIcon/CheckmarkFilledIcon';
 import { ChevronDownIcon } from '@redocly/theme/icons/ChevronDownIcon/ChevronDownIcon';
 import { ChevronUpIcon } from '@redocly/theme/icons/ChevronUpIcon/ChevronUpIcon';
 import { useConnectMCPButton, useOutsideClick, useThemeHooks } from '@redocly/theme/core/hooks';
+import { DEFAULT_MCP_OPTIONS } from '@redocly/theme/core/constants';
 
 type MenuOption = {
   key: MCPOption;
@@ -41,6 +44,22 @@ const MENU_OPTIONS: MenuOption[] = [
     descriptionTranslationKey: 'page.actions.connectMcp.vscodeDescription',
     descriptionDefault: 'Install MCP server on VS Code',
   },
+  {
+    key: 'claude-code',
+    icon: ClaudeIcon,
+    titleTranslationKey: 'page.actions.connectMcp.claudeCode',
+    titleDefault: 'Connect to Claude Code',
+    descriptionTranslationKey: 'page.actions.connectMcp.claudeCodeDescription',
+    descriptionDefault: 'Copy the Claude Code CLI command',
+  },
+  {
+    key: 'codex',
+    icon: CodexIcon,
+    titleTranslationKey: 'page.actions.connectMcp.codex',
+    titleDefault: 'Connect to Codex CLI',
+    descriptionTranslationKey: 'page.actions.connectMcp.codexDescription',
+    descriptionDefault: 'Copy the Codex CLI command',
+  },
   {
     key: 'copy',
     icon: CopyIcon,
@@ -51,6 +70,9 @@ const MENU_OPTIONS: MenuOption[] = [
   },
 ];
 
+// Copy actions keep the dropdown open so the copied checkmark is visible.
+const COPY_OPTIONS: MCPOption[] = ['claude-code', 'codex', 'copy'];
+
 export type ConnectMCPButtonProps = {
   placement?: 'top' | 'bottom';
   alignment?: 'start' | 'end';
@@ -60,14 +82,14 @@ export type ConnectMCPButtonProps = {
 export function ConnectMCPButton({
   placement = 'bottom',
   alignment = 'end',
-  options = ['cursor', 'vscode', 'copy'],
+  options = DEFAULT_MCP_OPTIONS,
 }: ConnectMCPButtonProps): JSX.Element | null {
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
   const [isOpen, setIsOpen] = useState(false);
   const wrapperRef = useRef<HTMLDivElement>(null);
 
-  const { isCopied, visibleOptions, handleAction } = useConnectMCPButton({ options });
+  const { copiedOption, visibleOptions, handleAction } = useConnectMCPButton({ options });
 
   useOutsideClick(wrapperRef, () => setIsOpen(false));
 
@@ -78,13 +100,13 @@ export function ConnectMCPButton({
   if (!primaryOption) return null;
 
   const PrimaryIcon = primaryOption.icon;
-  // When copy is the primary action there is no dropdown item to show the copied state, so the
-  // primary button itself must reflect it.
-  const showPrimaryCopied = primaryOption.key === 'copy' && isCopied;
+  const showPrimaryCopied = copiedOption === primaryOption.key;
 
   const handleMenuAction = (key: MCPOption) => {
     handleAction(key);
-    setIsOpen(false);
+    if (!COPY_OPTIONS.includes(key)) {
+      setIsOpen(false);
+    }
   };
 
   return (
@@ -121,7 +143,7 @@ export function ConnectMCPButton({
           <DropdownMenu>
             {dropdownOptions.map((option) => {
               const Icon = option.icon;
-              const showCheckmark = option.key === 'copy' && isCopied;
+              const showCheckmark = copiedOption === option.key;
 
               return (
                 <DropdownMenuItem key={option.key} onAction={() => handleMenuAction(option.key)}>
@@ -162,17 +184,25 @@ const SplitButtonGroup = styled.div`
   align-items: stretch;
 `;
 
+/* Doubled selectors outrank the base button class in any style injection order,
+   and margin: 0 keeps themed button margins from splitting the group apart. */
 const PrimaryButton = styled(Button)`
-  --button-gap: var(--connect-mcp-button-gap);
-  border-top-right-radius: 0;
-  border-bottom-right-radius: 0;
+  && {
+    --button-gap: var(--connect-mcp-button-gap);
+    margin: 0;
+    border-top-right-radius: 0;
+    border-bottom-right-radius: 0;
+  }
 `;
 
 const ChevronButton = styled(Button)`
-  border-top-left-radius: 0;
-  border-bottom-left-radius: 0;
-  border-left: none;
-  padding-inline: var(--connect-mcp-button-chevron-padding-inline);
+  && {
+    margin: 0;
+    border-top-left-radius: 0;
+    border-bottom-left-radius: 0;
+    border-left: none;
+    padding-inline: var(--connect-mcp-button-chevron-padding-inline);
+  }
 `;
 
 const DropdownWrapper = styled.div<{ $placement?: string; $alignment?: string }>`

package/src/components/MCP/McpConnectionTabs.tsx

@@ -0,0 +1,263 @@
+import React, { useEffect, useState } from 'react';
+import styled from 'styled-components';
+
+import type { JSX, ReactNode } from 'react';
+import type { TFunction } from '@redocly/theme/core/types';
+
+import { useMCPConfig, useThemeHooks } from '@redocly/theme/core/hooks';
+import {
+  generateClaudeCodeCommand,
+  generateClaudeDesktopConfig,
+  generateCodexCommand,
+  generateMcpInstallPrompt,
+} from '@redocly/theme/core/utils';
+import { CodeBlock } from '@redocly/theme/components/CodeBlock/CodeBlock';
+import { ClaudeIcon } from '@redocly/theme/icons/ClaudeIcon/ClaudeIcon';
+import { ChatGptIcon } from '@redocly/theme/icons/ChatGptIcon/ChatGptIcon';
+import { Tabs, TabsSize } from '@redocly/theme/markdoc/components/Tabs/Tabs';
+import { TabItemFragment } from '@redocly/theme/markdoc/components/Tabs/TabItemFragment';
+import { NumberedList } from '@redocly/theme/markdoc/components/NumberedList/NumberedList';
+import { NumberedItem } from '@redocly/theme/markdoc/components/NumberedList/NumberedItem';
+
+export type McpConnectionTab = 'claude' | 'chatgpt' | 'json';
+
+export type McpConnectionTabsProps = {
+  options?: McpConnectionTab[];
+  className?: string;
+};
+
+const DEFAULT_TAB_OPTIONS: McpConnectionTab[] = ['claude', 'chatgpt', 'json'];
+
+const TAB_LABELS: Record<
+  McpConnectionTab,
+  { translationKey: string; defaultLabel: string; icon?: React.ComponentType }
+> = {
+  claude: {
+    translationKey: 'page.mcpNotAllowed.tabs.claude',
+    defaultLabel: 'Claude',
+    icon: ClaudeIcon,
+  },
+  chatgpt: {
+    translationKey: 'page.mcpNotAllowed.tabs.chatgpt',
+    defaultLabel: 'ChatGPT',
+    icon: ChatGptIcon,
+  },
+  json: { translationKey: 'page.mcpNotAllowed.tabs.json', defaultLabel: 'JSON' },
+};
+
+type TabClient = { headline: string; content: ReactNode };
+
+// The report control is docs feedback, not useful on the connection page.
+const CODE_BLOCK_HEADER = { controls: { copy: {}, report: { hidden: true } } };
+
+export function McpConnectionTabs({
+  options = DEFAULT_TAB_OPTIONS,
+  className,
+}: McpConnectionTabsProps): JSX.Element | null {
+  const { useTranslate } = useThemeHooks();
+  const { translate } = useTranslate();
+  const { serverName, serverUrl, isMcpDisabled } = useMCPConfig();
+  // The SSR markup of error pages is cached with the build-time origin, so the
+  // tabs remount after hydration to pick up the real browser origin.
+  const [hydrated, setHydrated] = useState(false);
+
+  useEffect(() => setHydrated(true), []);
+
+  if (isMcpDisabled) {
+    return null;
+  }
+
+  const connection = { serverName, url: serverUrl };
+
+  return (
+    <McpConnectionTabsWrapper
+      key={hydrated ? 'client' : 'ssr'}
+      data-component-name="MCP/McpConnectionTabs"
+      data-testid="mcp-connection-tabs"
+      className={className}
+    >
+      <Tabs size={TabsSize.SMALL}>
+        {options.map((option) => {
+          const { translationKey, defaultLabel, icon: TabIcon } = TAB_LABELS[option];
+
+          return (
+            <TabItemFragment
+              key={option}
+              label={translate(translationKey, defaultLabel)}
+              icon={TabIcon ? <TabIcon /> : undefined}
+            >
+              {renderTabContent(option, connection, translate)}
+            </TabItemFragment>
+          );
+        })}
+      </Tabs>
+    </McpConnectionTabsWrapper>
+  );
+}
+
+function renderTabContent(
+  option: McpConnectionTab,
+  connection: { serverName: string; url: string },
+  translate: TFunction,
+): ReactNode {
+  const terminalHint = (
+    <TabHint>
+      {translate('page.mcpNotAllowed.snippets.terminal.hint', 'Run this command in your terminal:')}
+    </TabHint>
+  );
+
+  const urlBlock = <CodeBlock lang="text" source={connection.url} header={CODE_BLOCK_HEADER} />;
+
+  const assistantPromptClient: TabClient = {
+    headline: translate('page.mcpNotAllowed.snippets.prompt.headline', 'Prompt'),
+    content: (
+      <>
+        <TabHint>
+          {translate(
+            'page.mcpNotAllowed.snippets.prompt.hint',
+            'Or paste this prompt into the chat to have it add the server for you:',
+          )}
+        </TabHint>
+        <CodeBlock
+          lang="text"
+          source={generateMcpInstallPrompt(connection)}
+          header={CODE_BLOCK_HEADER}
+          wrapContents
+        />
+      </>
+    ),
+  };
+
+  switch (option) {
+    case 'claude':
+      return renderClientList([
+        {
+          headline: translate('page.mcpNotAllowed.snippets.claudeCode.headline', 'Claude Code'),
+          content: (
+            <>
+              {terminalHint}
+              <CodeBlock
+                lang="shell"
+                source={generateClaudeCodeCommand(connection)}
+                header={CODE_BLOCK_HEADER}
+                wrapContents
+              />
+            </>
+          ),
+        },
+        {
+          headline: translate(
+            'page.mcpNotAllowed.snippets.claudeDesktop.headline',
+            'Claude Desktop',
+          ),
+          content: (
+            <>
+              <TabHint>
+                {translate(
+                  'page.mcpNotAllowed.snippets.claudeDesktop.instruction',
+                  'In Claude Desktop, open Settings → Developer → Edit Config, add this to the configuration file, and restart Claude Desktop:',
+                )}
+              </TabHint>
+              <CodeBlock
+                lang="json"
+                source={generateClaudeDesktopConfig(connection)}
+                header={CODE_BLOCK_HEADER}
+              />
+            </>
+          ),
+        },
+      ]);
+    case 'chatgpt':
+      return renderClientList([
+        {
+          headline: translate('page.mcpNotAllowed.snippets.codexCli.headline', 'Codex CLI'),
+          content: (
+            <>
+              {terminalHint}
+              <CodeBlock
+                lang="shell"
+                source={generateCodexCommand(connection)}
+                header={CODE_BLOCK_HEADER}
+                wrapContents
+              />
+            </>
+          ),
+        },
+        {
+          headline: translate(
+            'page.mcpNotAllowed.snippets.chatgptApp.headline',
+            'ChatGPT desktop app',
+          ),
+          content: (
+            <>
+              <TabHint>
+                {translate(
+                  'page.mcpNotAllowed.snippets.chatgptApp.instruction',
+                  'In the ChatGPT desktop app, go to Settings → Plugins → MCPs and add a server with the "Streamable HTTP" type and this URL (restart the app afterwards):',
+                )}
+              </TabHint>
+              {urlBlock}
+            </>
+          ),
+        },
+        assistantPromptClient,
+      ]);
+    case 'json':
+      return (
+        <>
+          <TabHint>
+            {translate(
+              'page.mcpNotAllowed.snippets.json.hint',
+              'Add this server entry to your MCP client configuration file:',
+            )}
+          </TabHint>
+          <CodeBlock
+            lang="json"
+            source={JSON.stringify(
+              { [connection.serverName]: { url: connection.url, description: 'MCP Server' } },
+              null,
+              2,
+            )}
+            header={CODE_BLOCK_HEADER}
+          />
+        </>
+      );
+  }
+}
+
+function renderClientList(clients: TabClient[]): ReactNode {
+  return (
+    <NumberedList>
+      {clients.map((client, index) => (
+        <NumberedItem
+          key={index}
+          type="dot"
+          size="small"
+          headline={client.headline}
+          index={index + 1}
+          isLast={index === clients.length - 1}
+        >
+          {client.content}
+        </NumberedItem>
+      ))}
+    </NumberedList>
+  );
+}
+
+const McpConnectionTabsWrapper = styled.div`
+  --md-numbered-list-margin: 0 0 var(--spacing-sm);
+
+  font-size: var(--page-mcp-405-snippets-font-size);
+  line-height: var(--page-mcp-405-snippets-line-height);
+  text-align: left;
+
+  /* The copy control floats over the code, so wrapped lines need room to clear it. */
+  pre[data-testid='source-code'] {
+    padding-right: var(--page-mcp-405-snippets-code-padding-right);
+  }
+`;
+
+const TabHint = styled.p`
+  margin: 0 0 var(--spacing-xs);
+  color: var(--page-mcp-405-snippets-hint-text-color);
+`;

package/src/core/constants/mcp.ts

@@ -1 +1,11 @@
+import type { MCPOption } from '../types/mcp';
+
 export const DEFAULT_MCP_SERVER_NAME = 'mcp-server';
+
+export const DEFAULT_MCP_OPTIONS: MCPOption[] = [
+  'cursor',
+  'vscode',
+  'claude-code',
+  'codex',
+  'copy',
+];

package/src/core/hooks/use-active-heading.ts

@@ -8,6 +8,15 @@ type HeadingEntry = {
   [key: string]: IntersectionObserverEntry;
 };
 
+type ClickScroll = {
+  target: HTMLElement;
+  scrollMargin: number;
+  closestDistance: number;
+  reached: boolean;
+};
+
+const TARGET_TOLERANCE = 2;
+
 export function useActiveHeading(
   contentElement: HTMLDivElement | null,
   displayedHeadings?: Array<{ id: string; depth: number } | null>,
@@ -17,11 +26,14 @@ export function useActiveHeading(
   const headingElementsRef = useRef<HeadingEntry>({});
   const displayedHeadingsRef = useRef(displayedHeadings);
   const lockObserver = useRef<boolean>(false);
+  const clickScroll = useRef<ClickScroll | null>(null);
   const location = useLocation();
 
   useEffect(() => {
     setHeading(undefined);
     headingElementsRef.current = {};
+    clickScroll.current = null;
+    lockObserver.current = false;
   }, [location.pathname]);
 
   useEffect(() => {
@@ -133,10 +145,6 @@ export function useActiveHeading(
 
   const intersectionCallback = useCallback(
     (entries: IntersectionObserverEntry[]) => {
-      if (lockObserver.current) {
-        return;
-      }
-
       headingElementsRef.current = entries.reduce(
         (map: HeadingEntry, entry: IntersectionObserverEntry) => {
           map[entry.target.id] = entry;
@@ -145,6 +153,10 @@ export function useActiveHeading(
         headingElementsRef.current,
       );
 
+      if (lockObserver.current) {
+        return;
+      }
+
       if (isTopOfPage()) {
         const newHeading = headingElements[0]?.id || undefined;
         setHeading(newHeading);
@@ -202,22 +214,71 @@ export function useActiveHeading(
     [getIndexFromId, headingElements, getTriggerOffset, findActiveHeaderByVirtualPosition],
   );
 
+  const releaseClickScroll = useCallback(() => {
+    clickScroll.current = null;
+    lockObserver.current = false;
+  }, []);
+
+  const trackClickScroll = useCallback(() => {
+    const clickScrollState = clickScroll.current;
+    if (!clickScrollState) {
+      return;
+    }
+
+    const { top } = clickScrollState.target.getBoundingClientRect();
+
+    if (clickScrollState.reached) {
+      if (top >= 0 && top <= getTriggerOffset()) {
+        return;
+      }
+    } else {
+      const distance = Math.abs(top - clickScrollState.scrollMargin);
+
+      if (distance <= TARGET_TOLERANCE) {
+        clickScrollState.reached = true;
+        return;
+      }
+
+      if (distance <= clickScrollState.closestDistance + TARGET_TOLERANCE) {
+        clickScrollState.closestDistance = Math.min(clickScrollState.closestDistance, distance);
+        return;
+      }
+    }
+
+    releaseClickScroll();
+    intersectionCallback([]);
+  }, [releaseClickScroll, intersectionCallback, getTriggerOffset]);
+
   const handleHeadingClick = useCallback(
     (headingId: string) => {
-      lockObserver.current = true;
+      releaseClickScroll();
       setHeading(headingId);
 
-      const headingElement = headingElements.find((el) => el.id === headingId);
-      if (headingElement && headingElement.scrollIntoView) {
-        headingElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
+      const target =
+        document.getElementById(headingId) || headingElements.find((el) => el.id === headingId);
+
+      if (!target?.scrollIntoView) {
+        return;
+      }
+
+      target.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
+      if (!target.getClientRects().length) {
+        return;
       }
 
-      setTimeout(() => {
-        headingElementsRef.current = {};
-        lockObserver.current = false;
-      }, 300);
+      const scrollMargin = parseFloat(getComputedStyle(target).scrollMarginTop) || 0;
+      const distance = Math.abs(target.getBoundingClientRect().top - scrollMargin);
+
+      lockObserver.current = true;
+      clickScroll.current = {
+        target,
+        scrollMargin,
+        closestDistance: distance,
+        reached: distance <= TARGET_TOLERANCE,
+      };
     },
-    [headingElements],
+    [headingElements, releaseClickScroll],
   );
 
   useEffect(() => {
@@ -268,7 +329,10 @@ export function useActiveHeading(
     });
 
     const handleScroll = () => {
-      if (lockObserver.current) return;
+      if (clickScroll.current) {
+        trackClickScroll();
+        return;
+      }
 
       if (isTopOfPage()) {
         setHeading(headingElements[0]?.id || undefined);
@@ -281,7 +345,7 @@ export function useActiveHeading(
       observer.disconnect();
       window.removeEventListener('scroll', handleScroll);
     };
-  }, [headingElements, intersectionCallback, getTriggerOffset]);
+  }, [headingElements, intersectionCallback, getTriggerOffset, trackClickScroll]);
 
   return { heading, handleHeadingClick };
 }

package/src/core/hooks/use-active-section-id.ts

@@ -60,11 +60,13 @@ export function useActiveSectionId(
     }
 
     window.addEventListener('scroll', scrollListener, { capture: false });
-    setTimeout(() => {
+    const initialRead = setTimeout(() => {
       scrollListener();
     }, 10);
 
     return () => {
+      clearTimeout(initialRead);
+      scrollListener.cancel();
       window.removeEventListener('scroll', scrollListener);
     };
   }, [location, heightOffset, scrollListener]);