@redocly/theme 0.59.0-rc.3 → 0.60.0-custom.2

package/src/core/hooks/use-mcp-config.ts

@@ -0,0 +1,49 @@
+import { useMemo } from 'react';
+
+import { useThemeHooks } from './use-theme-hooks';
+import { IS_BROWSER } from '../utils/dom';
+import { DEFAULT_MCP_SERVER_NAME } from '../constants';
+import { generateMCPDeepLink } from '../utils/mcp';
+
+export type McpConfig = {
+  serverName: string;
+  origin: string;
+  serverUrl: string;
+  cursorUrl: string;
+  vscodeUrl: string;
+  isMcpDisabled: boolean;
+};
+
+export function useMCPConfig(): McpConfig {
+  const { useMcpData } = useThemeHooks();
+
+  const {
+    docs: { enabled, name },
+  } = useMcpData();
+
+  const origin = IS_BROWSER
+    ? window.location.origin
+    : ((globalThis as { SSR_HOSTNAME?: string })['SSR_HOSTNAME'] ?? '');
+  const serverName = name || DEFAULT_MCP_SERVER_NAME;
+  const serverUrl = `${origin}/mcp`;
+  const isMcpDisabled = !enabled || false;
+
+  const cursorUrl = useMemo(
+    () => generateMCPDeepLink('cursor', { serverName, url: serverUrl }),
+    [serverName, serverUrl],
+  );
+
+  const vscodeUrl = useMemo(
+    () => generateMCPDeepLink('vscode', { serverName, url: serverUrl }),
+    [serverName, serverUrl],
+  );
+
+  return {
+    serverName,
+    origin,
+    serverUrl,
+    cursorUrl,
+    vscodeUrl,
+    isMcpDisabled,
+  };
+}

package/src/core/hooks/use-page-actions.ts

@@ -1,31 +1,42 @@
-import { useMemo } from 'react';
+import { useMemo, useCallback } from 'react';
 
 import type { PageProps, UiAccessibleConfig } from '@redocly/config';
-import type { PageAction } from '../types';
+import type { PageAction, MCPClientType, McpConnectionParams } from '../types';
 
 import { CopyIcon } from '@redocly/theme/icons/CopyIcon/CopyIcon';
 import { ChatGptIcon } from '@redocly/theme/icons/ChatGptIcon/ChatGptIcon';
 import { ClaudeIcon } from '@redocly/theme/icons/ClaudeIcon/ClaudeIcon';
 import { MarkdownFullIcon } from '@redocly/theme/icons/MarkdownFullIcon/MarkdownFullIcon';
+import { VSCodeIcon } from '@redocly/theme/icons/VSCodeIcon/VSCodeIcon';
+import { CursorIcon } from '@redocly/theme/icons/CursorIcon/CursorIcon';
 
 import { useThemeHooks } from './use-theme-hooks';
 import { useThemeConfig } from './use-theme-config';
+import { useMCPConfig } from './use-mcp-config';
 import { ClipboardService } from '../utils/clipboard-service';
 import { IS_BROWSER } from '../utils/dom';
-import { CursorIcon } from '../../icons/CursorIcon/CursorIcon';
+import { generateMCPDeepLink } from '../utils/mcp';
 
-const DEFAULT_ENABLED_ACTIONS = ['copy', 'view', 'chatgpt', 'claude'] as const;
-const CURSOR_URL =
-  'cursor://anysphere.cursor-deeplink/mcp/install?name=$NAME&config=$BASE64_ENCODED_CONFIG';
+const DEFAULT_ENABLED_ACTIONS = [
+  'copy',
+  'view',
+  'chatgpt',
+  'claude',
+  'docs-mcp-cursor',
+  'docs-mcp-vscode',
+  'docs-mcp-json',
+] as const;
 
 export type PageActionType =
   | 'copy'
   | 'view'
   | 'chatgpt'
   | 'claude'
+  | 'docs-mcp-cursor'
+  | 'docs-mcp-vscode'
+  | 'docs-mcp-json'
   | 'mcp-cursor'
