blume 1.4.2 → 1.5.0

package/src/ai/mcp/data.ts

@@ -14,8 +14,12 @@ export interface McpRoute {
   facets?: Record<string, string>;
   indexable: boolean;
   lastModified: string | null;
+  /** Resolved locale code (the default locale when not under i18n). */
+  locale: string;
   route: string;
   title: string;
+  /** Docs version (`""` for the current docs). */
+  version: string;
 }
 
 /**
@@ -37,10 +41,20 @@ export interface McpData {
    * `search_docs` can match CJK/Thai content.
    */
   defaultLocale?: string;
+  /**
+   * Archived docs version ids, in configured order. Present only on a
+   * versioned site; its presence is what makes `search_docs`/`list_pages`
+   * default to the current docs.
+   */
+  archivedVersions?: string[];
   documents: OramaDoc[];
   instructions?: string;
   name: string;
   navigation: Navigation;
+  /** Per-locale trees for a locale-aware `get_navigation` (i18n sites only). */
+  navigationByLocale?: Record<string, Navigation>;
+  /** Per-archived-version trees, keyed by version id then locale code. */
+  navigationByVersion?: Record<string, Record<string, Navigation>>;
   pages: Record<string, string>;
   routes: McpRoute[];
   site: string | null;
@@ -79,28 +93,40 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
     }
     const page = pageById.get(route.id);
     const facets = page ? pageFacets(page, config) : undefined;
-    routes.push({
+    const entry: McpRoute = {
       contentType: route.contentType,
       description: page?.description,
-      ...(facets ? { facets } : {}),
       indexable: route.indexable,
       lastModified: route.lastModified ?? null,
+      locale: route.locale,
       route: route.path,
       title: route.title,
-    });
+      version: route.version,
+    };
+    if (facets) {
+      entry.facets = facets;
+    }
+    routes.push(entry);
   }
 
