Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

24.1 KB
Raw Blame
/**
 * The one MCP tool reference renderer shared by `cua mcp`, `cua-driver mcp`
 * and Lume's MCP server.
 *
 * Layout:
 *
 * - folder mode (`reference/mcp-tools/`): `index.mdx` (curated header, then
 *   one table per category listing every tool with its one-line summary; each
 *   row carries the tool's anchor so old `mcp-tools#<tool>` links still land)
 *   and one page per category;
 * - single-page mode (`reference/mcp-tools.mdx`) for small servers.
 *
 * Each tool: a heading anchored by its name (`#get_window_state`), the
 * description, one facts line (effect, permission, platforms), a parameters
 * table (`Parameter | Type | Default | Description`, required parameters show
 * `required`, one anchor per parameter: `#get_window_state--pid`) and minimal
 * example arguments built from the schema and validated against it.
 */

import { codeCell, codeFence, escapeMdxText, escapeTableCell, metaJson, renderPage, slug, stableJson } from './mdx';
import { firstSentence, sentence } from './cli-mdx';

export interface JsonSchema {
  type?: string | string[];
  description?: string;
  enum?: unknown[];
  const?: unknown;
  items?: JsonSchema;
  oneOf?: JsonSchema[];
  anyOf?: JsonSchema[];
  properties?: Record<string, JsonSchema>;
  required?: string[];
  additionalProperties?: boolean | JsonSchema;
  default?: unknown;
  deprecated?: boolean;
  format?: string;
  minimum?: number;
  maximum?: number;
  minItems?: number;
  maxItems?: number;
  minLength?: number;
  maxLength?: number;
  /** Renderer-only: the platforms that accept this parameter, when not all. */
  'x-platforms'?: string[];
}

export interface McpToolEntry {
  name: string;
  description: string;
  /** Category slug. */
  category: string;
  input_schema: JsonSchema;
  /** Longer usage notes after the description. */
  instructions?: string;
  annotations?: { read_only?: boolean; destructive?: boolean; idempotent?: boolean };
  permission?: string;
  /** Platforms that serve the tool, when not all of the server's platforms. */
  platforms?: string[];
  /** Extra `Label: value` facts (providers, metering, SDK symbol). */
  facts?: Array<[string, string]>;
  notes?: string[];
  /**
   * Per-platform variants when the tool's text or schema differs by platform:
   * rendered as synced platform tabs (a platform without the tool says so).
   */
  variants?: McpToolVariant[];
}

export interface McpToolVariant {
  platform: string;
  description: string;
  instructions?: string;
  input_schema: JsonSchema;
}

export interface McpCategory {
  slug: string;
  title: string;
  summary: string;
  /** Curated Markdown under the category heading. */
  intro?: string;
  /**
   * The canonical entry of each tool when another generated reference owns
   * it (the Spaces contract): the category page is then a short table linking
   * there, with the tool anchors kept, instead of repeating the entries.
   */
  canonical?: (tool: string) => string;
  /** With `canonical`: the canonical page section a tool belongs to, one heading per section. */
  canonicalSection?: (tool: string) => { title: string; href: string };
}

export interface McpReference {
  /** Docs product folder (`cua-cli`). */
  product: string;
  /** How the server starts, e.g. `cua mcp`. */
  server: string;
  generator: string;
  source: string;
  version?: string;
  description: string;
  categories: McpCategory[];
  tools: McpToolEntry[];
  /** Curated Markdown at the top of the index (or the single page). */
  header?: string;
  /** Curated Markdown sections after the tool index (for example permissions). */
  footer?: string;
  /** One page for every tool instead of a folder of category pages. */
  singlePage?: boolean;
  /**
   * Folder mode: group categories onto fewer pages (each category a section
   * of its page). Without it, every category gets its own page.
   */
  pages?: McpPage[];
  /** Every platform the server runs on, in tab order (for per-platform variants). */
  platforms?: string[];
}

/** A page of the folder-mode reference holding several categories. */
export interface McpPage {
  slug: string;
  title: string;
  summary: string;
  /** Category slugs on this page, in order. */
  categories: string[];
}

// ---------------------------------------------------------------- schema

