@redocly/theme 0.69.0-next.0 → 0.69.0-next.2

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/components/Markdown/Markdown.tsx

@@ -7,6 +7,7 @@ import { markdownBaseTableCss } from '@redocly/theme/components/Markdown/styles/
 import { markdownLinksCss } from '@redocly/theme/components/Markdown/styles/links';
 import { headingAnchorCss } from '@redocly/theme/components/Markdown/styles/heading-anchor';
 import {
+  ACCORDION_SELECTOR,
   ANCHOR_CLASS,
   H1_CLASS,
   H2_CLASS,
@@ -172,7 +173,7 @@ export const Markdown = styled.main
     margin: var(--md-hr-margin-vertical) 0;
   }
 
-  details {
+  details:not(${ACCORDION_SELECTOR}) {
     margin: 1.125em 0;
 
     summary {

package/src/core/constants/accordion.ts

@@ -0,0 +1,4 @@
+export const ACCORDION_COMPONENT_NAME = 'Markdoc/Accordion/Accordion';
+export const ACCORDION_GROUP_COMPONENT_NAME = 'Markdoc/Accordion/AccordionGroup';
+
+export const ACCORDION_SELECTOR = `[data-component-name='${ACCORDION_COMPONENT_NAME}']`;

package/src/core/constants/index.ts

@@ -1,3 +1,4 @@
+export * from './accordion';
 export * from './common';
 export * from './environments';
 export * from './code-walkthrough';

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-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]);

package/src/core/hooks/use-connect-mcp-button.ts

@@ -6,13 +6,15 @@ import type { MCPOption } from '../types';
 import { useThemeHooks } from './use-theme-hooks';
 import { useMCPConfig } from './use-mcp-config';
 import { ClipboardService } from '../utils/clipboard-service';
+import { DEFAULT_MCP_OPTIONS } from '../constants/mcp';
+import { generateClaudeCodeCommand, generateCodexCommand } from '../utils/mcp';
 
 export type McpButtonOptions = {
   options?: MCPOption[];
 };
 
 export type McpButtonSettings = {
-  isCopied: boolean;
+  copiedOption: MCPOption | null;
   cursorUrl: string;
   vscodeUrl: string;
   triggerButtonText: string;
@@ -23,35 +25,41 @@ export type McpButtonSettings = {
 const COPIED_RESET_TIMEOUT = 1000;
 
 export function useConnectMCPButton({
-  options = ['cursor', 'vscode', 'copy'],
+  options = DEFAULT_MCP_OPTIONS,
 }: McpButtonOptions = {}): McpButtonSettings {
   const { useTranslate } = useThemeHooks();
   const { translate } = useTranslate();
   const { serverName, serverUrl, cursorUrl, vscodeUrl } = useMCPConfig();
-  const [isCopied, setIsCopied] = useState(false);
+  const [copiedOption, setCopiedOption] = useState<MCPOption | null>(null);
 
   // eslint-disable-next-line react-hooks/exhaustive-deps
   const resetCopied = useCallback(
-    debounce(() => setIsCopied(false), COPIED_RESET_TIMEOUT),
+    debounce(() => setCopiedOption(null), COPIED_RESET_TIMEOUT),
     [],
   );
 
   const handleAction = useCallback(
     (action: MCPOption) => {
-      if (action === 'copy') {
-        const config = {
-          [serverName]: {
-            url: serverUrl,
-            description: 'MCP Server',
-          },
-        };
-        ClipboardService.copyCustom(JSON.stringify(config, null, 2));
-        setIsCopied(true);
+      const connection = { serverName, url: serverUrl };
+      const copyTextMap: Partial<Record<MCPOption, string>> = {
+        copy: JSON.stringify(
+          { [serverName]: { url: serverUrl, description: 'MCP Server' } },
+          null,
+          2,
+        ),
+        'claude-code': generateClaudeCodeCommand(connection),
+        codex: generateCodexCommand(connection),
+      };
+
+      const copyText = copyTextMap[action];
+      if (copyText !== undefined) {
+        ClipboardService.copyCustom(copyText);
+        setCopiedOption(action);
         resetCopied();
         return;
       }
 
-      const urlMap: Record<Exclude<MCPOption, 'copy'>, string> = {
+      const urlMap: Partial<Record<MCPOption, string>> = {
         cursor: cursorUrl,
         vscode: vscodeUrl,
       };
@@ -69,7 +77,7 @@ export function useConnectMCPButton({
   const visibleOptions = useMemo(() => options.filter(Boolean), [options]);
 
   return {
-    isCopied,
+    copiedOption,
     cursorUrl,
     vscodeUrl,
     triggerButtonText,

package/src/core/styles/global.ts

@@ -28,6 +28,7 @@ import { code } from '@redocly/theme/components/CodeBlock/variables';
 import { productPicker } from '@redocly/theme/components/Product/variables';
 import { markdown } from '@redocly/theme/components/Markdown/variables';
 import { banner } from '@redocly/theme/components/Banner/variables';
+import { markdownAccordion } from '@redocly/theme/markdoc/components/Accordion/variables';
 import { markdownTabs } from '@redocly/theme/markdoc/components/Tabs/variables';
 import { markdownNumberedList } from '@redocly/theme/markdoc/components/NumberedList/variables';
 import { diagram } from '@redocly/theme/markdoc/components/Diagram/variables';
@@ -1049,8 +1050,8 @@ const pages = css`
 
   --page-mcp-405-status-text-color: var(--text-color-helper);
   --page-mcp-405-status-font-size: var(--font-size-lg); // @presenter FontSize
-  --page-mcp-405-status-line-height: var(--line-height-lg); // @presenter LineHeight
   --page-mcp-405-status-font-weight: var(--font-weight-semibold); // @presenter FontWeight
+  --page-mcp-405-status-line-height: var(--line-height-lg); // @presenter LineHeight
 
   --page-mcp-405-title-text-color: var(--text-color-primary);
   --page-mcp-405-title-font-size: 42px; // @presenter FontSize
@@ -1066,6 +1067,11 @@ const pages = css`
   --page-mcp-405-description-font-size-mobile: var(--font-size-lg);
   --page-mcp-405-description-line-height-mobile: var(--line-height-lg);
 
+  --page-mcp-405-snippets-font-size: var(--font-size-base); // @presenter FontSize
+  --page-mcp-405-snippets-line-height: var(--line-height-base); // @presenter LineHeight
+  --page-mcp-405-snippets-hint-text-color: var(--text-color-secondary);
+  --page-mcp-405-snippets-code-padding-right: var(--spacing-xxl);
+
    // @tokens End
 
   /**
@@ -1352,6 +1358,7 @@ export const styles = css<{ palette?: string }>`
     ${loadProgressBar}
     ${logo}
     ${markdown}
+    ${markdownAccordion}
     ${markdownTabs}
     ${markdownNumberedList}
     ${diagram}

package/src/core/types/catalog.ts

@@ -212,6 +212,9 @@ export type BffCatalogEntityList = BffCatalogList<BffCatalogEntity>;
 export type BffCatalogRelatedEntityList = BffCatalogList<BffCatalogRelatedEntity>;
 
 export type Page = {
+  // Optional so existing code that builds a Page keeps compiling; the catalog BFF always emits both.
+  nextPage?: string | null;
+  previousPage?: string | null;
   endCursor: string | null;
   startCursor: string | null;
   hasNextPage: boolean;

package/src/core/types/l10n.ts

@@ -136,6 +136,19 @@ export type TranslationKey =
   | 'page.notFound.description'
   | 'page.mcpNotAllowed.title'
   | 'page.mcpNotAllowed.description'
+  | 'page.mcpNotAllowed.snippets.terminal.hint'
+  | 'page.mcpNotAllowed.snippets.claudeCode.headline'
+  | 'page.mcpNotAllowed.snippets.claudeDesktop.headline'
+  | 'page.mcpNotAllowed.snippets.claudeDesktop.instruction'
+  | 'page.mcpNotAllowed.snippets.chatgptApp.headline'
+  | 'page.mcpNotAllowed.snippets.chatgptApp.instruction'
+  | 'page.mcpNotAllowed.snippets.codexCli.headline'
+  | 'page.mcpNotAllowed.snippets.prompt.headline'
+  | 'page.mcpNotAllowed.snippets.prompt.hint'
+  | 'page.mcpNotAllowed.snippets.json.hint'
+  | 'page.mcpNotAllowed.tabs.claude'
+  | 'page.mcpNotAllowed.tabs.chatgpt'
+  | 'page.mcpNotAllowed.tabs.json'
   | 'page.lastUpdated.timeago'
   | 'page.lastUpdated.on'
   | 'catalog.filters.placeholder'
@@ -271,6 +284,10 @@ export type TranslationKey =
   | 'page.actions.connectMcp.cursorDescription'
   | 'page.actions.connectMcp.vscode'
   | 'page.actions.connectMcp.vscodeDescription'
+  | 'page.actions.connectMcp.claudeCode'
+  | 'page.actions.connectMcp.claudeCodeDescription'
+  | 'page.actions.connectMcp.codex'
+  | 'page.actions.connectMcp.codexDescription'
   | 'page.actions.connectMcp.copyConfig'
   | 'page.actions.connectMcp.copyConfigDescription'
   | 'openapi.download.description.title'

package/src/core/types/mcp.ts

@@ -1,6 +1,6 @@
 export type MCPClientType = 'cursor' | 'vscode';
 
-export type MCPOption = 'cursor' | 'vscode' | 'copy';
+export type MCPOption = 'cursor' | 'vscode' | 'claude-code' | 'codex' | 'copy';
 
 export type McpConnectionParams = {
   serverName: string;

package/src/core/utils/mcp.ts

@@ -32,3 +32,42 @@ export function generateMCPDeepLink(
       return generateCursorMCPDeepLink(config);
   }
 }
+
+// Server names can contain spaces (e.g. "Docs MCP server") which break bare CLI
+// arguments, so commands use a slugified form while JSON configs keep the raw name.
+export function slugifyMcpServerName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Claude Desktop's config file only launches stdio commands, so remote servers
+// connect through the mcp-remote bridge.
+export function generateClaudeDesktopConfig(config: McpConnectionParams): string {
+  return JSON.stringify(
+    {
+      mcpServers: {
+        [slugifyMcpServerName(config.serverName)]: {
+          command: 'npx',
+          args: ['-y', 'mcp-remote', config.url],
+        },
+      },
+    },
+    null,
+    2,
+  );
+}
+
+export function generateClaudeCodeCommand(config: McpConnectionParams): string {
+  return `claude mcp add --transport http ${slugifyMcpServerName(config.serverName)} ${config.url}`;
+}
+
+export function generateCodexCommand(config: McpConnectionParams): string {
+  return `codex mcp add ${slugifyMcpServerName(config.serverName)} --url ${config.url}`;
+}
+
+// Pasted into an AI assistant (Claude Code, Codex) so it installs the server itself.
+export function generateMcpInstallPrompt(config: McpConnectionParams): string {
+  return `Add the MCP server "${slugifyMcpServerName(config.serverName)}" with URL ${config.url} (streamable HTTP transport) to my MCP configuration, then verify it is connected.`;
+}