-  return {
+  const data: McpData = {
     base: normalizeBasePath(config.deployment.base),
     defaultLocale: config.i18n?.defaultLocale,
-    documents: documents.map((doc) => ({
-      content: doc.content,
-      contentType: doc.contentType,
-      description: doc.description,
-      ...(doc.facets ? { facets: doc.facets } : {}),
-      route: doc.route,
-      title: doc.title,
-    })),
+    documents: documents.map((doc) => {
+      const document: OramaDoc = {
+        content: doc.content,
+        contentType: doc.contentType,
+        description: doc.description,
+        locale: doc.locale,
+        route: doc.route,
+        title: doc.title,
+        version: doc.version,
+      };
+      if (doc.facets) {
+        document.facets = doc.facets;
+      }
+      return document;
+    }),
     instructions: config.ai.mcp.instructions,
     name: config.ai.mcp.name ?? config.title,
     navigation: graph.navigation,
@@ -109,4 +135,14 @@ export const buildMcpData = async (project: BlumeProject): Promise<McpData> => {
     site: config.deployment.site ?? null,
     version: manifest.blumeVersion,
   };
+  if (config.versions) {
+    data.archivedVersions = config.versions.archived.map(
+      (version) => version.id
+    );
+    data.navigationByVersion = graph.navigationByVersion;
+  }
+  if (config.i18n) {
+    data.navigationByLocale = graph.navigationByLocale;
+  }
+  return data;
 };

package/src/ai/mcp/discovery.ts

@@ -1,7 +1,8 @@
 import { withBasePath } from "../../core/base-path.ts";
-import { trimEnd } from "../../core/trim.ts";
-import { slugify } from "../../openapi/references.ts";
+import { absoluteUrl, siteRoot } from "../../core/site-url.ts";
+import { trimChar } from "../../core/trim.ts";
 import { MCP_TOOLS } from "./tools.ts";
+import type { McpToolMeta } from "./tools.ts";
 
 /** Inputs needed to describe the MCP server in discovery documents. */
 export interface McpDiscoveryInput {
@@ -20,16 +21,14 @@ const serverUrl = (input: McpDiscoveryInput): string => {
   const path = withBasePath(input.base, input.route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  return input.site ? `${trimEnd(input.site, "/")}${path}` : path;
+  return input.site ? absoluteUrl(input.site, path) : path;
 };
 
 /**
  * The `/.well-known/mcp.json` discovery document: the minimal pointer agents use
  * to find the server and its transport.
  */
-export const buildMcpDiscovery = (
-  input: McpDiscoveryInput
-): Record<string, unknown> => ({
+export const buildMcpDiscovery = (input: McpDiscoveryInput) => ({
   servers: [
     {
       name: input.name,
@@ -49,10 +48,29 @@ const CARD_TEXT_MAX = 100;
 const truncate = (text: string): string =>
   text.length > CARD_TEXT_MAX ? `${text.slice(0, CARD_TEXT_MAX - 1)}…` : text;
 
+// The server-card schema constrains `name` to `namespace/server` in ASCII
+// (`^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$`), so the display name cannot reuse the
+// route slugifier, which keeps Unicode letters. Decompose (NFKD) and drop
+// combining marks first so an accented name transliterates (`Café` → `cafe`)
+// instead of losing the letter.
+const NON_ASCII_SLUG = /[^a-z0-9]+/gu;
+const COMBINING_MARKS = /\p{M}+/gu;
+
+const asciiSlugify = (text: string): string =>
+  trimChar(
+    text
+      .normalize("NFKD")
+      .replace(COMBINING_MARKS, "")
+      .toLowerCase()
+      .replace(NON_ASCII_SLUG, "-"),
+    "-"
+  );
+
 /**
  * The card's identity in the schema's reverse-DNS `namespace/server` form:
  * the site hostname reversed (`useblume.dev` → `dev.useblume`), or
- * `localhost` when no site is configured, plus the slugged display name.
+ * `localhost` when no site is configured, plus the slugged display name (an
+ * entirely non-ASCII name falls back to `docs`).
  */
 const reverseDnsName = (input: McpDiscoveryInput): string => {
   let namespace = "localhost";
@@ -66,7 +84,7 @@ const reverseDnsName = (input: McpDiscoveryInput): string => {
       // Not a parsable URL; the local namespace is honest enough.
     }
   }
-  return `${namespace}/${slugify(input.name) || "docs"}`;
+  return `${namespace}/${asciiSlugify(input.name) || "docs"}`;
 };
 
 const HTTP_URL = /^https?:\/\//u;
@@ -83,20 +101,32 @@ const HTTP_URL = /^https?:\/\//u;
  * excludes primitives for. Full input schemas are served live via
  * `tools/list`.
  */
-export const buildMcpServerCard = (
-  input: McpDiscoveryInput
-): Record<string, unknown> => {
+export interface McpServerCard {
+  $schema: string;
+  capabilities: { tools: { listChanged: boolean } };
+  description: string;
+  name: string;
+  /** Absolute endpoints only — present when a `site` is configured. */
+  remotes?: { type: string; url: string }[];
+  serverInfo: { name: string; version: string };
+  title: string;
+  tools: McpToolMeta[];
+  transport: string;
+  transports: { endpoint: string; type: string }[];
+  url: string;
+  version: string;
+  websiteUrl?: string;
+}
+
+export const buildMcpServerCard = (input: McpDiscoveryInput): McpServerCard => {
   const url = serverUrl(input);
-  return {
+  const card: McpServerCard = {
     $schema: SERVER_CARD_SCHEMA,
     capabilities: { tools: { listChanged: false } },
     description: truncate(
       `Model Context Protocol server for the ${input.name} documentation.`
     ),
     name: reverseDnsName(input),
-    ...(HTTP_URL.test(url)
-      ? { remotes: [{ type: "streamable-http", url }] }
-      : {}),
     serverInfo: { name: input.name, version: input.version },
     title: truncate(input.name),
     tools: MCP_TOOLS.map((tool) => ({
@@ -109,6 +139,12 @@ export const buildMcpServerCard = (
     transports: [{ endpoint: url, type: "streamable-http" }],
     url,
     version: input.version,
-    ...(input.site ? { websiteUrl: trimEnd(input.site, "/") } : {}),
   };
+  if (HTTP_URL.test(url)) {
+    card.remotes = [{ type: "streamable-http", url }];
+  }
+  if (input.site) {
+    card.websiteUrl = siteRoot(input.site);
+  }
+  return card;
 };