/** A reader-facing type label for a JSON Schema. */
export function schemaType(s: JsonSchema): string {
  const alts = s.oneOf ?? s.anyOf;
  if (alts?.length) {
    const labels = alts
      .filter((a) => a.type !== 'null')
      .flatMap((a) => (a.oneOf?.length ? a.oneOf : [a]))
      .map((a) => {
        const kind = a.properties?.kind?.const;
        return typeof kind === 'string' ? `${kind} target` : schemaType(a);
      });
    return [...new Set(labels)].join(' | ');
  }
  if (s.const !== undefined) return JSON.stringify(s.const);
  if (s.enum?.length) return s.enum.map((v) => JSON.stringify(v)).join(' | ');
  const types = (Array.isArray(s.type) ? s.type : [s.type ?? 'any']).filter((t) => t !== 'null');
  return types
    .map((t) => {
      if (t === 'array') return `${schemaType(s.items ?? {})}[]`;
      if (t === 'object' && s.additionalProperties && typeof s.additionalProperties === 'object')
        return `map of ${schemaType(s.additionalProperties)}`;
      return t;
    })
    .join(' | ');
}

function describe(prop: JsonSchema): string {
  if (prop.description) return prop.description;
  for (const alt of prop.anyOf ?? prop.oneOf ?? []) {
    const nested = describe(alt);
    if (nested) return nested;
  }
  return '';
}

function constraints(prop: JsonSchema): string[] {
  const out: string[] = [];
  if (prop.minimum !== undefined || prop.maximum !== undefined) {
    if (prop.minimum !== undefined && prop.maximum !== undefined)
      out.push(`Range: ${prop.minimum} to ${prop.maximum}.`);
    else if (prop.minimum !== undefined) out.push(`Minimum: ${prop.minimum}.`);
    else out.push(`Maximum: ${prop.maximum}.`);
  }
  if (prop.minItems !== undefined || prop.maxItems !== undefined) {
    out.push(`Items: ${prop.minItems ?? 0} to ${prop.maxItems ?? 'any'}.`);
  }
  if (prop.deprecated) out.push('Deprecated.');
  if (prop['x-platforms']?.length) out.push(`${prop['x-platforms'].join(', ')} only.`);
  return out;
}

function paramRows(
  tool: string,
  schema: JsonSchema,
  prefix = '',
  parentRequired = true
): string[] {
  // `tool` is the anchor prefix: `click` or, inside a platform tab, `click--linux`.
  const required = new Set(schema.required ?? []);
  const rows: string[] = [];
  for (const [name, prop] of Object.entries(schema.properties ?? {})) {
    const full = prefix ? `${prefix}.${name}` : name;
    const isRequired = parentRequired && required.has(name);
    const def = isRequired
      ? 'required'
      : prop.default !== undefined
        ? codeCell(JSON.stringify(prop.default))
        : '';
    const desc = [escapeTableCell(sentence(describe(prop))), ...constraints(prop)].filter(Boolean).join(' ');
    const anchor = `<span id="${tool}--${slug(full.replace(/\./g, '-'))}"></span>`;
    rows.push(`| ${anchor}${codeCell(full)} | ${codeCell(schemaType(prop))} | ${def} | ${desc} |`);
    // One level of nested object fields (not unions, not maps).
    if (!prefix && prop.properties && !prop.oneOf && !prop.anyOf) {
      rows.push(...paramRows(tool, prop, full, isRequired));
    }
  }
  return rows;
}

function paramsTable(anchor: string, schema: JsonSchema): string[] {
  const rows = paramRows(anchor, schema);
  if (!rows.length) return ['No parameters.', ''];
  return ['| Parameter | Type | Default | Description |', '| --- | --- | --- | --- |', ...rows, ''];
}

// ---------------------------------------------------------------- examples

function sampleValue(name: string, prop: JsonSchema): unknown {
  if (prop.default !== undefined) return prop.default;
  if (prop.const !== undefined) return prop.const;
  if (prop.enum?.length) return prop.enum[0];
  const alt = (prop.oneOf ?? prop.anyOf)?.find((a) => a.type !== 'null');
  if (alt) return sampleValue(name, alt);
  const type = Array.isArray(prop.type) ? prop.type.find((t) => t !== 'null') : prop.type;
  switch (type) {
    case 'integer':
    case 'number': {
      const n = /(^|_)(x|x1|x2|from_x|to_x)$/.test(name) ? 100 : /(^|_)(y|y1|y2|from_y|to_y)$/.test(name) ? 200 : 1;
      if (prop.minimum !== undefined && n < prop.minimum) return prop.minimum;
      if (prop.maximum !== undefined && n > prop.maximum) return prop.maximum;
      return n;
    }
    case 'boolean':
      return false;
    case 'array': {
      const count = Math.max(prop.minItems ?? 1, 1);
      return Array.from({ length: count }, () => sampleValue(name.replace(/s$/, ''), prop.items ?? {}));
    }
    case 'object': {
      const obj: Record<string, unknown> = {};
      for (const key of prop.required ?? []) obj[key] = sampleValue(key, prop.properties?.[key] ?? {});
      return obj;
    }
    default:
      return `<${name}>`;
  }
}

