blume 2.2.0 → 2.2.2

package/src/components/layout/PageActions.astro

@@ -1,6 +1,12 @@
 ---
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
+import {
+  isBuiltInMcpClient,
+  mcpClients,
+  mcpMenuRows,
+} from "../../core/mcp-clients.ts";
+import type { McpMenuEntry } from "../../core/mcp-clients.ts";
 import { NEW_TAB_ATTRS } from "../../core/new-tab.ts";
 import { openInChatProviders } from "../../core/open-in-chat.ts";
 import type { OpenInChatProvider } from "../../core/open-in-chat.ts";
@@ -18,6 +24,11 @@ interface Props {
   mcpUrl?: string | null;
   /** Display name of the MCP server (defaults to the site title). */
   mcpName?: string | null;
+  /**
+   * "Connect to MCP" clients to list after "Copy server URL", in order, with
+   * custom labels resolved; omitting the prop lists every built-in client.
+   */
+  mcpMenu?: readonly McpMenuEntry[];
   /**
    * "Open in chat" providers to list, in order; an empty list hides the
    * action, and omitting the prop shows every provider.
@@ -40,6 +51,7 @@ const {
   exportEpub,
   mcpUrl,
   mcpName,
+  mcpMenu,
   openInChat,
   strings,
   divider = true,
@@ -89,6 +101,10 @@ const providers = (openInChat ?? openInChatProviders).map((key) => ({
 // keep that separator only while a configured list preserves v0 first.
 const chatSeparator = providers.length > 1 && providers[0]?.key === "v0";
 
+// `agents.mcp.clients` picks and orders the clients after "Copy server URL",
+// with a rule between the commands to copy and the install links.
+const mcpRows = mcpMenuRows(mcpMenu ?? mcpClients);
+
 // The block renders once, for the right rail. Below `xl` the script moves it
 // into the mobile "On this page" dropdown, and the global styles below the
 // markup restyle it there from that container.
@@ -99,11 +115,17 @@ const rowClass =
   "flex w-full items-center gap-2.5 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:text-foreground";
 
 // Items inside the floating popovers keep menu affordances (padding + hover
-// background).
+// background). Their icons sit in a box one line tall, so a label that wraps
+// keeps them beside its first line.
 const menuRowClass =
-  "flex w-full items-center gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground";
+  "flex w-full items-start gap-2.5 rounded-md px-2 py-1.5 text-start text-muted-foreground text-sm transition-colors hover:bg-muted hover:text-foreground";
+const menuIconClass = "flex h-lh shrink-0 items-center";
+// At most out to the rail's edge, past its padding (`--blume-rail-inset`, set
+// by the layout), less 2px so the border never lands on the edge: the rail
+// scrolls, so it clips anything wider. Longer labels wrap instead. The minimum
+// width gives way to that cap in a narrower rail.
 const panelClass =
-  "absolute top-full right-2 z-50 mt-1 w-max min-w-[14rem] max-w-[22rem] rounded-blume border border-border bg-background p-1 shadow-xl";
+  "absolute top-full end-0 z-50 mt-1 w-max [--blume-menu-room:calc(100%+var(--blume-rail-inset,1rem)-2px)] min-w-[min(14rem,var(--blume-menu-room))] max-w-(--blume-menu-room) wrap-anywhere rounded-blume border border-border bg-background p-1 shadow-xl";
 ---
 
 <div
@@ -156,13 +178,17 @@ const panelClass =
         <div class={panelClass} data-blume-menu>
           {exportPdf && (
             <button class={menuRowClass} data-blume-export-pdf type="button">
-              <Icon name="file" size={16} />
+              <span class={menuIconClass}>
+                <Icon name="file" size={16} />
+              </span>
               <span class="flex-1">{a.exportPdf}</span>
             </button>
           )}
           {exportEpub && (
             <button class={menuRowClass} data-blume-export-epub type="button">
-              <Icon name="book-open" size={16} />
+              <span class={menuIconClass}>
+                <Icon name="book-open" size={16} />
+              </span>
               <span class="flex-1" data-blume-epub-label>
                 {a.exportEpub}
               </span>
@@ -198,9 +224,11 @@ const panelClass =
                 data-open-in={provider.key}
                 {...NEW_TAB_ATTRS}
               >
-                <span set:html={LOGOS[provider.key]} />
+                <span class={menuIconClass} set:html={LOGOS[provider.key]} />
                 <span class="flex-1">{provider.label}</span>
-                <Icon name="external-link" size={13} />
+                <span class={menuIconClass}>
+                  <Icon name="external-link" size={13} />
+                </span>
               </a>
             </>
           ))}
@@ -225,34 +253,72 @@ const panelClass =
         </summary>
         <div class={panelClass} data-blume-menu>
           <button class={menuRowClass} data-mcp-copy-url type="button">
-            <Icon name="link" size={16} />
+            <span class={menuIconClass}>
+              <Icon name="link" size={16} />
+            </span>
             <span class="flex-1" data-mcp-url-label>
               {a.copyServerUrl}
             </span>
           </button>
-          <button class={menuRowClass} data-mcp-copy-claude type="button">
-            <span set:html={LOGOS.claude} />
-            <span class="flex-1" data-mcp-claude-label>
-              {a.copyClaudeCode}
-            </span>
-          </button>
-          <button class={menuRowClass} data-mcp-copy-codex type="button">
-            <span set:html={LOGOS.codex} />
-            <span class="flex-1" data-mcp-codex-label>
-              {a.copyCodex}
-            </span>
-          </button>
-          <hr class="my-1 border-border border-t" />
-          <a class={menuRowClass} data-mcp-cursor rel="noreferrer">
-            <span set:html={LOGOS.cursor} />
-            <span class="flex-1">{a.addToCursor}</span>
-            <Icon name="external-link" size={13} />
-          </a>
-          <a class={menuRowClass} data-mcp-vscode rel="noreferrer">
-            <Icon name="code" size={16} />
-            <span class="flex-1">{a.addToVscode}</span>
-            <Icon name="external-link" size={13} />
-          </a>
+          {mcpRows.map(({ client, rule }) => (
+            <>
+              {rule && <hr class="my-1 border-border border-t" />}
+              {client === "claude-code" && (
+                <button
+                  class={menuRowClass}
+                  data-mcp-copy-claude
+                  type="button"
+                >
+                  <span class={menuIconClass} set:html={LOGOS.claude} />
+                  <span class="flex-1" data-mcp-claude-label>
+                    {a.copyClaudeCode}
+                  </span>
+                </button>
+              )}
+              {client === "codex" && (
+                <button class={menuRowClass} data-mcp-copy-codex type="button">
+                  <span class={menuIconClass} set:html={LOGOS.codex} />
+                  <span class="flex-1" data-mcp-codex-label>
+                    {a.copyCodex}
+                  </span>
+                </button>
+              )}
+              {client === "cursor" && (
+                <a class={menuRowClass} data-mcp-cursor rel="noreferrer">
+                  <span class={menuIconClass} set:html={LOGOS.cursor} />
+                  <span class="flex-1">{a.addToCursor}</span>
+                  <span class={menuIconClass}>
+                    <Icon name="external-link" size={13} />
+                  </span>
+                </a>
+              )}
+              {client === "vscode" && (
+                <a class={menuRowClass} data-mcp-vscode rel="noreferrer">
+                  <span class={menuIconClass}>
+                    <Icon name="code" size={16} />
+                  </span>
+                  <span class="flex-1">{a.addToVscode}</span>
+                  <span class={menuIconClass}>
+                    <Icon name="external-link" size={13} />
+                  </span>
+                </a>
+              )}
+              {!isBuiltInMcpClient(client) && (
+                <button
+                  class={menuRowClass}
+                  data-mcp-copy-command={client.command}
+                  type="button"
+                >
+                  <span class={menuIconClass}>
+                    <Icon name={client.icon ?? "terminal"} size={16} />
+                  </span>
+                  <span class="flex-1" data-mcp-command-label>
+                    {client.label}
+                  </span>
+                </button>
+              )}
+            </>
+          ))}
         </div>
       </details>
     )
@@ -299,6 +365,7 @@ const panelClass =
 </style>
 
 <script>
+  import { mcpClientCommand } from "../../core/mcp-clients.ts";
   import { copyDeferredText, copyText, flashLabel } from "../copy-feedback.ts";
   import { installDropdownDismiss } from "../dropdown-dismiss.ts";
   import { mountBase } from "../islands/base-path.ts";
@@ -397,10 +464,15 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
       return;
     }
     const rect = summary.getBoundingClientRect();
+    // The rail scrolls, so it clips the menu at its own edges: its top sits
+    // under the sticky header, below the viewport's.
+    const room = details
+      .closest("[data-blume-toc]")
+      ?.getBoundingClientRect() ?? { bottom: window.innerHeight, top: 0 };
     const margin = 8;
     const flipUp =
-      rect.bottom + menu.offsetHeight + margin > window.innerHeight &&
-      rect.top - menu.offsetHeight - margin > 0;
+      rect.bottom + menu.offsetHeight + margin > room.bottom &&
+      rect.top - menu.offsetHeight - margin > room.top;
     menu.classList.toggle("top-full", !flipUp);
     menu.classList.toggle("mt-1", !flipUp);
     menu.classList.toggle("bottom-full", flipUp);
@@ -468,7 +540,7 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
     }
     // The action dropdowns are native <details>. Make them behave like a proper
     // menu: only one open at a time, and flip above the trigger when opening
-    // downward would run past the viewport bottom.
+    // downward would run past the rail's bottom and there's room above.
     const dropdowns = [...root.querySelectorAll<HTMLDetailsElement>("details")];
     for (const details of dropdowns) {
       details.addEventListener("toggle", () => {
@@ -572,6 +644,19 @@ hr { border: 0; border-top: 1px solid #ddd; margin: 2em 0; }`;
             root.querySelector("[data-mcp-codex-label]")
           )
         );
+      for (const button of root.querySelectorAll<HTMLElement>(
+        "[data-mcp-copy-command]"
+      )) {
+        button.addEventListener("click", () =>
+          copy(
+            mcpClientCommand(button.dataset.mcpCopyCommand ?? "", {
+              name: id,
+              url: mcpUrl,
+            }),
+            button.querySelector("[data-mcp-command-label]")
+          )
+        );
+      }
     }
 
     const label = root.querySelector("[data-blume-copy-label]");

package/src/components/layout/RootLayout.astro

@@ -9,6 +9,8 @@ import type { UIStrings } from "../../core/i18n-ui.ts";
 import { resolveDateFormatOptions } from "../../core/date-format.ts";
 import type { ResolvedDateFormat } from "../../core/schema.ts";
 import type { OpenInChatProvider } from "../../core/open-in-chat.ts";
+import { mcpMenuEntries } from "../../core/mcp-clients.ts";
+import type { McpClientEntry } from "../../core/mcp-clients.ts";
 import type {
   BlumeBanner,
   BlumeClientData,
@@ -114,7 +116,15 @@ interface Props {
   banner?: BlumeBanner | null;
   analytics?: BlumeDataConfig["analytics"] | null;
   navigation: Navigation;
-  mcp?: { name: string; route: string } | null;
+  /**
+   * The hosted MCP server. `clients` lists the "Connect to MCP" menu's
+   * clients in order, and defaults to every built-in one.
+   */
+  mcp?: {
+    clients?: readonly McpClientEntry[];
+    name: string;
+    route: string;
+  } | null;
   page: { title: string; description?: string; route: string };
   headings: Heading[];
   imageZoom?: boolean;
@@ -471,6 +481,11 @@ const markdownMirror = isBare
 // Needs a configured site to be useful, so the menu is hidden without one.
 const mcpUrl =
   mcp && siteUrl ? new URL(withMountedBase(mcp.route), siteUrl).href : null;
+// Custom clients' labels resolve to the page's locale. Without a list,
+// PageActions shows every built-in client.
+const mcpMenu = mcp?.clients
+  ? mcpMenuEntries(mcp.clients, locale, data.config.i18n?.defaultLocale)
+  : undefined;
 
 // Scope the sidebar (and the breadcrumbs/pagination derived from it) to the
 // active tab's section, so a multi-section site drills each tab into its own
@@ -953,7 +968,7 @@ const localeRedirect = localeTargets
         showToc && (
           <aside
             aria-label={strings.toc.title}
-            class="sticky top-16 hidden h-[calc(100dvh-4rem)] scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto px-4 pt-6 pb-10 text-sm xl:block"
+            class="sticky top-16 hidden h-[calc(100dvh-4rem)] scrollbar-thin scrollbar-thumb-border scrollbar-track-transparent overflow-y-auto [--blume-rail-inset:1rem] px-(--blume-rail-inset) pt-6 pb-10 text-sm xl:block"
             data-blume-toc
           >
             {hasToc && (
@@ -968,6 +983,7 @@ const localeRedirect = localeTargets
               editUrl={editUrl}
               exportEpub={exportEpub}
               exportPdf={exportPdf}
+              mcpMenu={mcpMenu}
               mcpName={mcp?.name}
               mcpUrl={mcpUrl}
               openInChat={openInChat}

package/src/components/layout/SiteFooter.astro

@@ -1,8 +1,8 @@
 ---
 // The site footer, below the content on every page: one row, as tall as the
-// header, with `footer.links` on one side and the social profile icons on the
-// other. The site's repository (`github`, unless `navigation.repo` hides it)
-// is the first icon; the footer is the only place it's linked. With `consent` configured the links end with the
+// header, with `footer.links` on one side, the social profile icons on the
+// other, and `footer.copyright` centered between them. The site's repository
+// (`github`, unless `navigation.repo` hides it) is the first icon; the footer is the only place it's linked. With `consent` configured the links end with the
 // Cookie settings link, which reopens the reader's consent choices. Renders
 // nothing when there's none of these; a `components.ts` `Footer` replaces it.
 import data from "blume:data";
@@ -12,6 +12,7 @@ import type { Navigation } from "../../core/types.ts";
 import { EN_UI } from "../../core/i18n-ui.ts";
 import type { UIStrings } from "../../core/i18n-ui.ts";
 import { routeSetFor } from "../../core/locale-links.ts";
+import { resolveLocalizable } from "../../core/localizable.ts";
 import { newTabAttrs } from "../../core/new-tab.ts";
 import Icon from "../Icon.astro";
 import { withBase } from "../islands/base-path.ts";
@@ -21,8 +22,9 @@ import { footerSocialLinks } from "./footer-socials.ts";
 interface Props {
   footer?: BlumeDataConfig["footer"];
   /**
-   * Active locale of the page: labels written as per-locale maps show its
-   * entry, and internal links move into it (see `footer-links.ts`).
+   * Active locale of the page: the copyright and labels written as
+   * per-locale maps show its entry, and internal links move into it (see
+   * `footer-links.ts`).
    */
   locale?: string;
   /** The page's navigation: its `repoUrl` is the repository link. */
@@ -40,6 +42,14 @@ const socials = footerSocialLinks(
     ? { href: repoUrl, label: { ...EN_UI.nav, ...ui?.nav }.githubRepository }
     : null
 );
+const copyright =
+  footer?.copyright === undefined
+    ? null
+    : resolveLocalizable(
+        footer.copyright,
+        locale,
+        data.config.i18n?.defaultLocale
+      );
 const links = footerLinks(footer?.links ?? [], {
   basePath: data.config.basePath,
   i18n: data.config.i18n,
@@ -58,9 +68,17 @@ const hasLinks = links.length > 0 || consentSettings !== null;
 ---
 
 {
-  (hasLinks || socials.length > 0) && (
+  (copyright !== null || hasLinks || socials.length > 0) && (
     <footer class="border-border border-t px-4 md:px-6" data-blume-footer>
-      <div class="flex min-h-16 flex-wrap items-center justify-between gap-x-6 gap-y-3 py-3">
+      {/* With a copyright, three columns from `md`, the outer two sharing
+          what it leaves so it sits at the true center; without one, the
+          links keep the row's full width. Narrower, the row wraps. */}
+      <div
+        class:list={[
+          "flex min-h-16 flex-wrap items-center gap-x-6 gap-y-3 py-3",
+          copyright !== null && "md:grid md:grid-cols-[1fr_auto_1fr]",
+        ]}
+      >
         {hasLinks && (
           <ul class="flex flex-wrap items-center gap-x-5 gap-y-2 text-sm">
             {links.map((link) => (
@@ -87,10 +105,15 @@ const hasLinks = links.length > 0 || consentSettings !== null;
             )}
           </ul>
         )}
+        {copyright !== null && (
+          <p class="text-muted-foreground text-sm md:col-start-2">
+            {copyright}
+          </p>
+        )}
         {/* Pulled out by the buttons' padding, so the glyphs line up with the
             footer's edge, and pushed to the far side even with no links. */}
         {socials.length > 0 && (
-          <ul class="-me-[9px] -my-[9px] ms-auto flex flex-wrap items-center gap-1">
+          <ul class="-me-[9px] -my-[9px] ms-auto flex flex-wrap items-center gap-1 md:col-start-3">
             {socials.map((social) => (
               <li>
                 <a

package/src/core/config-input.ts

@@ -22,6 +22,8 @@ import type { FontSlug } from "../theme/fonts.ts";
 import type { FooterSocial } from "./footer.ts";
 import type {
   blumeConfigSchema,
+  McpClient,
+  McpCustomClient,
   OpenInChatProvider,
   SidebarDisplay,
   SidebarItemConfig,
@@ -147,9 +149,15 @@ export interface FooterLink {
 
 /**
  * The site footer, below the content on every page: a row of links on one
- * side, and social profile icons on the other.
+ * side, social profile icons on the other, and a copyright line centered
+ * between them.
  */
 export interface FooterConfig {
+  /**
+   * A line of plain text centered between the links and the icons, like
+   * `© 2026 Acme, Inc.`, or a map of locale code to text.
+   */
+  copyright?: LocalizableLabel;
   /** Links in one row, left to right. */
   links?: FooterLink[];
   /**
@@ -719,6 +727,32 @@ export interface LlmsTxtConfig {
 
 /** Expose the docs as an MCP server for connecting agents. */
 export interface McpConfig {
+  /**
+   * The clients the "Connect to MCP" page action installs the server into,
+   * beside its "Copy server URL" row. Defaults to `true` (every built-in
+   * client). Set `false` to list none, or list built-in keys and your own
+   * clients, in order. A custom client's `command` is copied with `{name}`
+   * (the server name as an id) and `{url}` (the server's URL) filled in; its
+   * `label` localizes like a header link's, and `icon` defaults to `terminal`.
+   *
+   * ```ts
+   * agents: {
+   *   mcp: {
+   *     enabled: true,
+   *     clients: [
+   *       "claude-code",
+   *       {
+   *         label: "Copy Copilot CLI command",
+   *         command: "copilot mcp add --transport http {name} {url}",
+   *         icon: "terminal",
+   *       },
+   *       "vscode",
+   *     ],
+   *   },
+   * }
+   * ```
+   */
+  clients?: boolean | (McpClient | McpCustomClient)[];
   /** Turn the MCP server on. Defaults to `false`. */
   enabled?: boolean;
   /** Optional system hint passed to connecting agents. */
@@ -1567,8 +1601,8 @@ export interface BlumeConfig {
    */
   feedback?: boolean | FeedbackConfig;
   /**
-   * The site footer: social profile icons and up to four link columns. Unset,
-   * the site has no footer.
+   * The site footer: a copyright line, a row of links, and social profile
+   * icons. Unset, the site has no footer.
    */
   footer?: FooterConfig;
   /** Opt-in custom frontmatter keys, validated by schemas you supply. */
@@ -1597,7 +1631,7 @@ export interface BlumeConfig {
    * Limit how often one reader (by IP address) can call the server routes —
    * the assistant, the API playground proxy, server-side search — with an
    * adapter from `blume/ratelimit`: `memory()` (the default, 30 requests per
-   * 10 minutes), `upstash()`, or `cloudflare()`. `false` turns it off.
+   * 10 minutes), `upstash()`, `cloudflare()`, or `unkey()`. `false` turns it off.
    */
   rateLimit?: false | RateLimitAdapter;
   /** React island behavior (compiler auto-memoization). */

package/src/core/data.ts

@@ -187,7 +187,7 @@ export interface BlumeDataConfig {
   feedback: boolean;
   /** Whether the rating asks for a written comment after it (`feedback.comments`). */
   feedbackComments: boolean;
-  /** `footer`: social profile icons and link columns, or `null` when unset. */
+  /** `footer`: the copyright line, links, and social profile icons, or `null` when unset. */
   footer: ResolvedConfig["footer"] | null;
   /**
    * Repo coordinates for content components that address the API or build
@@ -206,8 +206,15 @@ export interface BlumeDataConfig {
   /** `markdown.imageZoom`: click-to-zoom content images. */
   imageZoom: boolean;
   logo: BlumeLogo | null;
-  /** Hosted MCP server, or `null` when MCP is off. */
-  mcp: { name: string; route: string } | null;
+  /**
+   * Hosted MCP server, or `null` when MCP is off, with the clients its
+   * "Connect to MCP" page action lists (`agents.mcp.clients`), in order.
+   */
+  mcp: {
+    clients: ResolvedConfig["agents"]["mcp"]["clients"];
+    name: string;
+    route: string;
+  } | null;
   /** `seo.metatags`: the site's own tags for every page's head, or `null`. */
   metatags: Record<string, string> | null;
   /**

package/src/core/mcp-clients.ts

@@ -0,0 +1,87 @@
+import { resolveLocalizable } from "./localizable.ts";
+import type { LocalizableLabel } from "./schema.ts";
+
+/**
+ * Clients the "Connect to MCP" page action knows how to install the server
+ * into, in display order. Shared by the config schema (`agents.mcp.clients`
+ * entries validate against this list) and the PageActions menu (which renders
+ * the full list when the config is `true`). Lives outside `schema.ts` so the
+ * component can import the list without pulling the whole config schema into
+ * the layout module graph.
+ */
+export const mcpClients = ["claude-code", "codex", "cursor", "vscode"] as const;
+
+export type McpClient = (typeof mcpClients)[number];
+
+/** A client Blume doesn't ship: a menu row that copies its `command`. */
+export interface McpCustomClient {
+  /**
+   * Command the row copies, with `{name}` (the server name as an id, like
+   * `acme-docs`) and `{url}` (the server's absolute URL) filled in.
+   */
+  command: string;
+  /** Icon beside the label: a Lucide name, inline SVG, or image. Defaults to `terminal`. */
+  icon?: string;
+  /** Row label, optionally per locale (`{ en: "…", de: "…" }`). */
+  label: LocalizableLabel;
+}
+
+export type McpClientEntry = McpClient | McpCustomClient;
+
+/** A menu entry as a page renders it: a custom label resolved to its locale. */
+export type McpMenuEntry =
+  | McpClient
+  | (Omit<McpCustomClient, "label"> & { label: string });
+
+/** Whether a `clients` entry names a built-in client rather than a custom one. */
+export const isBuiltInMcpClient = (
+  client: McpClientEntry | McpMenuEntry
+): client is McpClient => typeof client === "string";
+
+/** Resolve the custom clients' labels for one page's locale. */
+export const mcpMenuEntries = (
+  clients: readonly McpClientEntry[],
+  locale?: string,
+  defaultLocale?: string
+): McpMenuEntry[] =>
+  clients.map((client) =>
+    isBuiltInMcpClient(client)
+      ? client
+      : {
+          ...client,
+          label: resolveLocalizable(client.label, locale, defaultLocale),
+        }
+  );
+
+/** Whether a row opens an install link rather than copying a command. */
+const opensLink = (client: McpMenuEntry): boolean =>
+  client === "cursor" || client === "vscode";
+
+/**
+ * The menu's rows after "Copy server URL", each with whether a rule goes
+ * above it: wherever the list switches between commands to copy and install
+ * links ("Copy server URL" copies too), so the default menu keeps its one
+ * rule before Cursor.
+ */
+export const mcpMenuRows = (
+  entries: readonly McpMenuEntry[]
+): { client: McpMenuEntry; rule: boolean }[] =>
+  entries.map((client, index) => {
+    const previous = entries[index - 1];
+    return {
+      client,
+      rule:
+        opensLink(client) !== (previous !== undefined && opensLink(previous)),
+    };
+  });
+
+/** Fill a custom client's command for the server it installs. */
+export const mcpClientCommand = (
+  command: string,
+  server: { name: string; url: string }
+): string =>
+  // Replacer functions, not strings: a URL may contain `$`, which a string
+  // replacement would interpret as a substitution pattern.
+  command
+    .replaceAll("{name}", () => server.name)
+    .replaceAll("{url}", () => server.url);

package/src/core/nav-diagnostics.ts

@@ -1,6 +1,9 @@
 import { isAssetIcon } from "../theme/icon-kind.ts";
 import { hasIcon } from "../theme/icons.ts";
 import { isInternalPath } from "./base-path.ts";
+import { resolveLocalizable } from "./localizable.ts";
+import { isBuiltInMcpClient } from "./mcp-clients.ts";
+import type { McpClientEntry } from "./mcp-clients.ts";
 import { isPageRef, normalizeRef } from "./navigation.ts";
 import type { SidebarItemConfig } from "./schema.ts";
 import type { Diagnostic, NavNode, Navigation, PageRecord } from "./types.ts";
@@ -100,6 +103,28 @@ export const validateSearchPopularIcons = (
   return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
 };
 
+/**
+ * Warn about unknown icons on custom "Connect to MCP" clients
+ * (`agents.mcp.clients`), which live outside the navigation model too. A
+ * per-locale label is named in the default locale.
+ */
+export const validateMcpClientIcons = (
+  clients: readonly McpClientEntry[],
+  defaultLocale?: string
+): Diagnostic[] => {
+  const icons = clients.flatMap((client) =>
+    !isBuiltInMcpClient(client) && client.icon
+      ? [
+          {
+            icon: client.icon,
+            where: `MCP client "${resolveLocalizable(client.label, defaultLocale, defaultLocale)}"`,
+          },
+        ]
+      : []
+  );
+  return unknownIconDiagnostics(icons, ICON_FORMAT_HINT);
+};
+
 /** Whether an internal path resolves to a page or a section that has pages. */
 const resolvesToPages = (routes: Set<string>, path: string): boolean =>
   routes.has(path) || [...routes].some((route) => route.startsWith(`${path}/`));