-  | 'mcp-claude'
-  | 'mcp-json';
+  | 'mcp-vscode';
 
 export function usePageActions(
   pageSlug: string,
@@ -34,12 +45,12 @@ export function usePageActions(
 ): PageAction[] {
   const { useTranslate, usePageData, usePageProps, usePageSharedData } = useThemeHooks();
   const { translate } = useTranslate();
-
   const themeConfig = useThemeConfig();
   const pageProps = usePageProps();
   const openApiSharedData = usePageSharedData<
     { options: { excludeFromSearch: boolean } } | undefined
   >('openAPIDocsStore');
+  const mcpConfig = useMCPConfig();
 
   const shouldHideAllActions = shouldHidePageActions(
     pageProps,
@@ -48,172 +59,179 @@ export function usePageActions(
   );
   const { isPublic } = usePageData() || {};
 
+  const createMCPHandler = useCallback(
+    (clientType: MCPClientType, requiresMcpUrl: boolean = false) =>
+      () => {
+        if (requiresMcpUrl && !mcpUrl) return null;
+        if (!requiresMcpUrl && (mcpUrl || mcpConfig.isMcpDisabled)) return null;
+
+        const config = requiresMcpUrl
+          ? { serverName: mcpConfig.serverName, url: mcpUrl || '' }
+          : { serverName: mcpConfig.serverName, url: mcpConfig.serverUrl || '' };
+
+        return createMCPAction({ clientType, mcpConfig: config, translate });
+      },
+    [mcpUrl, mcpConfig, translate],
+  );
+
   const result: PageAction[] = useMemo(() => {
     if (shouldHideAllActions && !actions?.length) {
       return [];
     }
 
-    const origin = IS_BROWSER ? window.location.origin : (globalThis as any)['SSR_HOSTNAME'];
-
+    const origin = IS_BROWSER
+      ? window.location.origin
+      : ((globalThis as { SSR_HOSTNAME?: string })['SSR_HOSTNAME'] ?? '');
     const normalizedSlug = pageSlug.startsWith('/') ? pageSlug : '/' + pageSlug;
-
     const mdPageUrl = new URL(
       origin + normalizedSlug + (normalizedSlug === '/' ? 'index.html.md' : '.md'),
     ).toString();
 
-    function getExternalAiPromptLink(baseUrl: string): string {
-      const externalAiPrompt = `Read ${mdPageUrl} and answer questions based on the content.`;
-
-      const url = new URL(baseUrl);
-      url.searchParams.set('q', externalAiPrompt);
-
-      return url.toString();
-    }
+    const actionHandlers: Record<PageActionType, () => PageAction | null> = {
+      'docs-mcp-cursor': createMCPHandler('cursor'),
+      'docs-mcp-vscode': createMCPHandler('vscode'),
+      'mcp-cursor': createMCPHandler('cursor', true),
+      'mcp-vscode': createMCPHandler('vscode', true),
 
-    return (themeConfig.navigation?.actions?.items || actions || DEFAULT_ENABLED_ACTIONS)
-      .map((action) => {
-        function generateMCPConfig(isCursor?: boolean): string {
-          const jsonConfig = {
-            'mcp-server': {
-              url: mcpUrl,
-              description: 'MCP Server',
-            },
-          };
-          if (isCursor) {
-            const url = CURSOR_URL.replace('$NAME', 'mcp-server').replace(
-              '$BASE64_ENCODED_CONFIG',
-              btoa(JSON.stringify(jsonConfig['mcp-server'])),
-            );
-            return url;
-          }
-
-          return JSON.stringify(jsonConfig, null, 2);
-        }
-
-        switch (action) {
-          case 'mcp-cursor':
-            if (!mcpUrl) {
-              return null;
+      copy: () => ({
+        buttonText: translate('page.actions.copyButtonText', 'Copy'),
+        title: translate('page.actions.copyTitle', 'Copy for LLM'),
+        description: translate('page.actions.copyDescription', 'Copy page as Markdown for LLMs'),
+        iconComponent: CopyIcon,
+        onClick: async () => {
+          try {
+            const result = await fetch(mdPageUrl);
+            if (result.status !== 200) {
+              return;
             }
+            const text = await result.text();
+            ClipboardService.copyCustom(text);
+          } catch (error) {
+            console.error(error);
+          }
+        },
+      }),
 
-            return {
-              buttonText: translate('page.actions.cursorMcpButtonText', 'Connect to Cursor'),
-              title: translate('page.actions.cursorMcpTitle', 'Connect to Cursor'),
-              description: translate(
-                'page.actions.cursorMcpDescription',
-                'Install MCP server on Cursor',
-              ),
-              iconComponent: CursorIcon,
-              onClick: () => {
-                try {
-                  const url = generateMCPConfig(true);
-                  window.open(url, '_blank');
-                } catch (error) {
-                  console.error(error);
-                }
-              },
-            };
-          case 'mcp-claude':
-            if (!mcpUrl) {
-              return null;
-            }
+      view: () => ({
+        buttonText: translate('page.actions.viewAsMdButtonText', 'View as Markdown'),
+        title: translate('page.actions.viewAsMdTitle', 'View as Markdown'),
+        description: translate('page.actions.viewAsMdDescription', 'Open this page as Markdown'),
+        iconComponent: MarkdownFullIcon,
+        link: mdPageUrl,
+      }),
 
-            return {
-              buttonText: 'Copy Claude configuration',
-              title: 'Copy Claude configuration',
-              description: 'Copy MCP configuration for Claude',
-              iconComponent: ClaudeIcon,
-              onClick: async () => {
-                ClipboardService.copyCustom(`claude mcp add --transport http server ${mcpUrl}`);
-              },
-            };
-          case 'mcp-json':
-            return {
-              buttonText: 'Copy MCP configuration',
-              title: 'Copy MCP JSON configuration',
-              description: 'Copy MCP JSON configuration',
-              iconComponent: CopyIcon,
-              onClick: async () => {
-                ClipboardService.copyCustom(generateMCPConfig());
-              },
-            };
-          case 'copy':
-            return {
-              buttonText: translate('page.actions.copyButtonText', 'Copy'),
-              title: translate('page.actions.copyTitle', 'Copy for LLM'),
-              description: translate(
-                'page.actions.copyDescription',
-                'Copy page as Markdown for LLMs',
-              ),
-              iconComponent: CopyIcon,
-              onClick: async () => {
-                try {
-                  const result = await fetch(mdPageUrl);
-                  if (result.status !== 200) {
-                    throw new Error('Failed to fetch markdown content');
-                  }
-                  const text = await result.text();
-
-                  ClipboardService.copyCustom(text);
-                } catch (error) {
-                  console.error(error);
-                }
-              },
-            };
-          case 'view':
-            return {
-              buttonText: translate('page.actions.viewAsMdButtonText', 'View as Markdown'),
-              title: translate('page.actions.viewAsMdTitle', 'View as Markdown'),
-              description: translate(
-                'page.actions.viewAsMdDescription',
-                'Open this page as Markdown',
-              ),
-              iconComponent: MarkdownFullIcon,
-              link: mdPageUrl,
-            };
-          case 'chatgpt':
-            if (!isPublic) {
-              return null;
-            }
+      chatgpt: () => {
+        if (!isPublic) {
+          return null;
+        }
+        return {
+          buttonText: translate('page.actions.chatGptButtonText', 'Open in ChatGPT'),
+          title: translate('page.actions.chatGptTitle', 'Open in ChatGPT'),
+          description: translate('page.actions.chatGptDescription', 'Get insights from ChatGPT'),
+          iconComponent: ChatGptIcon,
+          link: getExternalAiPromptLink('https://chat.openai.com', mdPageUrl),
+        };
+      },
 
-            return {
-              buttonText: translate('page.actions.chatGptButtonText', 'Open in ChatGPT'),
-              title: translate('page.actions.chatGptTitle', 'Open in ChatGPT'),
-              description: translate(
-                'page.actions.chatGptDescription',
-                'Get insights from ChatGPT',
+      claude: () => {
+        if (!isPublic) {
+          return null;
+        }
+        return {
+          buttonText: translate('page.actions.claudeButtonText', 'Open in Claude'),
+          title: translate('page.actions.claudeTitle', 'Open in Claude'),
+          description: translate('page.actions.claudeDescription', 'Get insights from Claude'),
+          iconComponent: ClaudeIcon,
+          link: getExternalAiPromptLink('https://claude.ai/new', mdPageUrl),
+        };
+      },
+      'docs-mcp-json': () => {
+        return {
+          buttonText: 'Copy MCP configuration',
+          title: 'Copy MCP JSON configuration',
+          description: 'Copy MCP JSON configuration',
+          iconComponent: CopyIcon,
+          onClick: async () => {
+            ClipboardService.copyCustom(
+              JSON.stringify(
+                {
+                  'mcp-server': {
+                    url: mcpUrl,
+                    description: 'MCP Server',
+                  },
+                },
+                null,
+                2,
               ),
-              iconComponent: ChatGptIcon,
-              link: getExternalAiPromptLink('https://chat.openai.com'),
-            };
-          case 'claude':
-            if (!isPublic) {
-              return null;
-            }
+            );
+          },
+        };
+      },
+    };
 
-            return {
-              buttonText: translate('page.actions.claudeButtonText', 'Open in Claude'),
-              title: translate('page.actions.claudeTitle', 'Open in Claude'),
-              description: translate('page.actions.claudeDescription', 'Get insights from Claude'),
-              iconComponent: ClaudeIcon,
-              link: getExternalAiPromptLink('https://claude.ai/new'),
-            };
-        }
-      })
-      .filter((action) => action !== null);
+    return (themeConfig.navigation?.actions?.items || actions || DEFAULT_ENABLED_ACTIONS)
+      .map((action) => actionHandlers[action]?.())
+      .filter((action): action is PageAction => action !== null);
   }, [
     shouldHideAllActions,
     pageSlug,
     themeConfig.navigation?.actions?.items,
     actions,
-    mcpUrl,
     translate,
     isPublic,
+    createMCPHandler,
+    mcpUrl,
   ]);
 
   return result;
 }
 
+function getExternalAiPromptLink(baseUrl: string, mdPageUrl: string): string {
+  const externalAiPrompt = `Read ${mdPageUrl} and answer questions based on the content.`;
+  const url = new URL(baseUrl);
+  url.searchParams.set('q', externalAiPrompt);
+  return url.toString();
+}
+
+type CreateMCPActionParams = {
+  clientType: MCPClientType;
+  mcpConfig: McpConnectionParams;
+  translate: (key: string, defaultValue: string) => string;
+};
+
+function createMCPAction({ clientType, mcpConfig, translate }: CreateMCPActionParams): PageAction {
+  const url = generateMCPDeepLink(clientType, mcpConfig);
+  const sharedProps = {
+    onClick: () => {
+      window.open(url, '_blank');
+    },
+  };
+
+  if (clientType === 'cursor') {
+    return {
+      ...sharedProps,
+      buttonText: translate('page.actions.connectMcp.cursor', 'Connect to Cursor'),
+      title: translate('page.actions.connectMcp.cursor', 'Connect to Cursor'),
+      description: translate(
+        'page.actions.connectMcp.cursorDescription',
+        'Install MCP server on Cursor',
+      ),
+      iconComponent: CursorIcon,
+    };
+  }
+
+  return {
+    ...sharedProps,
+    buttonText: translate('page.actions.connectMcp.vscode', 'Connect to VS Code'),
+    title: translate('page.actions.connectMcp.vscode', 'Connect to VS Code'),
+    description: translate(
+      'page.actions.connectMcp.vscodeDescription',
+      'Install MCP server on VS Code',
+    ),
+    iconComponent: VSCodeIcon,
+  };
+}
+
 function shouldHidePageActions(
   pageProps: PageProps,
   themeConfig: UiAccessibleConfig,

package/src/core/hooks/use-product-picker.ts

@@ -1,6 +1,7 @@
 import { useNavigate } from 'react-router-dom';
 
 import { useThemeHooks } from './use-theme-hooks';
+import { withPathPrefix } from '../utils';
 
 export function useProductPicker() {
   const { useCurrentProduct, useProducts, useTelemetry, useLoadAndNavigate } = useThemeHooks();
@@ -12,7 +13,7 @@ export function useProductPicker() {
   function setProduct(product: typeof currentProduct) {
     if (!product) return;
     telemetry.sendProductPickedMessage({ product: product.slug });
-    loadAndNavigate({ navigate, to: product.link });
+    loadAndNavigate({ navigate, to: withPathPrefix(product.link) });
   }
   return {
     currentProduct,