/** Why `value` does not satisfy `schema` (the subset the samples use), or null. */
export function validate(value: unknown, schema: JsonSchema): string | null {
  const alts = schema.oneOf ?? schema.anyOf;
  if (alts?.length) return alts.some((a) => validate(value, a) === null) ? null : 'no alternative matches';
  if (schema.const !== undefined && value !== schema.const) return `must be ${JSON.stringify(schema.const)}`;
  if (schema.enum && !schema.enum.includes(value)) return 'not in enum';
  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
  if (types.length) {
    const actual = Array.isArray(value)
      ? 'array'
      : value === null
        ? 'null'
        : Number.isInteger(value)
          ? 'integer'
          : typeof value;
    const ok = types.some((t) => t === actual || (t === 'number' && actual === 'integer'));
    if (!ok) return `expected ${types.join('|')}, got ${actual}`;
  }
  if (typeof value === 'number') {
    if (schema.minimum !== undefined && value < schema.minimum) return 'below minimum';
    if (schema.maximum !== undefined && value > schema.maximum) return 'above maximum';
  }
  if (Array.isArray(value)) {
    if (schema.minItems !== undefined && value.length < schema.minItems) return 'too few items';
    for (const item of value) {
      const why = schema.items ? validate(item, schema.items) : null;
      if (why) return `item: ${why}`;
    }
  }
  if (value && typeof value === 'object' && !Array.isArray(value)) {
    for (const key of schema.required ?? []) {
      if (!(key in (value as object))) return `missing ${key}`;
    }
    for (const [key, v] of Object.entries(value as object)) {
      const sub = schema.properties?.[key];
      const why = sub ? validate(v, sub) : null;
      if (why) return `${key}: ${why}`;
    }
  }
  return null;
}

/** Minimal arguments (required parameters only), or null when none are required. */
export function exampleArguments(name: string, schema: JsonSchema): Record<string, unknown> | null {
  const required = schema.required ?? [];
  if (!required.length) return null;
  const args: Record<string, unknown> = {};
  for (const key of required) args[key] = sampleValue(key, schema.properties?.[key] ?? {});
  const why = validate(args, schema);
  if (why) throw new Error(`example arguments for ${name} do not match its schema: ${why}`);
  return args;
}

// ---------------------------------------------------------------- pages

function effect(a: McpToolEntry['annotations']): string | null {
  if (!a) return null;
  const kind = a.read_only ? 'read-only' : a.destructive ? 'destructive' : 'mutating';
  return `${kind}${a.idempotent ? ', idempotent' : ''}`;
}

function toolBody(anchor: string, name: string, v: { description: string; instructions?: string; input_schema: JsonSchema }, notes: string[] = []): string[] {
  const lines = [escapeMdxText(sentence(v.description)), ''];
  if (v.instructions) lines.push(escapeMdxText(v.instructions), '');
  lines.push(...paramsTable(anchor, v.input_schema));
  const args = exampleArguments(name, v.input_schema);
  if (args) lines.push('**Example arguments**', '', codeFence('json', JSON.stringify(args)), '');
  for (const note of notes) lines.push(`Note: ${escapeMdxText(sentence(note))}`, '');
  return lines;
}

function platformKey(platform: string): string {
  return slug(platform);
}

/** Whether the variants differ in anything the page shows. */
function variantsDiffer(variants: McpToolVariant[]): boolean {
  const key = (v: McpToolVariant) => stableJson([v.description, v.instructions ?? '', v.input_schema]);
  return new Set(variants.map(key)).size > 1;
}

