@redocly/theme 0.67.0-next.4 → 0.67.0-next.6

package/src/components/Search/SearchRecent.tsx

@@ -3,7 +3,7 @@ import styled from 'styled-components';
 
 import type { JSX } from 'react';
 
-import { breakpoints } from '@redocly/theme/core/utils';
+import { breakpoints, getBaseDataAttributes } from '@redocly/theme/core/utils';
 import { useThemeHooks, useRecentSearches } from '@redocly/theme/core/hooks';
 import { CloseIcon } from '@redocly/theme/icons/CloseIcon/CloseIcon';
 import { RecentlyViewedIcon } from '@redocly/theme/icons/RecentlyViewedIcon/RecentlyViewedIcon';
@@ -25,7 +25,9 @@ export function SearchRecent({ onSelect, className }: SearchRecentProps): JSX.El
   const handleOnRemove = (e: React.MouseEvent<SVGSVGElement, MouseEvent>, item: string) => {
     e.stopPropagation();
     removeSearchHistoryItem(item);
-    telemetry.sendSearchRecentRemoveButtonClickedMessage();
+    telemetry.sendSearchRecentRemoveClickedMessage([
+      getBaseDataAttributes('searchRecentRemove', 'search'),
+    ]);
   };
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>, item: string, index: number) => {

package/src/components/SidebarActions/SidebarActions.tsx

@@ -11,6 +11,7 @@ import {
   ControlsWrapChangeLayoutButtons,
 } from '@redocly/theme/components/SidebarActions/styled';
 import { Tooltip } from '@redocly/theme/components/Tooltip/Tooltip';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 export { LayoutVariant };
 
@@ -57,9 +58,13 @@ export const SidebarActions = ({
             onClick={() => {
               onChangeCollapseSidebarClick();
               if (collapsedSidebar) {
-                telemetry.sendSidebarItemExpandedMessage();
+                telemetry.sendSidebarExpandedMessage([
+                  getBaseDataAttributes('sidebarExpand', 'button'),
+                ]);
               } else {
-                telemetry.sendSidebarItemCollapsedMessage();
+                telemetry.sendSidebarCollapsedMessage([
+                  getBaseDataAttributes('sidebarCollapse', 'button'),
+                ]);
               }
             }}
             size="small"
@@ -76,7 +81,9 @@ export const SidebarActions = ({
             layout={layout}
             onClick={() => {
               onChangeViewClick();
-              telemetry.sendChangeLayoutButtonClickedMessage();
+              telemetry.sendChangeLayoutClickedMessage([
+                getBaseDataAttributes('changeLayout', 'button'),
+              ]);
             }}
           />
         </ControlsWrapChangeLayoutButtons>

package/src/components/TableOfContent/TableOfContent.tsx

@@ -10,7 +10,12 @@ import {
   useThemeConfig,
   useFullHeight,
 } from '@redocly/theme/core/hooks';
-import { breakpoints, getDisplayedHeadings, getLeastDepth } from '@redocly/theme/core/utils';
+import {
+  breakpoints,
+  getDisplayedHeadings,
+  getLeastDepth,
+  getBaseDataAttributes,
+} from '@redocly/theme/core/utils';
 
 export type TableOfContentProps = {
   headings?: Array<MdHeading | null> | null | undefined;
@@ -62,7 +67,7 @@ export function TableOfContent(props: TableOfContentProps): JSX.Element | null {
               data-testid={`toc-${heading.value}`}
               onClick={(e) => {
                 e.preventDefault();
-                telemetry.sendTocItemClickedMessage();
+                telemetry.sendTocItemClickedMessage([getBaseDataAttributes('tocItem', 'toc')]);
                 handleHeadingClick(heading.id);
               }}
             />

package/src/components/UserMenu/LoginButton.tsx

@@ -4,6 +4,7 @@ import type { ButtonVariant, ButtonSize } from '@redocly/theme/components/Button
 
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { Button } from '@redocly/theme/components/Button/Button';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 export type LoginButtonProps = {
   href: string;
@@ -36,7 +37,9 @@ export function LoginButton({
         data-translation-key={label ? undefined : labelTranslationKey}
         to={href}
         languageInsensitive
-        onClick={() => telemetry.sendLoginButtonClickedMessage()}
+        onClick={() =>
+          telemetry.sendLoginClickedMessage([getBaseDataAttributes('login', 'button')])
+        }
         data-testid="login-btn"
         extraClass={className}
         variant={variant}

package/src/components/UserMenu/LogoutMenuItem.tsx

@@ -5,6 +5,7 @@ import type { JSX } from 'react';
 import { useThemeHooks } from '@redocly/theme/core/hooks';
 import { LogoutIcon } from '@redocly/theme/icons/LogoutIcon/LogoutIcon';
 import { DropdownMenuItem } from '@redocly/theme/components/Dropdown/DropdownMenuItem';
+import { getBaseDataAttributes } from '@redocly/theme/core/utils';
 
 export type LogoutMenuItemProps = {
   iconOnly?: boolean;
@@ -18,7 +19,7 @@ export function LogoutMenuItem({ iconOnly, className }: LogoutMenuItemProps): JS
   const { translate } = useTranslate();
 
   const handleClick = () => {
-    telemetry.sendLogoutMenuItemClickedMessage();
+    telemetry.sendLogoutClickedMessage([getBaseDataAttributes('logoutItem', 'userMenu')]);
     handleLogout();
   };
 

package/src/core/constants/search.ts

@@ -73,4 +73,8 @@ export const TOOL_CALL_DISPLAY_TEXT: Partial<
     inProgressText: 'Reading API description...',
     completedText: 'Read API description',
   },
+  [ToolCallName.DescribeTools]: {
+    inProgressText: 'Discovering available tools...',
+    completedText: 'Discovered available tools',
+  },
 };

package/src/core/hooks/search/use-search-dialog.ts

@@ -5,6 +5,7 @@ import hotkeys from 'hotkeys-js';
 import { useThemeHooks } from '../use-theme-hooks';
 import { useThemeConfig } from '../use-theme-config';
 import { useSearchSession } from '../../contexts';
+import { getBaseDataAttributes } from '../../utils';
 
 export function useSearchDialog() {
   const [isOpen, setIsOpen] = useState(false);
@@ -20,7 +21,12 @@ export function useSearchDialog() {
     if (hotKeys) {
       hotkeys(hotKeys, (ev) => {
         setIsOpen(true);
-        telemetry.sendSearchOpenedMessage([{ object: 'search', method: 'shortcut' }]);
+        telemetry.sendSearchOpenedMessage([
+          {
+            ...getBaseDataAttributes('searchDialogId', 'search'),
+            method: 'shortcut',
+          },
+        ]);
         ev.preventDefault();
       });
 
@@ -30,7 +36,12 @@ export function useSearchDialog() {
   }, [hotKeys]);
 
   const onOpen = useCallback(function () {
-    telemetry.sendSearchOpenedMessage([{ object: 'search', method: 'click' }]);
+    telemetry.sendSearchOpenedMessage([
+      {
+        ...getBaseDataAttributes('searchDialogId', 'search'),
+        method: 'click',
+      },
+    ]);
     setIsOpen(true);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);

package/src/core/hooks/use-banner-telemetry.ts

@@ -3,6 +3,7 @@ import { useMemo } from 'react';
 import type { DisplayBanner } from '@redocly/theme/components/Banner/Banner';
 
 import { useThemeHooks } from './use-theme-hooks';
+import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
 
 const noop = (): void => {};
 const noopLink = (_href: string): void => {};
@@ -28,11 +29,11 @@ export function useBannerTelemetry(
       };
     }
 
-    const bannerUri = 'urn:redocly:realm:ui:banner:banner-id';
     const payload = {
-      id: 'banner-id' as const,
-      object: 'banner' as const,
-      uri: bannerUri,
+      ...getBaseDataAttributes<'bannerId', 'banner', 'urn:redocly:realm:ui:banner:bannerId'>(
+        'bannerId',
+        'banner',
+      ),
       trackingId: displayBanner.trackingId,
       hash: displayBanner.hash,
       color: displayBanner.color,

package/src/core/hooks/use-color-switcher.ts

@@ -6,6 +6,7 @@ import { useThemeConfig } from './use-theme-config';
 import { useThemeHooks } from './use-theme-hooks';
 import { createStore, useStore } from './use-store';
 import { DEFAULT_COLOR_MODES } from '../constants';
+import { generateBeforeAfterContext } from '../utils';
 
 const COLOR_MODE_KEY = 'colorSchema';
 const colorModeStore = createStore<string>({
@@ -51,7 +52,12 @@ export const useColorSwitcher = () => {
       root.classList.remove('notransition');
     });
     telemetry.sendColorModeSwitchedMessage([
-      { object: 'color_mode', from: activeColorMode, to: newMode },
+      ...generateBeforeAfterContext<'sendColorModeSwitchedMessage'>(
+        'colorMode',
+        'button',
+        { mode: activeColorMode },
+        { mode: newMode },
+      ),
     ]);
     setActiveColorMode(newMode);
   };

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

@@ -22,14 +22,7 @@ import {
   removeTrailingSlash,
   withoutPathPrefix,
 } from '../utils/urls';
-
-function createPageActionResource(pageSlug: string, pageUrl: string) {
-  return {
-    id: pageSlug,
-    object: 'page' as const,
-    uri: pageUrl,
-  };
-}
+import { getBaseDataAttributes } from '../utils/telemetry/get-base-data-attributes';
 
 const DEFAULT_ENABLED_ACTIONS = [
   'copy',
@@ -47,6 +40,7 @@ export type PageActionType =
   | 'claude'
   | 'docs-mcp-cursor'
   | 'docs-mcp-vscode'
+  // Used in OpenAPI docs x-mcp
   | 'mcp-cursor'
   | 'mcp-vscode';
 
@@ -78,25 +72,22 @@ export function usePageActions(
 
         const isDocsMcp = !requiresMcpUrl;
 
-        const origin = IS_BROWSER ? window.location.origin : '';
-        const pageUrl = `${origin}${pageSlug}`;
-
         return createMCPAction({
           clientType,
           mcpConfig: config,
           translate,
           onClickCallback: isDocsMcp
             ? () =>
-                telemetry.sendPageActionsButtonClickedMessage([
+                telemetry.sendPageActionsClickedMessage([
                   {
-                    ...createPageActionResource(pageSlug, pageUrl),
-                    action_type: `docs-mcp-${clientType}` as const,
+                    ...getBaseDataAttributes('pageActions', 'button'),
+                    actionType: `docs-mcp-${clientType}` as const,
                   },
                 ])
             : undefined,
         });
       },
-    [mcpUrl, mcpConfig, translate, telemetry, pageSlug],
+    [mcpUrl, mcpConfig, translate, telemetry],
   );
 
   const result: PageAction[] = useMemo(() => {
@@ -113,7 +104,6 @@ export function usePageActions(
       ? window.location.origin
       : ((globalThis as { SSR_HOSTNAME?: string })['SSR_HOSTNAME'] ?? '');
     const pathname = addTrailingSlash(pageSlug);
-    const pageUrl = combineUrls(origin, pathname);
     const isRoot = withoutPathPrefix(pathname) === '/';
     const mdPageUrl = isRoot
       ? combineUrls(origin, pathname, 'index.html.md')
@@ -138,10 +128,10 @@ export function usePageActions(
             }
             const text = await result.text();
             ClipboardService.copyCustom(text);
-            telemetry.sendPageActionsButtonClickedMessage([
+            telemetry.sendPageActionsClickedMessage([
               {
-                ...createPageActionResource(pageSlug, pageUrl),
-                action_type: 'copy',
+                ...getBaseDataAttributes('pageActions', 'button'),
+                actionType: 'copy',
               },
             ]);
           } catch (error) {
@@ -157,10 +147,10 @@ export function usePageActions(
         iconComponent: MarkdownFullIcon,
         link: mdPageUrl,
         onClick: () => {
-          telemetry.sendPageActionsButtonClickedMessage([
+          telemetry.sendPageActionsClickedMessage([
             {
-              ...createPageActionResource(pageSlug, pageUrl),
-              action_type: 'view',
+              ...getBaseDataAttributes('pageActions', 'button'),
+              actionType: 'view',
             },
           ]);
         },
@@ -175,10 +165,10 @@ export function usePageActions(
           iconComponent: ChatGptIcon,
           link,
           onClick: () => {
-            telemetry.sendPageActionsButtonClickedMessage([
+            telemetry.sendPageActionsClickedMessage([
               {
-                ...createPageActionResource(pageSlug, pageUrl),
-                action_type: 'chatgpt',
+                ...getBaseDataAttributes('pageActions', 'button'),
+                actionType: 'chatgpt',
               },
             ]);
             window.location.href = link;
@@ -195,10 +185,10 @@ export function usePageActions(
           iconComponent: ClaudeIcon,
           link,
           onClick: () => {
-            telemetry.sendPageActionsButtonClickedMessage([
+            telemetry.sendPageActionsClickedMessage([
               {
-                ...createPageActionResource(pageSlug, pageUrl),
-                action_type: 'claude',
+                ...getBaseDataAttributes('pageActions', 'button'),
+                actionType: 'claude',
               },
             ]);
             window.location.href = link;
@@ -300,28 +290,32 @@ function shouldHideAction(
     isMcpDisabled,
   }: ShouldHideActionContext,
 ): boolean {
-  // Can't use any actions if search is globally disabled (markdown files are not generated)
-  if (themeConfig.search?.hide) {
-    return true;
-  }
-  // Can't use any actions if no markdown files are generated for LLMs
-  if (pageProps?.seo?.llmstxt?.hide) {
-    return true;
-  }
   // Page actions are explicitly disabled in config
   if (themeConfig.navigation?.actions?.hide) {
     return true;
   }
 
-  const isOpenApiPage =
-    pageProps?.metadata?.type === 'openapi' || pageProps?.metadata?.subType === 'openapi-operation';
-  const isPageExcludedFromSearch =
-    pageProps?.frontmatter?.excludeFromSearch || (isOpenApiPage && openapiExcludeFromSearch);
+  const actionDependsOnLlmsTxt = ['view', 'copy', 'chatgpt', 'claude'].includes(action);
 
-  // Page excluded from search: only explicit MCP connect actions remain visible,
-  // since they don't depend on the page's markdown.
-  if (isPageExcludedFromSearch && action !== 'mcp-cursor' && action !== 'mcp-vscode') {
-    return true;
+  if (actionDependsOnLlmsTxt) {
+    // Can't use any actions if search is globally disabled (markdown files are not generated)
+    if (themeConfig.search?.hide) {
+      return true;
+    }
+    // Can't use any actions if no markdown files are generated for LLMs
+    if (pageProps?.seo?.llmstxt?.hide) {
+      return true;
+    }
+
+    const isOpenApiPage =
+      pageProps?.metadata?.type === 'openapi' ||
+      pageProps?.metadata?.subType === 'openapi-operation';
+    const isPageExcludedFromSearch =
+      pageProps?.frontmatter?.excludeFromSearch || (isOpenApiPage && openapiExcludeFromSearch);
+
+    if (isPageExcludedFromSearch) {
+      return true;
+    }
   }
 
   return shouldHideActionByType(action, { isPublic, mcpUrl, isMcpDisabled });

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

@@ -1,9 +1,10 @@
+import { useRef } from 'react';
 import { useNavigate } from 'react-router-dom';
 
 import { getProductClassName } from '@redocly/theme/components/Product/utils';
 
 import { useThemeHooks } from './use-theme-hooks';
-import { withPathPrefix } from '../utils';
+import { withPathPrefix, generateBeforeAfterContext } from '../utils';
 
 export function useProductPicker() {
   const { useCurrentProduct, useProducts, useTelemetry, useLoadAndNavigate } = useThemeHooks();
@@ -12,20 +13,33 @@ export function useProductPicker() {
   const telemetry = useTelemetry();
   const navigate = useNavigate();
   const loadAndNavigate = useLoadAndNavigate();
+  // An open dropdown can fire a menu item's onAction from an earlier render, so `product.link`
+  // may be stale (e.g. after a locale switch); resolve the live product via a ref.
+  const productsRef = useRef(products);
+  productsRef.current = products;
   function setProduct(product: typeof currentProduct) {
     if (!product) return;
-    telemetry.sendProductPickedMessage([{ object: 'product', product: product.slug }]);
+    // match on `name` (locale-stable; link/slug are re-localized)
+    const freshProduct = productsRef.current.find((p) => p.name === product.name) ?? product;
+    telemetry.sendProductPickerChangedMessage([
+      ...generateBeforeAfterContext<'sendProductPickerChangedMessage'>(
+        'productPicker',
+        'dropdown',
+        { product: currentProduct?.slug || '' },
+        { product: freshProduct.slug },
+      ),
+    ]);
     if (typeof document === 'undefined') return;
 
-    if (product.name) {
+    if (freshProduct.name) {
       const root = document.documentElement;
       Array.from(root.classList)
         .filter((c) => c.startsWith('product-'))
         .forEach((c) => root.classList.remove(c));
-      root.classList.add(getProductClassName(product.name));
+      root.classList.add(getProductClassName(freshProduct.name));
     }
 
-    loadAndNavigate({ navigate, to: withPathPrefix(product.link) });
+    loadAndNavigate({ navigate, to: withPathPrefix(freshProduct.link) });
   }
   return {
     currentProduct,

package/src/core/hooks/use-telemetry-fallback.ts

@@ -1,50 +1,61 @@
-// eslint-disable-next-line no-warning-comments
-// TODO we need to create some common way to do this.
+// Fallback no-op telemetry used by `useThemeHooks` when no ThemeDataContext
+// provider supplies real hooks.
 export const useTelemetryFallback = () => ({
   send: () => {},
-  sendPageViewedMessage: () => {},
-  sendPageActionsButtonClickedMessage: () => {},
   sendErrorMessage: () => {},
   sendClientErrorMessage: () => {},
+  sendCatalogEntitiesFilterCheckboxToggledMessage: () => {},
+  sendCatalogEntitiesCopyDataSchemaClickedMessage: () => {},
+  sendCatalogEntitiesViewModeChangedMessage: () => {},
+  sendCatalogEntitiesRelatedEntitiesListSearchQueryMessage: () => {},
+  sendCatalogEntitiesRelatedEntitiesListSearchResultClickMessage: () => {},
+  sendCatalogEntitiesListSearchQueryMessage: () => {},
+  sendCatalogEntitiesListSearchResultClickedMessage: () => {},
+  sendRedirectMessage: () => {},
+  sendCustomMessage: () => {},
+  sendSearchAIQueryMessage: () => {},
+  sendSearchAiOpenedMessage: () => {},
+  sendSearchAIFeedbackMessage: () => {},
+  sendLoginClickedMessage: () => {},
+  sendLoginProviderClickedMessage: () => {},
+  sendLogoutClickedMessage: () => {},
+  sendBannerViewedMessage: () => {},
+  sendBannerLinkClickedMessage: () => {},
+  sendBannerDismissedMessage: () => {},
   sendBreadcrumbClickedMessage: () => {},
-  sendColorModeSwitchedMessage: () => {},
-  sendSidebarItemClickedMessage: () => {},
-  sendSidebarItemExpandedMessage: () => {},
-  sendSidebarItemCollapsedMessage: () => {},
-  sendChangeLayoutButtonClickedMessage: () => {},
-  sendEditPageLinkClickedMessage: () => {},
-  sendCodeSnippetReportedMessage: () => {},
-  sendNavbarMenuItemClickedMessage: () => {},
-  sendLoginButtonClickedMessage: () => {},
-  sendLoginProviderButtonClickedMessage: () => {},
-  sendLogoutMenuItemClickedMessage: () => {},
-  sendLogoClickedMessage: () => {},
-  sendTocItemClickedMessage: () => {},
+  sendCatalogActionsClickedMessage: () => {},
   sendCatalogFilterChangedMessage: () => {},
   sendCatalogItemClickedMessage: () => {},
   sendScorecardLinkClickedMessage: () => {},
-  sendBackToCatalogButtonClickedMessage: () => {},
-  sendSidebarDrilldownBackButtonClickedMessage: () => {},
+  sendFilterCheckboxToggledMessage: () => {},
+  sendFeedbackMessage: () => {},
   sendFooterItemClickedMessage: () => {},
-  sendCatalogActionsButtonClickedMessage: () => {},
-  sendMobileMenuButtonCloseClickedMessage: () => {},
-  sendMobileMenuButtonOpenClickedMessage: () => {},
-  sendSearchInputResetButtonClickedMessage: () => {},
-  sendSearchRecentRemoveButtonClickedMessage: () => {},
+  sendNavbarMenuItemClickedMessage: () => {},
+  sendColorModeSwitchedMessage: () => {},
+  sendLanguagePickerChangedMessage: () => {},
+  sendProductPickerChangedMessage: () => {},
+  sendLogoClickedMessage: () => {},
+  sendCodeSnippetReportedMessage: () => {},
+  sendMobileMenuClosedMessage: () => {},
+  sendMobileMenuOpenedMessage: () => {},
+  sendPageViewedMessage: () => {},
+  sendPageTimeMessage: () => {},
+  sendPageActionsClickedMessage: () => {},
+  sendPageEditClickedMessage: () => {},
+  sendSidebarDrilldownBackClickedMessage: () => {},
+  sendSidebarItemClickedMessage: () => {},
+  sendSidebarExpandedMessage: () => {},
+  sendSidebarCollapsedMessage: () => {},
+  sendChangeLayoutClickedMessage: () => {},
+  sendRequestApiAccessClickedMessage: () => {},
+  sendVersionPickerChangedMessage: () => {},
+  sendSearchInputResetClickedMessage: () => {},
+  sendSearchResultClickedMessage: () => {},
+  sendSearchRecentRemoveClickedMessage: () => {},
   sendSearchRecentClickedMessage: () => {},
-  sendRequestApiAccessButtonClickedMessage: () => {},
-  sendVersionPickerSelectionChangeMessage: () => {},
-  sendProductPickedMessage: () => {},
-  sendFilterCheckboxToggledMessage: () => {},
-  sendLanguagePickerLocaleChangedMessage: () => {},
   sendSearchOpenedMessage: () => {},
   sendSearchQueryMessage: () => {},
-  sendSearchAiOpenedMessage: () => {},
-  sendSearchAIQueryMessage: () => {},
-  sendSearchAIFeedbackMessage: () => {},
-  sendFeedbackMessage: () => {},
-  sendSearchResultClickedMessage: () => {},
-  sendRedirectMessage: () => {},
+  sendTocItemClickedMessage: () => {},
   sendOpenapiDocsMessage: () => {},
   sendCopyCodeSnippetClickedMessage: () => {},
   sendViewedMessage: () => {},
@@ -67,10 +78,7 @@ export const useTelemetryFallback = () => ({
   sendAsyncapiDocsReferencedInClickedMessage: () => {},
   sendGraphqlDocsViewedMessage: () => {},
   sendGraphqlDocsPerformanceMetricsMessage: () => {},
+  sendGraphqlDocsDownloadDefinitionClickedMessage: () => {},
   sendGraphqlDocsReferencedInLinkClickedMessage: () => {},
   sendGraphqlDocsRequiredScopesModalOpenedMessage: () => {},
-  sendGraphqlDocsDownloadDefinitionClickedMessage: () => {},
-  sendBannerViewedMessage: () => {},
-  sendBannerLinkClickedMessage: () => {},
-  sendBannerDismissedMessage: () => {},
 });

package/src/core/styles/global.ts

@@ -1026,6 +1026,39 @@ const pages = css`
 
   // @tokens End
 
+  /**
+    * @tokens 405 MCP Page
+    * @presenter Color
+    */
+  --page-mcp-405-font-family: var(--font-family-base); // @presenter FontFamily
+  --page-mcp-405-margin-vertical: var(--spacing-xl);
+  --page-mcp-405-margin-horizontal: calc(var(--spacing-xxl) * 2);
+  --page-mcp-405-gap: var(--spacing-lg);
+  --page-mcp-405-max-width: 680px;
+  --page-mcp-405-margin-vertical-mobile: var(--spacing-xxl);
+  --page-mcp-405-margin-horizontal-mobile: 1rem;
+
+  --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-title-text-color: var(--text-color-primary);
+  --page-mcp-405-title-font-size: 42px; // @presenter FontSize
+  --page-mcp-405-title-font-weight: var(--font-weight-bold); // @presenter FontWeight
+  --page-mcp-405-title-line-height: 50px; // @presenter LineHeight
+  --page-mcp-405-title-font-size-mobile: var(--h3-font-size);
+  --page-mcp-405-title-line-height-mobile: var(--h3-line-height);
+
+  --page-mcp-405-description-text-color: var(--text-color-secondary);
+  --page-mcp-405-description-font-size: var(--font-size-xl); // @presenter FontSize
+  --page-mcp-405-description-font-weight: var(--font-weight-regular); // @presenter FontWeight
+  --page-mcp-405-description-line-height: var(--line-height-xl);
+  --page-mcp-405-description-font-size-mobile: var(--font-size-lg);
+  --page-mcp-405-description-line-height-mobile: var(--line-height-lg);
+
+   // @tokens End
+
   /**
     * @tokens 500 Page
     * @presenter Color

package/src/core/types/l10n.ts

@@ -134,6 +134,8 @@ export type TranslationKey =
   | 'page.forbidden.description'
   | 'page.notFound.title'
   | 'page.notFound.description'
+  | 'page.mcpNotAllowed.title'
+  | 'page.mcpNotAllowed.description'
   | 'page.lastUpdated.timeago'
   | 'page.lastUpdated.on'
   | 'catalog.filters.placeholder'

package/src/core/types/search.ts

@@ -133,4 +133,5 @@ export enum ToolCallName {
   GetSecuritySchemes = 'get-security-schemes',
   GetFullApiDescription = 'get-full-api-description',
   Execute = 'execute',
+  DescribeTools = 'describe-tools',
 }

package/src/core/utils/index.ts

@@ -46,3 +46,5 @@ export * from './content-segments';
 export * from './custom-catalog-options-casing';
 export * from './get-auto-dismiss-duration';
 export * from './tooltip-placement';
+export * from './telemetry/get-base-data-attributes';
+export * from './telemetry/generate-before-after-context';

package/src/core/utils/telemetry/generate-before-after-context.ts

@@ -0,0 +1,59 @@
+import type { AsyncApiRealmUI } from '@redocly/realm-asyncapi-sdk';
+
+import { getBaseDataAttributes } from './get-base-data-attributes';
+
+type UITelemetryClient = AsyncApiRealmUI.Telemetry;
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type UITelemetryClientMethods = {
+  [K in keyof UITelemetryClient]: UITelemetryClient[K] extends (...args: any) => any
+    ? UITelemetryClient[K]
+    : never;
+};
+type UITelemetryClientMethodKeys = {
+  [K in keyof UITelemetryClientMethods]: Parameters<
+    UITelemetryClientMethods[K]
+  >[0] extends readonly [any, any, ...any[]]
+    ? K
+    : never;
+}[keyof UITelemetryClientMethods];
+
+type EventSchemaProps<T extends UITelemetryClientMethodKeys> = Parameters<
+  UITelemetryClientMethods[T]
+>[0];
+
+type EventAfterContext<T extends UITelemetryClientMethodKeys> = EventSchemaProps<T>[0];
+type EventBeforeContext<T extends UITelemetryClientMethodKeys> = EventSchemaProps<T>[1];
+
+/**
+ * Builds a typed `[after, before]` tuple for Realm UI telemetry events whose AsyncAPI
+ * contract lists the updated state first, then the prior state (per CloudEvents styleguide).
+ *
+ * Each slice merges {@link getBaseDataAttributes} (`id`, `object`, `uri`) with the
+ * corresponding partial payload and sets `context` to `'after'` or `'before'`.
+ *
+ * @template T - Telemetry client method key whose `data` tuple is
+ *   `[after, before, ...]` (for example `'sendLanguagePickerChangedMessage'`).
+ * @param id - Stable resource identifier passed to {@link getBaseDataAttributes}
+ *   and included on both payloads.
+ * @param object - Resource kind passed to {@link getBaseDataAttributes}
+ *   and included on both payloads (for example `'dropdown'` or `'button'`).
+ * @param before - Event-specific fields for the prior state, excluding `id`, `object`,
+ *   `uri`, and `context` (filled by this helper).
+ * @param after - Event-specific fields for the updated state, excluding `id`, `object`,
+ *   `uri`, and `context` (filled by this helper).
+ * @returns A two-tuple in send order: the fully merged after payload, then the fully
+ *   merged before payload. Spread into the matching `send*Message` call.
+ */
+export function generateBeforeAfterContext<T extends UITelemetryClientMethodKeys>(
+  id: EventAfterContext<T>['id'],
+  object: EventAfterContext<T>['object'],
+  before: Omit<EventBeforeContext<T>, 'id' | 'object' | 'uri' | 'context'>,
+  after: Omit<EventAfterContext<T>, 'id' | 'object' | 'uri' | 'context'>,
+): [EventAfterContext<T> & { context: 'after' }, EventBeforeContext<T> & { context: 'before' }] {
+  const baseAttributes = getBaseDataAttributes(id, object);
+  return [
+    { ...baseAttributes, context: 'after' as const, ...after },
+    { ...baseAttributes, context: 'before' as const, ...before },
+  ];
+}