@primer/mcp 0.2.0 → 0.3.1

package/dist/server-owUZMSeG.js

@@ -0,0 +1,1525 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import * as cheerio from 'cheerio';
+import * as z from 'zod';
+import TurndownService from 'turndown';
+import componentsMetadata from '@primer/react/generated/components.json' with { type: 'json' };
+import octicons from '@primer/octicons/build/data.json' with { type: 'json' };
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { spawn } from 'child_process';
+import baseMotion from '@primer/primitives/dist/docs/base/motion/motion.json' with { type: 'json' };
+import baseSize from '@primer/primitives/dist/docs/base/size/size.json' with { type: 'json' };
+import baseTypography from '@primer/primitives/dist/docs/base/typography/typography.json' with { type: 'json' };
+import functionalSizeBorder from '@primer/primitives/dist/docs/functional/size/border.json' with { type: 'json' };
+import functionalSizeCoarse from '@primer/primitives/dist/docs/functional/size/size-coarse.json' with { type: 'json' };
+import functionalSizeFine from '@primer/primitives/dist/docs/functional/size/size-fine.json' with { type: 'json' };
+import functionalSize from '@primer/primitives/dist/docs/functional/size/size.json' with { type: 'json' };
+import light from '@primer/primitives/dist/docs/functional/themes/light.json' with { type: 'json' };
+import functionalTypography from '@primer/primitives/dist/docs/functional/typography/typography.json' with { type: 'json' };
+
+function idToSlug(id) {
+  if (id === 'actionbar') {
+    return 'action-bar';
+  }
+  if (id === 'tooltip-v2') {
+    return 'tooltip';
+  }
+  if (id === 'dialog_v2') {
+    return 'dialog';
+  }
+  return id.replaceAll('_', '-');
+}
+const components = Object.entries(componentsMetadata.components).map(([id, component]) => {
+  return {
+    id,
+    name: component.name,
+    importPath: component.importPath,
+    slug: idToSlug(id)
+  };
+});
+function listComponents() {
+  return components;
+}
+const patterns = [{
+  id: 'data-visualization',
+  name: 'Data Visualization'
+}, {
+  id: 'degraded-experiences',
+  name: 'Degraded Experiences'
+}, {
+  id: 'empty-states',
+  name: 'Empty States'
+}, {
+  id: 'feature-onboarding',
+  name: 'Feature Onboarding'
+}, {
+  id: 'forms',
+  name: 'Forms'
+}, {
+  id: 'loading',
+  name: 'Loading'
+}, {
+  id: 'navigation',
+  name: 'Navigation'
+}, {
+  id: 'notification-messaging',
+  name: 'Notification message'
+}, {
+  id: 'progressive-disclosure',
+  name: 'Progressive disclosure'
+}, {
+  id: 'saving',
+  name: 'Saving'
+}];
+function listPatterns() {
+  return patterns;
+}
+const icons = Object.values(octicons).map(icon => {
+  return {
+    name: icon.name,
+    keywords: icon.keywords,
+    heights: Object.keys(icon.heights)
+  };
+});
+function listIcons() {
+  return icons;
+}
+
+// radius.json may not exist in all versions of @primer/primitives
+let functionalSizeRadius = {};
+try {
+  const require = createRequire(import.meta.url);
+  const radiusPath = require.resolve('@primer/primitives/dist/docs/functional/size/radius.json');
+  functionalSizeRadius = JSON.parse(readFileSync(radiusPath, 'utf-8'));
+} catch {
+  // radius.json not available in this version of @primer/primitives
+}
+const categories = {
+  base: {
+    motion: Object.values(baseMotion).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    }),
+    size: Object.values(baseSize).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    }),
+    typography: Object.values(baseTypography).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    })
+  },
+  functional: {
+    border: Object.values(functionalSizeBorder).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    }),
+    radius: Object.values(functionalSizeRadius).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    }),
+    sizeCoarse: Object.values(functionalSizeCoarse).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    }),
+    sizeFine: Object.values(functionalSizeFine).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    }),
+    size: Object.values(functionalSize).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    }),
+    themes: {
+      light: Object.values(light).map(token => {
+        return {
+          name: token.name,
+          type: token.type,
+          value: token.value
+        };
+      })
+    },
+    typography: Object.values(functionalTypography).map(token => {
+      return {
+        name: token.name,
+        type: token.type,
+        value: token.value
+      };
+    })
+  }
+};
+const tokens = [...categories.base.motion, ...categories.base.size, ...categories.base.typography, ...categories.functional.border, ...categories.functional.radius, ...categories.functional.sizeCoarse, ...categories.functional.sizeFine, ...categories.functional.size, ...categories.functional.themes.light, ...categories.functional.typography];
+
+// Semantic group prefixes that apply to any element
+const SEMANTIC_PREFIXES = ['bgColor', 'fgColor', 'border', 'borderColor', 'shadow', 'focus', 'color', 'animation', 'duration'];
+function listTokenGroups() {
+  // Use the full token set so non-theme groups (stack, text, borderRadius, etc.) are included
+  const allTokens = tokens;
+
+  // Group tokens by their first segment
+  const groupMap = new Map();
+  for (const token of allTokens) {
+    const parts = token.name.split('-');
+    const prefix = parts[0];
+    if (!groupMap.has(prefix)) {
+      groupMap.set(prefix, {
+        count: 0,
+        subGroups: new Set()
+      });
+    }
+    const group = groupMap.get(prefix);
+    group.count++;
+
+    // For component tokens, track sub-groups (e.g., button-bgColor -> bgColor)
+    if (!SEMANTIC_PREFIXES.includes(prefix) && parts.length > 1) {
+      const subGroup = parts[1];
+      if (SEMANTIC_PREFIXES.includes(subGroup)) {
+        group.subGroups.add(subGroup);
+      }
+    }
+  }
+  const semantic = [];
+  const component = [];
+  for (const [name, data] of groupMap.entries()) {
+    const group = {
+      name,
+      count: data.count
+    };
+    if (data.subGroups.size > 0) {
+      group.subGroups = Array.from(data.subGroups).sort();
+    }
+    if (SEMANTIC_PREFIXES.includes(name)) {
+      semantic.push(group);
+    } else {
+      component.push(group);
+    }
+  }
+
+  // Sort by count descending
+  semantic.sort((a, b) => b.count - a.count);
+  component.sort((a, b) => b.count - a.count);
+  return {
+    semantic,
+    component
+  };
+}
+
+// Token with guidelines from markdown
+
+// Parse design tokens spec from new DESIGN_TOKENS_SPEC.md format
+function parseDesignTokensSpec(markdown) {
+  const results = [];
+  const lines = markdown.split('\n');
+  let currentGroup = '';
+  let currentToken = null;
+  let descriptionLines = [];
+  for (const line of lines) {
+    // Match group headings (## heading)
+    const groupMatch = line.match(/^## (.+)$/);
+    if (groupMatch) {
+      // Save previous token if exists
+      if (currentToken?.name) {
+        results.push({
+          name: currentToken.name,
+          value: getTokenValue(currentToken.name),
+          useCase: currentToken.useCase || descriptionLines.join(' '),
+          rules: currentToken.rules || '',
+          group: currentToken.group || ''
+        });
+        descriptionLines = [];
+      }
+      currentGroup = groupMatch[1].trim();
+      currentToken = null;
+      continue;
+    }
+
+    // Match token name (### tokenName)
+    const tokenMatch = line.match(/^### (.+)$/);
+    if (tokenMatch) {
+      // Save previous token if exists
+      if (currentToken?.name) {
+        results.push({
+          name: currentToken.name,
+          value: getTokenValue(currentToken.name),
+          useCase: currentToken.useCase || descriptionLines.join(' '),
+          rules: currentToken.rules || '',
+          group: currentToken.group || ''
+        });
+      }
+      descriptionLines = [];
+      currentToken = {
+        name: tokenMatch[1].trim(),
+        group: currentGroup
+      };
+      continue;
+    }
+
+    // Match new format usage line (**U:**)
+    const newUsageMatch = line.match(/^\*\*U:\*\*\s*(.+)$/);
+    if (newUsageMatch && currentToken) {
+      currentToken.useCase = newUsageMatch[1].trim();
+      continue;
+    }
+
+    // Match new format rules line (**R:**)
+    const newRulesMatch = line.match(/^\*\*R:\*\*\s*(.+)$/);
+    if (newRulesMatch && currentToken) {
+      currentToken.rules = newRulesMatch[1].trim();
+      continue;
+    }
+
+    // Description line (line after token name, before U:/R:)
+    if (currentToken && !currentToken.useCase && !line.startsWith('**') && line.trim() && !line.startsWith('#')) {
+      descriptionLines.push(line.trim());
+    }
+  }
+
+  // Don't forget the last token
+  if (currentToken?.name) {
+    results.push({
+      name: currentToken.name,
+      value: getTokenValue(currentToken.name),
+      useCase: currentToken.useCase || descriptionLines.join(' '),
+      rules: currentToken.rules || '',
+      group: currentToken.group || ''
+    });
+  }
+  return results;
+}
+
+// Get token value from the loaded tokens
+function getTokenValue(tokenName) {
+  const found = tokens.find(token => token.name === tokenName);
+  return found ? String(found.value) : '';
+}
+
+// Human-readable display labels for canonical group prefixes
+const GROUP_LABELS = {
+  bgColor: 'Background Color',
+  fgColor: 'Foreground Color',
+  borderColor: 'Border Color',
+  border: 'Border',
+  shadow: 'Shadow',
+  focus: 'Focus',
+  color: 'Color',
+  borderWidth: 'Border Width',
+  borderRadius: 'Border Radius',
+  boxShadow: 'Box Shadow',
+  controlStack: 'Control Stack',
+  fontStack: 'Font Stack',
+  outline: 'Outline',
+  text: 'Text',
+  control: 'Control',
+  overlay: 'Overlay',
+  stack: 'Stack',
+  spinner: 'Spinner'
+};
+
+// Get canonical group prefix from token name
+function getGroupFromName(name) {
+  return name.split('-')[0];
+}
+
+// Build complete token list from JSON (includes all tokens, not just those with guidelines)
+function buildAllTokens(guidelinesTokens) {
+  const guidelinesMap = new Map(guidelinesTokens.map(t => [t.name, t]));
+
+  // Include theme tokens AND size/typography/border tokens
+  const allSourceTokens = [...categories.base.motion, ...categories.base.size, ...categories.base.typography, ...categories.functional.themes.light, ...categories.functional.size, ...categories.functional.sizeCoarse, ...categories.functional.sizeFine, ...categories.functional.border, ...categories.functional.radius, ...categories.functional.typography];
+  const allTokens = [];
+  const seen = new Set();
+  for (const token of allSourceTokens) {
+    if (seen.has(token.name)) continue;
+    seen.add(token.name);
+    const existing = guidelinesMap.get(token.name);
+    if (existing) {
+      allTokens.push(existing);
+    } else {
+      allTokens.push({
+        name: token.name,
+        value: String(token.value),
+        useCase: '',
+        rules: '',
+        group: getGroupFromName(token.name)
+      });
+    }
+  }
+  return allTokens;
+}
+
+// Expand token patterns like [accent, danger] into multiple tokens
+function expandTokenPattern(token) {
+  const bracketRegex = /\[(.*?)\]/;
+  const match = token.name.match(bracketRegex);
+  if (!match) return [token];
+  const variants = match[1].split(',').map(s => s.trim());
+  return variants.map(variant => ({
+    ...token,
+    name: token.name.replace(bracketRegex, variant)
+  }));
+}
+
+// Load and parse token guidelines, then build complete token list
+function loadAllTokensWithGuidelines() {
+  try {
+    const specMarkdown = loadDesignTokensSpec();
+    const specTokens = parseDesignTokensSpec(specMarkdown);
+    return buildAllTokens(specTokens);
+  } catch {
+    // DESIGN_TOKENS_SPEC.md not available in this version of @primer/primitives
+    return buildAllTokens([]);
+  }
+}
+
+// Load the design tokens guide (logic, rules, patterns, golden examples)
+function loadDesignTokensGuide() {
+  const require = createRequire(import.meta.url);
+  const guidePath = require.resolve('@primer/primitives/DESIGN_TOKENS_GUIDE.md');
+  return readFileSync(guidePath, 'utf-8');
+}
+
+// Load the design tokens spec (token dictionary with use cases and rules)
+function loadDesignTokensSpec() {
+  const require = createRequire(import.meta.url);
+  const specPath = require.resolve('@primer/primitives/DESIGN_TOKENS_SPEC.md');
+  return readFileSync(specPath, 'utf-8');
+}
+
+// Get design token specifications text with dynamic group information
+function getDesignTokenSpecsText(groups) {
+  return `
+# Design Token Specifications
+
+## 1. Core Rule & Enforcement
+* **Expert Mode**: CSS expert. NEVER use raw values (hex, px, etc.). Tokens only.
+* **Motion & Transitions:** Every interactive state change (Hover, Active) MUST include a transition. NEVER use raw values like 200ms or ease-in. Use var(--base-duration-...) and var(--base-easing-...).
+* **Shorthand**: MUST use \`font: var(...)\`. NEVER split size/weight. 
+* **Shorthand Fallback**: If no shorthand exists (e.g. Monospace), use individual tokens for font-size, family, and line-height. NEVER raw 1.5.
+* **States**: Define 5: Rest, Hover, Focus-visible, Active, Disabled.
+* **Focus**: \`:focus-visible\` MUST use \`outline: var(--focus-outline)\` AND \`outline-offset: var(--outline-focus-offset)\`.
+* **Validation**: CALL \`lint_css\` after any CSS change. Task is incomplete without a success message.
+* **Self-Correction**: Adopt autofixes immediately. Report unfixable errors to the user.
+
+## 2. Typography Constraints (STRICT)
+- **Body Only**: Only \`body\` group supports size suffixes (e.g., \`body-small\`).
+- **Static Shorthands**: NEVER add suffixes to \`caption\`, \`display\`, \`codeBlock\`, or \`codeInline\`.
+
+## 3. Logic Matrix: Color & Semantic Mapping
+| Input Color/Intent | Semantic Role | Background Suffix | Foreground Requirement |
+| :--- | :--- | :--- | :--- |
+| Blue / Interactive | \`accent\` | \`-emphasis\` (Solid) | \`fgColor-onEmphasis\` |
+| Green / Positive | \`success\` | \`-muted\` (Light) | \`fgColor-{semantic}\` |
+| Red / Danger | \`danger\` | \`-emphasis\` | \`fgColor-onEmphasis\` |
+| Yellow / Warning | \`attention\` | \`-muted\` | \`fgColor-attention\` |
+| Orange / Critical | \`severe\` | \`-emphasis\` | \`fgColor-onEmphasis\` |
+| Purple / Done | \`done\` | Any | Match intent |
+| Pink / Sponsors | \`sponsors\` | Any | Match intent |
+| Grey / Neutral | \`default\` | \`bgColor-muted\` | \`fgColor-default\` (Not muted) |
+
+## 4. Optimization & Recipes (MANDATORY)
+**Strategy**: STOP property-by-property searching. Use \`get_token_group_bundle\` for these common patterns:
+- **Forms**: \`["control", "focus", "outline", "text", "borderRadius", "stack", "animation"]\`
+- **Modals/Cards**: \`["overlay", "shadow", "outline", "borderRadius", "bgColor", "stack", "animation"]\`
+- **Tables/Lists**: \`["stack", "borderColor", "text", "bgColor", "control"]\`
+- **Nav/Sidebars**: \`["control", "text", "accent", "stack", "focus", "animation"]\`
+- **Status/Badges**: \`["text", "success", "danger", "attention", "severe", "stack"]\`
+
+## 5. Available Groups
+- **Semantic**: ${groups.semantic.map(g => `${g.name}\``).join(', ')}
+- **Components**: ${groups.component.map(g => `\`${g.name}\``).join(', ')}
+`.trim();
+}
+
+// Get token usage patterns text (static golden examples)
+function getTokenUsagePatternsText() {
+  return `
+# Design Token Reference Examples
+
+> **CRITICAL FOR AI**: To implement the examples below, DO NOT search for tokens one-by-one. 
+> Use \`get_token_group_bundle(groups: ["control", "stack", "focus", "borderRadius"])\` to fetch the required token values in a single call.
+
+---
+
+## 1. Interaction Pattern: The Primary Button
+*Demonstrates: 5 states, color pairing, typography shorthand, and motion.*
+
+\`\`\`css
+.btn-primary {
+  /* Logic: Use control tokens for interactive elements */
+  background-color: var(--control-bgColor-rest);
+  color: var(--fgColor-default);
+  font: var(--text-body-shorthand-medium); /* MUST use shorthand */
+  
+  /* Scale: DEFAULT is medium/normal */
+  padding-block: var(--control-medium-paddingBlock);
+  padding-inline: var(--control-medium-paddingInline-normal);
+  border: none;
+  border-radius: var(--borderRadius-medium);
+  cursor: pointer;
+
+  /* Motion: MUST be <300ms */
+  transition: background-color 150ms ease, transform 100ms ease;
+}
+
+.btn-primary:hover {
+  background-color: var(--control-bgColor-hover);
+}
+
+.btn-primary:focus-visible {
+  outline: var(--focus-outline);
+  outline-offset: var(--outline-focus-offset);
+}
+
+.btn-primary:active {
+  background-color: var(--control-bgColor-active);
+  transform: scale(0.98);
+}
+
+.btn-primary:disabled {
+  /* Logic: MUST pair bgColor-disabled with fgColor-disabled */
+  background-color: var(--bgColor-disabled);
+  color: var(--fgColor-disabled);
+  cursor: not-allowed;
+}
+\`\`\`
+
+---
+
+## 2. Layout Pattern: Vertical Stack
+*Demonstrates: Layout spacing rules and matching padding density.*
+
+\`\`\`css
+.card-stack {
+  display: flex;
+  flex-direction: column;
+
+  /* Logic: Use stack tokens for layout spacing */
+  gap: var(--stack-gap-normal);
+  padding: var(--stack-padding-normal);
+  
+  background-color: var(--bgColor-default);
+  border: 1px solid var(--borderColor-default);
+  border-radius: var(--borderRadius-large);
+}
+
+/* Logic: Matching padding density to purpose */
+.card-header {
+  padding-block-end: var(--stack-gap-condensed);
+  border-bottom: 1px solid var(--borderColor-muted);
+}
+\`\`\`
+
+---
+
+## Implementation Rules for AI:
+1. **Shorthand First**: Always use \`font: var(...)\` rather than splitting size/weight.
+2. **States**: Never implement a button without all 5 states.
+3. **Spacing**: Use \`control-\` tokens for the component itself and \`stack-\` tokens for the container/layout.
+4. **Motion**: Always include the \`prefers-reduced-motion\` media query to set transitions to \`none\`.
+\`\`\`css
+@media (prefers-reduced-motion: reduce) {
+  .btn-primary {
+    transition: none;
+  }
+}
+\`\`\`
+`.trim();
+}
+
+// Search tokens with keyword matching and optional group filter
+// Returns expanded tokens (patterns like [accent, danger] are expanded) filtered by query
+function searchTokens(allTokens, query, group) {
+  // 1. Flatten and expand all patterns first (e.g., [accent, danger])
+  const expandedTokens = allTokens.flatMap(expandTokenPattern);
+
+  // 2. Prepare keywords and group filter
+  const keywords = query.toLowerCase().split(/\s+/).filter(k => k.length > 0);
+
+  // 3. Perform filtered search with keyword splitting (Logical AND)
+  return expandedTokens.filter(token => {
+    // Combine all relevant metadata into one searchable string
+    const searchableText = `${token.name} ${token.useCase} ${token.rules} ${token.group}`.toLowerCase();
+
+    // Ensure EVERY keyword in the query exists somewhere in this token's metadata
+    const matchesKeywords = keywords.every(word => searchableText.includes(word));
+    const matchesGroup = !group || tokenMatchesGroup(token, group);
+    return matchesKeywords && matchesGroup;
+  });
+}
+
+// Alias map: fuzzy/human-readable names → canonical token name prefix
+const GROUP_ALIASES = {
+  // Identity mappings (canonical prefixes, lowercased key)
+  bgcolor: 'bgColor',
+  fgcolor: 'fgColor',
+  bordercolor: 'borderColor',
+  border: 'border',
+  shadow: 'shadow',
+  focus: 'focus',
+  color: 'color',
+  button: 'button',
+  control: 'control',
+  overlay: 'overlay',
+  borderradius: 'borderRadius',
+  boxshadow: 'boxShadow',
+  fontstack: 'fontStack',
+  spinner: 'spinner',
+  // Fuzzy aliases
+  background: 'bgColor',
+  backgroundcolor: 'bgColor',
+  bg: 'bgColor',
+  foreground: 'fgColor',
+  foregroundcolor: 'fgColor',
+  textcolor: 'fgColor',
+  fg: 'fgColor',
+  radius: 'borderRadius',
+  rounded: 'borderRadius',
+  elevation: 'overlay',
+  depth: 'overlay',
+  btn: 'button',
+  typography: 'text',
+  font: 'text',
+  text: 'text',
+  'line-height': 'text',
+  lineheight: 'text',
+  leading: 'text',
+  // Layout & Spacing
+  stack: 'stack',
+  controlstack: 'controlStack',
+  padding: 'stack',
+  margin: 'stack',
+  gap: 'stack',
+  spacing: 'stack',
+  layout: 'stack',
+  // State & Interaction
+  offset: 'focus',
+  outline: 'outline',
+  ring: 'focus',
+  // Decoration & Borders
+  borderwidth: 'borderWidth',
+  line: 'borderColor',
+  stroke: 'borderColor',
+  separator: 'borderColor',
+  // Color-to-Semantic Intent Mapping
+  red: 'danger',
+  green: 'success',
+  yellow: 'attention',
+  orange: 'severe',
+  blue: 'accent',
+  purple: 'done',
+  pink: 'sponsors',
+  grey: 'neutral',
+  gray: 'neutral',
+  // Descriptive Aliases
+  light: 'muted',
+  subtle: 'muted',
+  dark: 'emphasis',
+  strong: 'emphasis',
+  intense: 'emphasis',
+  bold: 'emphasis',
+  vivid: 'emphasis',
+  highlight: 'emphasis'
+};
+
+// Match a token against a resolved group by checking both the token name prefix and the group label
+function tokenMatchesGroup(token, resolvedGroup) {
+  const rg = resolvedGroup.toLowerCase();
+  const tokenPrefix = token.name.split('-')[0].toLowerCase();
+  const tokenGroup = token.group.toLowerCase();
+  return tokenPrefix === rg || tokenGroup === rg;
+}
+
+// Group tokens by their group property and format as Markdown
+function formatBundle(bundleTokens) {
+  const grouped = bundleTokens.reduce((acc, token) => {
+    const group = GROUP_LABELS[token.group] || token.group || 'Ungrouped';
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!acc[group]) acc[group] = [];
+    acc[group].push(token);
+    return acc;
+  }, {});
+  return Object.entries(grouped).map(([group, groupTokens]) => {
+    const tokenList = groupTokens.map(t => {
+      const nameLabel = t.value ? `\`${t.name}\` → \`${t.value}\`` : `\`${t.name}\``;
+      return `- ${nameLabel}\n  - **U**: ${t.useCase || '(none)'}\n  - **R**: ${t.rules || '(none)'}`;
+    }).join('\n');
+    return `## ${group}\n\n${tokenList}`;
+  }).join('\n\n---\n\n');
+}
+
+/**
+ * Generates a sorted, unique list of group names from the current token cache.
+ * Used for "Healing" error messages and the Design System Search Map.
+ */
+function getValidGroupsList(validTokens) {
+  if (validTokens.length === 0) {
+    return 'No groups available.';
+  }
+
+  // 1. Extract unique group names
+  const uniqueGroups = Array.from(new Set(validTokens.map(t => t.group)));
+
+  // 2. Sort alphabetically for consistency
+  uniqueGroups.sort((a, b) => a.localeCompare(b));
+
+  // 3. Return as a formatted Markdown string with backticks
+  return uniqueGroups.map(g => `\`${g}\``).join(', ');
+}
+
+// Usage Guidance Hints
+const groupHints = {
+  control: '`control` tokens are for form inputs/checkboxes. For buttons, use the `button` group.',
+  button: '`button` tokens are for standard triggers. For form-fields, see the `control` group.',
+  text: 'STRICT: The following typography groups do NOT support size suffixes (-small, -medium, -large): `caption`, `display`, `codeBlock`, and `codeInline`. STRICT: Use shorthand tokens where possible. If splitting, you MUST fetch line-height tokens (e.g., --text-body-lineHeight-small) instead of using raw numbers.',
+  fgColor: 'Use `fgColor` for text. For borders, use `borderColor`.',
+  borderWidth: '`borderWidth` only has sizing values (thin, thick, thicker). For border *colors*, use the `borderColor` or `border` group.',
+  animation: 'TRANSITION RULE: Apply duration and easing to the base class, not the :hover state. Standard pairing: `transition: background-color var(--base-duration-200) var(--base-easing-easeInOut);`'
+};
+
+// -----------------------------------------------------------------------------
+// Stylelint runner
+// -----------------------------------------------------------------------------
+function runStylelint(css) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('npx', ['stylelint', '--stdin', '--fix'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      shell: true
+    });
+    let stdout = '';
+    let stderr = '';
+    proc.stdout.on('data', data => {
+      stdout += data.toString();
+    });
+    proc.stderr.on('data', data => {
+      stderr += data.toString();
+    });
+    proc.on('close', code => {
+      if (code === 0) {
+        resolve({
+          stdout,
+          stderr
+        });
+      } else {
+        const error = new Error(`Stylelint exited with code ${code}`);
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+      }
+    });
+    proc.on('error', reject);
+    proc.stdin.write(css);
+    proc.stdin.end();
+  });
+}
+
+var version = "0.3.1";
+var packageJson = {
+	version: version};
+
+const server = new McpServer({
+  name: 'Primer',
+  version: packageJson.version
+});
+const turndownService = new TurndownService();
+
+// Load all tokens with guidelines from primitives
+const allTokensWithGuidelines = loadAllTokensWithGuidelines();
+
+// -----------------------------------------------------------------------------
+// Project setup
+// -----------------------------------------------------------------------------
+server.registerTool('init', {
+  description: 'Setup or create a project that includes Primer React'
+}, async () => {
+  const url = new URL(`/product/getting-started/react`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `The getting started documentation for Primer React is included below. It's important that the project:
+
+- Is using a tool like Vite, Next.js, etc that supports TypeScript and React. If the project does not have support for that, generate an appropriate project scaffold
+- Installs the latest version of \`@primer/react\` from \`npm\`
+- Correctly adds the \`ThemeProvider\` and \`BaseStyles\` components to the root of the application
+- Includes an import to a theme from \`@primer/primitives\`
+- If the project wants to use icons, also install the \`@primer/octicons-react\` from \`npm\`
+- Add appropriate agent instructions (like for copilot) to the project to prefer using components, tokens, icons, and more from Primer packages
+
+---
+
+${text}
+`
+    }]
+  };
+});
+
+// -----------------------------------------------------------------------------
+// Components
+// -----------------------------------------------------------------------------
+server.registerTool('list_components', {
+  description: 'List all of the components available from Primer React'
+}, async () => {
+  const components = listComponents().map(component => {
+    return `- ${component.name}`;
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: `The following components are available in the @primer/react in TypeScript projects:
+
+${components.join('\n')}
+
+You can use the \`get_component\` tool to get more information about a specific component. You can use these components from the @primer/react package.`
+    }]
+  };
+});
+server.registerTool('get_component', {
+  description: 'Retrieve documentation and usage details for a specific React component from the @primer/react package by its name. This tool provides the official Primer documentation for any listed component, making it easy to inspect, reuse, or integrate components in your project.',
+  inputSchema: {
+    name: z.string().describe('The name of the component to retrieve')
+  }
+}, async ({
+  name
+}) => {
+  const components = listComponents();
+  const match = components.find(component => {
+    return component.name === name || component.name.toLowerCase() === name.toLowerCase();
+  });
+  if (!match) {
+    return {
+      isError: true,
+      errorMessage: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`list_components\` tool.`,
+      content: []
+    };
+  }
+  const llmsUrl = new URL(`/product/components/${match.slug}/llms.txt`, 'https://primer.style');
+  const llmsResponse = await fetch(llmsUrl);
+  if (llmsResponse.ok) {
+    try {
+      const llmsText = await llmsResponse.text();
+      return {
+        content: [{
+          type: 'text',
+          text: llmsText
+        }]
+      };
+    } catch (_) {
+      // If there's an error fetching or processing the llms.txt, we fall back to the regular documentation
+    }
+  }
+  const url = new URL(`/product/components/${match.slug}`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here is the documentation for the \`${name}\` component from the @primer/react package:
+${text}`
+    }]
+  };
+});
+server.registerTool('get_component_examples', {
+  description: 'Get examples for how to use a component from Primer React',
+  inputSchema: {
+    name: z.string().describe('The name of the component to retrieve')
+  }
+}, async ({
+  name
+}) => {
+  const components = listComponents();
+  const match = components.find(component => {
+    return component.name === name;
+  });
+  if (!match) {
+    return {
+      content: [{
+        type: 'text',
+        text: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`get_components\` tool.`
+      }]
+    };
+  }
+  const url = new URL(`/product/components/${match.id}`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here are some examples of how to use the \`${name}\` component from the @primer/react package:
+
+${text}`
+    }]
+  };
+});
+server.registerTool('get_component_usage_guidelines', {
+  description: 'Get usage information for how to use a component from Primer',
+  inputSchema: {
+    name: z.string().describe('The name of the component to retrieve')
+  }
+}, async ({
+  name
+}) => {
+  const components = listComponents();
+  const match = components.find(component => {
+    return component.name === name;
+  });
+  if (!match) {
+    return {
+      content: [{
+        type: 'text',
+        text: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`get_components\` tool.`
+      }]
+    };
+  }
+  const url = new URL(`/product/components/${match.id}/guidelines`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    if (response.status >= 400 && response.status < 500 || response.status >= 300 && response.status < 400) {
+      return {
+        content: [{
+          type: 'text',
+          text: `There are no accessibility guidelines for the \`${name}\` component in the @primer/react package.`
+        }]
+      };
+    }
+    throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here are the usage guidelines for the \`${name}\` component from the @primer/react package:
+
+${text}`
+    }]
+  };
+});
+server.registerTool('get_component_accessibility_guidelines', {
+  description: 'Retrieve accessibility guidelines and best practices for a specific component from the @primer/react package by its name. Use this tool to get official accessibility recommendations, usage tips, and requirements to ensure your UI components are inclusive and meet accessibility standards.',
+  inputSchema: {
+    name: z.string().describe('The name of the component to retrieve')
+  }
+}, async ({
+  name
+}) => {
+  const components = listComponents();
+  const match = components.find(component => {
+    return component.name === name;
+  });
+  if (!match) {
+    return {
+      content: [{
+        type: 'text',
+        text: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`list_components\` tool.`
+      }]
+    };
+  }
+  const url = new URL(`/product/components/${match.id}/accessibility`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    if (response.status >= 400 && response.status < 500 || response.status >= 300 && response.status < 400) {
+      return {
+        content: [{
+          type: 'text',
+          text: `There are no accessibility guidelines for the \`${name}\` component in the @primer/react package.`
+        }]
+      };
+    }
+    throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here are the accessibility guidelines for the \`${name}\` component from the @primer/react package:
+
+${text}`
+    }]
+  };
+});
+
+// -----------------------------------------------------------------------------
+// Patterns
+// -----------------------------------------------------------------------------
+server.registerTool('list_patterns', {
+  description: 'List all of the patterns available from Primer React'
+}, async () => {
+  const patterns = listPatterns().map(pattern => {
+    return `- ${pattern.name}`;
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: `The following patterns are available in the @primer/react in TypeScript projects:
+
+${patterns.join('\n')}`
+    }]
+  };
+});
+server.registerTool('get_pattern', {
+  description: 'Get a specific pattern by name',
+  inputSchema: {
+    name: z.string().describe('The name of the pattern to retrieve')
+  }
+}, async ({
+  name
+}) => {
+  const patterns = listPatterns();
+  const match = patterns.find(pattern => {
+    return pattern.name === name;
+  });
+  if (!match) {
+    return {
+      content: [{
+        type: 'text',
+        text: `There is no pattern named \`${name}\` in the @primer/react package. For a full list of patterns, use the \`list_patterns\` tool.`
+      }]
+    };
+  }
+  const url = new URL(`/product/ui-patterns/${match.id}`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url} - ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here are the guidelines for the \`${name}\` pattern for Primer:
+
+${text}`
+    }]
+  };
+});
+
+// -----------------------------------------------------------------------------
+// Design Tokens
+// -----------------------------------------------------------------------------
+server.registerTool('find_tokens', {
+  description: 'Search for specific tokens. Tip: If you only provide a \'group\' and leave \'query\' empty, it returns all tokens in that category. Avoid property-by-property searching. COLOR RESOLUTION: If a user asks for "pink" or "blue", do not search for the color name. Use the semantic intent: blue->accent, red->danger, green->success. Always check both "emphasis" and "muted" variants for background colors. After identifying tokens and writing CSS, you MUST validate the result using lint_css.',
+  inputSchema: {
+    query: z.string().optional().default('').describe('Search keywords (e.g., "danger border", "success background")'),
+    group: z.string().optional().describe('Filter by group (e.g., "fgColor", "border")'),
+    limit: z.number().int().min(1).max(100).optional().default(15).describe('Maximum results to return to stay within context limits')
+  }
+}, async ({
+  query,
+  group,
+  limit
+}) => {
+  // Resolve group via aliases
+  const resolvedGroup = group ? GROUP_ALIASES[group.toLowerCase().replace(/\s+/g, '')] || group : undefined;
+
+  // Split query into keywords and extract any that match a known group
+  const rawKeywords = query.toLowerCase().split(/\s+/).filter(k => k.length > 0);
+  let effectiveGroup = resolvedGroup;
+  const filteredKeywords = [];
+  for (const kw of rawKeywords) {
+    const normalized = kw.replace(/\s+/g, '');
+    const aliasMatch = GROUP_ALIASES[normalized];
+    if (aliasMatch && !effectiveGroup) {
+      effectiveGroup = aliasMatch;
+    } else {
+      filteredKeywords.push(kw);
+    }
+  }
+
+  // Guard: no query and no group → ask user to provide at least one
+  if (filteredKeywords.length === 0 && !effectiveGroup) {
+    return {
+      content: [{
+        type: 'text',
+        text: 'Please provide a query, a group, or both. Call `get_design_token_specs` to see available token groups.'
+      }]
+    };
+  }
+
+  // Group-only search: return all tokens in the group
+  const isGroupOnly = filteredKeywords.length === 0 && effectiveGroup;
+  let results;
+  if (isGroupOnly) {
+    results = allTokensWithGuidelines.filter(token => tokenMatchesGroup(token, effectiveGroup));
+  } else {
+    results = searchTokens(allTokensWithGuidelines, filteredKeywords.join(' '), effectiveGroup);
+  }
+  if (results.length === 0) {
+    const validGroups = getValidGroupsList(allTokensWithGuidelines);
+    return {
+      content: [{
+        type: 'text',
+        text: `No tokens found matching "${query}"${effectiveGroup ? ` in group "${effectiveGroup}"` : ''}. 
+
+### 💡 Available Groups:
+${validGroups}
+
+### Troubleshooting for AI:
+1. **Multi-word Queries**: Search keywords use 'AND' logic. If searching "text shorthand typography" fails, try a single keyword like "shorthand" within the "text" group.
+2. **Property Mismatch**: Do not search for CSS properties like "offset", "padding", or "font-size". Use semantic intent keywords: "danger", "muted", "emphasis".
+3. **Typography**: Remember that \`caption\`, \`display\`, and \`code\` groups do NOT support size suffixes. Use the base shorthand only.
+4. **Group Intent**: Use the \`group\` parameter instead of putting group names in the \`query\` string (e.g., use group: "stack" instead of query: "stack padding").`
+      }]
+    };
+  }
+  const limitedResults = results.slice(0, limit);
+  let output;
+  if (!query) {
+    output = `Found ${results.length} token(s). Showing top ${limitedResults.length}:\n\n`;
+  } else {
+    output = `Found ${results.length} token(s) matching "${query}". Showing top ${limitedResults.length}:\n\n`;
+  }
+  output += formatBundle(limitedResults);
+  if (results.length > limit) {
+    output += `\n\n*...and ${results.length - limit} more matches. Use more specific keywords to narrow the search.*`;
+  }
+  return {
+    content: [{
+      type: 'text',
+      text: output
+    }]
+  };
+});
+server.registerTool('get_token_group_bundle', {
+  description: "PREFERRED FOR COMPONENTS. Fetch all tokens for complex UI (e.g., Dialogs, Cards) in one call by providing an array of groups like ['overlay', 'shadow']. Use this instead of multiple find_tokens calls to save context.",
+  inputSchema: {
+    groups: z.array(z.string()).describe('Array of group names (e.g., ["overlay", "shadow", "focus"])')
+  }
+}, async ({
+  groups
+}) => {
+  // Normalize and resolve aliases
+  const resolvedGroups = groups.map(g => {
+    const normalized = g.toLowerCase().replace(/\s+/g, '');
+    return GROUP_ALIASES[normalized] || g;
+  });
+
+  // Filter tokens matching any of the resolved groups
+  const matched = allTokensWithGuidelines.filter(token => resolvedGroups.some(rg => tokenMatchesGroup(token, rg)));
+  if (matched.length === 0) {
+    const validGroups = getValidGroupsList(allTokensWithGuidelines);
+    return {
+      content: [{
+        type: 'text',
+        text: `No tokens found for groups: ${groups.join(', ')}.\n\n### Valid Groups:\n${validGroups}`
+      }]
+    };
+  }
+  let text = `Found ${matched.length} token(s) across ${resolvedGroups.length} group(s):\n\n${formatBundle(matched)}`;
+  const activeHints = resolvedGroups.map(g => groupHints[g]).filter(Boolean);
+  if (activeHints.length > 0) {
+    text += `\n\n### ⚠️ Usage Guidance:\n${activeHints.map(h => `- ${h}`).join('\n')}`;
+  }
+  return {
+    content: [{
+      type: 'text',
+      text
+    }]
+  };
+});
+server.registerTool('get_design_token_specs', {
+  description: 'CRITICAL: CALL THIS FIRST. Provides the logic matrix and the list of valid group names. You cannot search accurately without this map.'
+}, async () => {
+  const groups = listTokenGroups();
+  const customRules = getDesignTokenSpecsText(groups);
+  let text;
+  try {
+    const upstreamGuide = loadDesignTokensGuide();
+    text = `${customRules}\n\n---\n\n${upstreamGuide}`;
+  } catch {
+    text = customRules;
+  }
+  return {
+    content: [{
+      type: 'text',
+      text
+    }]
+  };
+});
+server.registerTool('get_token_usage_patterns', {
+  description: 'Provides "Golden Example" CSS for core patterns: Button (Interactions) and Stack (Layout). Use this to understand how to apply the Logic Matrix, Motion, and Spacing scales.'
+}, async () => {
+  const customPatterns = getTokenUsagePatternsText();
+  let text;
+  try {
+    const guide = loadDesignTokensGuide();
+    const goldenExampleMatch = guide.match(/## Golden Example[\s\S]*?(?=\n## |$)/);
+    if (goldenExampleMatch) {
+      text = `${customPatterns}\n\n---\n\n${goldenExampleMatch[0].trim()}`;
+    } else {
+      text = customPatterns;
+    }
+  } catch {
+    text = customPatterns;
+  }
+  return {
+    content: [{
+      type: 'text',
+      text
+    }]
+  };
+});
+server.registerTool('lint_css', {
+  description: 'REQUIRED FINAL STEP. Use this to validate your CSS. You cannot complete a task involving CSS without a successful run of this tool.',
+  inputSchema: {
+    css: z.string()
+  }
+}, async ({
+  css
+}) => {
+  try {
+    // --fix flag tells Stylelint to repair what it can
+    const {
+      stdout
+    } = await runStylelint(css);
+    return {
+      content: [{
+        type: 'text',
+        text: stdout || '✅ Stylelint passed (or was successfully autofixed).'
+      }]
+    };
+  } catch (error) {
+    // If Stylelint still has errors it CANNOT fix, it will land here
+    const errorOutput = error instanceof Error && 'stdout' in error ? error.stdout : String(error);
+    return {
+      content: [{
+        type: 'text',
+        text: `❌ Errors without autofix remaining:\n${errorOutput}`
+      }]
+    };
+  }
+});
+
+// -----------------------------------------------------------------------------
+// Foundations
+// -----------------------------------------------------------------------------
+server.registerTool('get_color_usage', {
+  description: 'Get the guidelines for how to apply color to a user interface'
+}, async () => {
+  const url = new URL(`/product/getting-started/foundations/color-usage`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url} - ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here is the documentation for color usage in Primer:\n\n${text}`
+    }]
+  };
+});
+server.registerTool('get_typography_usage', {
+  description: 'Get the guidelines for how to apply typography to a user interface'
+}, async () => {
+  const url = new URL(`/product/getting-started/foundations/typography`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url} - ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here is the documentation for typography usage in Primer:\n\n${text}`
+    }]
+  };
+});
+
+// -----------------------------------------------------------------------------
+// Icons
+// -----------------------------------------------------------------------------
+server.registerTool('list_icons', {
+  description: 'List all of the icons (octicons) available from Primer Octicons React'
+}, async () => {
+  const icons = listIcons().map(icon => {
+    const keywords = icon.keywords.map(keyword => {
+      return `<keyword>${keyword}</keyword>`;
+    });
+    const sizes = icon.heights.map(height => {
+      return `<size value="${height}"></size>`;
+    });
+    return [`<icon name="${icon.name}">`, ...keywords, ...sizes, `</icon>`].join('\n');
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: `The following icons are available in the @primer/octicons-react package in TypeScript projects:
+
+${icons.join('\n')}
+
+You can use the \`get_icon\` tool to get more information about a specific icon. You can use these components from the @primer/octicons-react package.`
+    }]
+  };
+});
+server.registerTool('get_icon', {
+  description: 'Get a specific icon (octicon) by name from Primer',
+  inputSchema: {
+    name: z.string().describe('The name of the icon to retrieve'),
+    size: z.string().optional().describe('The size of the icon to retrieve, e.g. "16"').default('16')
+  }
+}, async ({
+  name,
+  size
+}) => {
+  const icons = listIcons();
+  const match = icons.find(icon => {
+    return icon.name === name || icon.name.toLowerCase() === name.toLowerCase();
+  });
+  if (!match) {
+    return {
+      content: [{
+        type: 'text',
+        text: `There is no icon named \`${name}\` in the @primer/octicons-react package. For a full list of icons, use the \`get_icon\` tool.`
+      }]
+    };
+  }
+  const url = new URL(`/octicons/icon/${match.name}-${size}`, 'https://primer.style');
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  }
+  const html = await response.text();
+  if (!html) {
+    return {
+      content: []
+    };
+  }
+  const $ = cheerio.load(html);
+  const source = $('main').html();
+  if (!source) {
+    return {
+      content: []
+    };
+  }
+  const text = turndownService.turndown(source);
+  return {
+    content: [{
+      type: 'text',
+      text: `Here is the documentation for the \`${name}\` icon at size: \`${size}\`:
+${text}`
+    }]
+  };
+});
+
+// -----------------------------------------------------------------------------
+// Coding guidelines
+// -----------------------------------------------------------------------------
+server.registerTool('primer_coding_guidelines', {
+  description: 'Get the guidelines when writing code that uses Primer or for UI code that you are creating'
+}, async () => {
+  return {
+    content: [{
+      type: 'text',
+      text: `When writing code that uses Primer, follow these guidelines:
+
+## Design Tokens
+
+- Prefer design tokens over hard-coded values. For example, use \`var(--fgColor-default)\` instead of \`#24292f\`. Use the \`find_tokens\` tool to search for a design token by keyword or group. Use \`get_design_token_specs\` to browse available token groups, and \`get_token_group_bundle\` to retrieve all tokens within a specific group.
+- Prefer recommending design tokens in the same group for related CSS properties. For example, when styling background and border color, use tokens from the same group/category
+
+## Authoring & Using Components
+
+- Prefer re-using a component from Primer when possible over writing a new component.
+- Prefer using existing props for a component for styling instead of adding styling to a component
+- Prefer using icons from Primer instead of creating new icons. Use the \`list_icons\` tool to find the icon you need.
+- Follow patterns from Primer when creating new components. Use the \`list_patterns\` tool to find the pattern you need, if one exists
+- When using a component from Primer, make sure to follow the component's usage and accessibility guidelines
+
+## Coding guidelines
+
+The following list of coding guidelines must be followed:
+
+- Do not use the sx prop for styling components. Instead, use CSS Modules.
+- Do not use the Box component for styling components. Instead, use CSS Modules.
+`
+    }]
+  };
+});
+
+// -----------------------------------------------------------------------------
+// Accessibility
+// -----------------------------------------------------------------------------
+
+/**
+ * The `review_alt_text` tool is experimental and may be removed in future versions.
+ *
+ * The intent of this tool is to assist products like Copilot Code Review and Copilot Coding Agent
+ * in reviewing both user- and AI-generated alt text for images, ensuring compliance with accessibility guidelines.
+ * This tool is not intended to replace human-generated alt text; rather, it supports the review process
+ * by providing suggestions for improvement. It should be used alongside human review, not as a substitute.
+ *
+ *
+ **/
+server.registerTool('review_alt_text', {
+  description: 'Evaluates image alt text against accessibility best practices and context relevance.',
+  inputSchema: {
+    surroundingText: z.string().describe('Text surrounding the image, relevant to the image.'),
+    alt: z.string().describe('The alt text of the image being evaluated'),
+    image: z.string().describe('The image URL or file path being evaluated')
+  }
+}, async ({
+  surroundingText,
+  alt,
+  image
+}) => {
+  // Call the LLM through MCP sampling
+  const response = await server.server.createMessage({
+    messages: [{
+      role: 'user',
+      content: {
+        type: 'text',
+        text: `Does this alt text: '${alt}' meet accessibility guidelines and describe the image: ${image} accurately in context of this surrounding text: '${surroundingText}'?\n\n`
+      }
+    }],
+    sampling: {
+      temperature: 0.4
+    },
+    maxTokens: 500
+  });
+  return {
+    content: [{
+      type: 'text',
+      text: response.content.type === 'text' ? response.content.text : 'Unable to generate summary'
+    }],
+    altTextEvaluation: response.content.type === 'text' ? response.content.text : 'Unable to generate summary',
+    nextSteps: `If the evaluation indicates issues with the alt text, provide more meaningful alt text based on the feedback. DO NOT run this tool repeatedly on the same image - evaluations may vary slightly with each run.`
+  };
+});
+
+export { server as s };