export function toolSection(tool: McpToolEntry, level: number, allPlatforms: string[] = []): string[] {
  const lines = [`${'#'.repeat(level)} \`${tool.name}\``, ''];
  const facts: string[] = [];
  const e = effect(tool.annotations);
  if (e) facts.push(`Effect: ${e}.`);
  if (tool.permission) facts.push(`Permission: \`${tool.permission}\`.`);
  if (tool.platforms?.length) facts.push(`Platforms: ${tool.platforms.join(', ')}.`);
  for (const [label, value] of tool.facts ?? []) facts.push(`${label}: ${value}.`);
  const variants = tool.variants ?? [];
  if (variants.length > 1 && variantsDiffer(variants)) {
    if (facts.length) lines.push(facts.join(' '), '');
    // Parameters with the same schema on every platform are listed once, after
    // the tabs; each tab keeps its description and the parameters that differ.
    const props = variants.map((v) => v.input_schema.properties ?? {});
    const common = Object.keys(props[0]).filter((name) =>
      props.every((p) => p[name] !== undefined && stableJson(p[name]) === stableJson(props[0][name]))
    );
    const requiredEverywhere = (name: string) => variants.every((v) => (v.input_schema.required ?? []).includes(name));
    const subset = (schema: JsonSchema, keep: (name: string) => boolean): JsonSchema => ({
      ...schema,
      properties: Object.fromEntries(Object.entries(schema.properties ?? {}).filter(([n]) => keep(n))),
      required: (schema.required ?? []).filter(keep),
    });
    const tabs = allPlatforms.length ? allPlatforms : variants.map((v) => v.platform);
    lines.push(`<Tabs items={[${tabs.map((p) => `'${p}'`).join(', ')}]} groupId="platform" persist>`);
    for (const platform of tabs) {
      const v = variants.find((x) => x.platform === platform);
      lines.push(`<Tab value="${platform}">`, '');
      if (!v) {
        lines.push(`Not available on ${platform}.`, '', '</Tab>');
        continue;
      }
      lines.push(escapeMdxText(sentence(v.description)), '');
      if (v.instructions) lines.push(escapeMdxText(v.instructions), '');
      const own = subset(v.input_schema, (n) => !common.includes(n));
      if (Object.keys(own.properties ?? {}).length) {
        lines.push(`**${common.length ? `${platform} parameters` : 'Parameters'}**`, '');
        lines.push(...paramsTable(`${tool.name}--${platformKey(platform)}`, own));
      }
      lines.push('</Tab>');
    }
    lines.push('</Tabs>', '');
    if (common.length) {
      const shared = subset(variants[0].input_schema, (n) => common.includes(n) && (requiredEverywhere(n) || !(variants[0].input_schema.required ?? []).includes(n)));
      shared.required = common.filter(requiredEverywhere);
      lines.push(`**Parameters on every platform**`, '');
      lines.push(...paramsTable(tool.name, { ...shared, properties: Object.fromEntries(common.map((n) => [n, props[0][n]])) }));
    }
    let args: Record<string, unknown> | null = null;
    try {
      args = exampleArguments(tool.name, variants[0].input_schema);
      for (const v of variants.slice(1)) if (args && validate(args, v.input_schema)) args = null;
    } catch {
      args = null;
    }
    if (args) lines.push('**Example arguments**', '', codeFence('json', JSON.stringify(args)), '');
    for (const note of tool.notes ?? []) lines.push(`Note: ${escapeMdxText(sentence(note))}`, '');
    return lines;
  }
  const only = variants[0] ?? tool;
  lines.push(escapeMdxText(sentence(only.description)), '');
  if (only.instructions) lines.push(escapeMdxText(only.instructions), '');
  if (facts.length) lines.push(facts.join(' '), '');
  lines.push(...paramsTable(tool.name, only.input_schema));
  const args = exampleArguments(tool.name, only.input_schema);
  if (args) lines.push('**Example arguments**', '', codeFence('json', JSON.stringify(args)), '');
  for (const note of tool.notes ?? []) lines.push(`Note: ${escapeMdxText(sentence(note))}`, '');
  return lines;
}

function mcpUrl(ref: McpReference, page?: string): string {
  return `/${ref.product}/reference/mcp-tools${page ? `/${page}` : ''}`;
}

function byCategory(ref: McpReference): Map<string, McpToolEntry[]> {
  const known = new Set(ref.categories.map((c) => c.slug));
  const stray = ref.tools.filter((t) => !known.has(t.category)).map((t) => t.name);
  if (stray.length) throw new Error(`MCP tools without a category: ${stray.join(', ')}`);
  const names = ref.tools.map((t) => t.name);
  const dupes = names.filter((n, i) => names.indexOf(n) !== i);
  if (dupes.length) throw new Error(`duplicate MCP tools: ${dupes.join(', ')}`);
  return new Map(ref.categories.map((c) => [c.slug, ref.tools.filter((t) => t.category === c.slug)]));
}

function indexTable(tools: McpToolEntry[], href: (tool: string) => string, withPlatforms: boolean): string[] {
  const lines = withPlatforms
    ? ['| Tool | Description | Platforms |', '| --- | --- | --- |']
    : ['| Tool | Description |', '| --- | --- |'];
  for (const tool of tools) {
    const cell = `<span id="${tool.name}"></span>[\`${tool.name}\`](${href(tool.name)})`;
    const desc = escapeTableCell(firstSentence(tool.description));
    lines.push(withPlatforms ? `| ${cell} | ${desc} | ${tool.platforms?.join(', ') ?? 'all'} |` : `| ${cell} | ${desc} |`);
  }
  return [...lines, ''];
}

/**
 * Renders the MCP reference, keyed by path relative to the product's
 * `reference/` folder (`mcp-tools/index.mdx`, ... or `mcp-tools.mdx`).
 */
export function renderMcpReference(ref: McpReference): Map<string, string> {
  const groups = byCategory(ref);
  const withPlatforms = ref.tools.some((t) => t.platforms?.length);
  const out = new Map<string, string>();
  const page = (title: string, description: string, body: string[]) => {
    const text = body.join('\n');
    return renderPage({
      title,
      description,
      generator: ref.generator,
      source: ref.source,
      version: ref.version,
      components: text.includes('<Tabs ') ? ['Tabs'] : [],
      body: text,
    });
  };
  const all = ref.platforms ?? [];

  if (ref.singlePage) {
    out.set('mcp-tools.mdx', page('MCP tools', ref.description, mcpBody(ref, 2)));
    return out;
  }

  const pages = mcpPages(ref);
  const pageOf = new Map(pages.flatMap((p) => p.categories.map((c) => [c, p.slug] as const)));
  const index: string[] = [];
  if (ref.header) index.push(ref.header.trim(), '');
  for (const cat of ref.categories) {
    const tools = groups.get(cat.slug) ?? [];
    if (!tools.length) continue;
    const at = pageOf.get(cat.slug)!;
    const catHref = ref.pages ? `${mcpUrl(ref, at)}#${slug(cat.title)}` : mcpUrl(ref, at);
    index.push(`## ${cat.title}`, '', `${escapeMdxText(sentence(cat.summary))} [Reference](${catHref}).`, '');
    index.push(...indexTable(tools, cat.canonical ?? ((t) => `${mcpUrl(ref, at)}#${t}`), withPlatforms));
  }
  if (ref.footer) index.push(ref.footer.trim(), '');
  out.set('mcp-tools/index.mdx', page('All tools', ref.description, index));

  const slugs: string[] = [];
  for (const p of pages) {
    const cats = p.categories
      .map((c) => ref.categories.find((x) => x.slug === c)!)
      .filter((cat) => (groups.get(cat.slug) ?? []).length);
    if (!cats.length) continue;
    slugs.push(p.slug);
    const body: string[] = [];
    // One category per page: its tools are the page's sections. Several: each
    // category is a section and its tools sit one level below.
    const level = ref.pages ? 3 : 2;
    if (ref.pages) {
      const listed = cats.flatMap((cat) => (cat.canonical ? [] : groups.get(cat.slug)!));
      if (listed.length > 1) body.push(...indexTable(listed, (t) => `#${t}`, withPlatforms).map((l) => l.replace(/<span id="[^"]*"><\/span>/, '')));
    }
    body.push(`Served by \`${ref.server}\`; see [MCP tools](${mcpUrl(ref)}) for every tool.`, '');
    for (const cat of cats) {
      const tools = groups.get(cat.slug)!;
      if (ref.pages) body.push(`## ${cat.title}`, '', escapeMdxText(sentence(cat.summary)), '');
      if (cat.canonical) {
        body.push(...canonicalTables(cat, tools, withPlatforms, ref.pages ? 3 : 2));
        continue;
      }
      if (!ref.pages && tools.length > 1) body.push(...indexTable(tools, (t) => `#${t}`, withPlatforms).map((l) => l.replace(/<span id="[^"]*"><\/span>/, '')));
      if (cat.intro) body.push(cat.intro.trim(), '');
      for (const tool of tools) body.push(...toolSection(tool, level, all));
    }
    out.set(`mcp-tools/${p.slug}.mdx`, page(p.title, sentence(p.summary), body));
  }
  out.set('mcp-tools/meta.json', metaJson('MCP tools', ['index', ...slugs]));
  return out;
}

/** The folder-mode pages: the configured groups, or one page per category. */
function mcpPages(ref: McpReference): McpPage[] {
  if (!ref.pages) return ref.categories.map((c) => ({ slug: c.slug, title: c.title, summary: c.summary, categories: [c.slug] }));
  const placed = ref.pages.flatMap((p) => p.categories);
  const known = ref.categories.map((c) => c.slug);
  const left = known.filter((c) => !placed.includes(c));
  const stray = placed.filter((c, i) => !known.includes(c) || placed.indexOf(c) !== i);
  if (left.length || stray.length) {
    throw new Error(`MCP pages of ${ref.server} do not cover the categories once. Unplaced: ${left.join(', ') || 'none'}; unknown or repeated: ${stray.join(', ') || 'none'}`);
  }
  return ref.pages;
}

/** A canonical category: tables linking to where each tool is documented, tool anchors kept. */
function canonicalTables(cat: McpCategory, tools: McpToolEntry[], withPlatforms: boolean, level: number): string[] {
  const body: string[] = [];
  if (cat.intro) body.push(cat.intro.trim(), '');
  const sections = new Map<string, { href: string; tools: McpToolEntry[] }>();
  for (const tool of tools) {
    const sec = cat.canonicalSection?.(tool.name) ?? { title: '', href: '' };
    const entry = sections.get(sec.title) ?? { href: sec.href, tools: [] };
    entry.tools.push(tool);
    sections.set(sec.title, entry);
  }
  for (const [title, sec] of sections) {
    if (title) body.push(`${'#'.repeat(level)} ${title}`, '', `Full entries: [${title}](${sec.href}).`, '');
    body.push(...indexTable(sec.tools, cat.canonical!, withPlatforms));
  }
  return body;
}

/**
 * The whole tool reference as one body: header, one section per category
 * (canonical categories as linking tables), tools a level below, footer.
 * `level` is the category heading level.
 */
export function mcpBody(ref: McpReference, level: number): string[] {
  const groups = byCategory(ref);
  const withPlatforms = ref.tools.some((t) => t.platforms?.length);
  const body: string[] = [];
  if (ref.header) body.push(ref.header.trim(), '');
  for (const cat of ref.categories) {
    const tools = groups.get(cat.slug) ?? [];
    if (!tools.length) continue;
    body.push(`${'#'.repeat(level)} ${cat.title}`, '');
    if (cat.canonical) {
      body.push(escapeMdxText(sentence(cat.summary)), '');
      body.push(...canonicalTables(cat, tools, withPlatforms, level + 1));
      continue;
    }
    if (cat.intro) body.push(cat.intro.trim(), '');
    for (const tool of tools) body.push(...toolSection(tool, level + 1, ref.platforms ?? []));
  }
  if (ref.footer) body.push(ref.footer.trim(), '');
  return body;
}

/** Rows for a product Reference index: one per MCP category. */
export function mcpIndexRows(ref: McpReference): Array<{ name: string; href: string; description: string }> {
  const groups = byCategory(ref);
  if (ref.singlePage) {
    return [{ name: 'MCP tools', href: mcpUrl(ref).replace(/\/mcp-tools$/, '/mcp-tools'), description: ref.description }];
  }
  return [
    { name: 'All tools', href: mcpUrl(ref), description: `Every \`${ref.server}\` tool with a one-line summary.` },
    ...mcpPages(ref)
      .map((p) => ({ p, count: p.categories.reduce((n, c) => n + (groups.get(c)?.length ?? 0), 0) }))
      .filter(({ count }) => count)
      .map(({ p, count }) => ({
        name: p.title,
        href: mcpUrl(ref, p.slug),
        description: `${sentence(p.summary)} ${count} tools.`,
      })),
  ];
}