@primer/mcp 0.3.4 → 0.4.0-rc.2d1806208

package/dist/server-BTJ9W5jN.js

@@ -0,0 +1,1190 @@
+import { createRequire } from "node:module";
+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 { 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" };
+//#region src/primer.ts
+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: "copy",
+		name: "Copy",
+		category: "scenario"
+	},
+	{
+		id: "delete",
+		name: "Delete",
+		category: "scenario"
+	},
+	{
+		id: "filter",
+		name: "Filter",
+		category: "scenario"
+	},
+	{
+		id: "search",
+		name: "Search",
+		category: "scenario"
+	},
+	{
+		id: "data-visualization",
+		name: "Data Visualization",
+		category: "ui"
+	},
+	{
+		id: "degraded-experiences",
+		name: "Degraded Experiences",
+		category: "ui"
+	},
+	{
+		id: "empty-states",
+		name: "Empty States",
+		category: "ui"
+	},
+	{
+		id: "feature-onboarding",
+		name: "Feature Onboarding",
+		category: "ui"
+	},
+	{
+		id: "forms",
+		name: "Forms",
+		category: "ui"
+	},
+	{
+		id: "loading",
+		name: "Loading",
+		category: "ui"
+	},
+	{
+		id: "navigation",
+		name: "Navigation",
+		category: "ui"
+	},
+	{
+		id: "notification-messaging",
+		name: "Notification message",
+		category: "ui"
+	},
+	{
+		id: "progressive-disclosure",
+		name: "Progressive disclosure",
+		category: "ui"
+	},
+	{
+		id: "saving",
+		name: "Saving",
+		category: "ui"
+	}
+];
+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;
+}
+//#endregion
+//#region src/primitives.ts
+let functionalSizeRadius = {};
+try {
+	const radiusPath = createRequire(import.meta.url).resolve("@primer/primitives/dist/docs/functional/size/radius.json");
+	functionalSizeRadius = JSON.parse(readFileSync(radiusPath, "utf-8"));
+} catch {}
+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
+];
+const SEMANTIC_PREFIXES = [
+	"bgColor",
+	"fgColor",
+	"border",
+	"borderColor",
+	"shadow",
+	"focus",
+	"color",
+	"animation",
+	"duration"
+];
+function listTokenGroups() {
+	const allTokens = tokens;
+	const groupMap = /* @__PURE__ */ 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: /* @__PURE__ */ new Set()
+		});
+		const group = groupMap.get(prefix);
+		group.count++;
+		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);
+	}
+	semantic.sort((a, b) => b.count - a.count);
+	component.sort((a, b) => b.count - a.count);
+	return {
+		semantic,
+		component
+	};
+}
+function parseDesignTokensSpec(markdown) {
+	const results = [];
+	const lines = markdown.split("\n");
+	let currentGroup = "";
+	let currentToken = null;
+	let descriptionLines = [];
+	for (const line of lines) {
+		const groupMatch = line.match(/^## (.+)$/);
+		if (groupMatch) {
+			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;
+		}
+		const tokenMatch = line.match(/^### (.+)$/);
+		if (tokenMatch) {
+			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;
+		}
+		const newUsageMatch = line.match(/^\*\*U:\*\*\s*(.+)$/);
+		if (newUsageMatch && currentToken) {
+			currentToken.useCase = newUsageMatch[1].trim();
+			continue;
+		}
+		const newRulesMatch = line.match(/^\*\*R:\*\*\s*(.+)$/);
+		if (newRulesMatch && currentToken) {
+			currentToken.rules = newRulesMatch[1].trim();
+			continue;
+		}
+		if (currentToken && !currentToken.useCase && !line.startsWith("**") && line.trim() && !line.startsWith("#")) descriptionLines.push(line.trim());
+	}
+	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;
+}
+function getTokenValue(tokenName) {
+	const found = tokens.find((token) => token.name === tokenName);
+	return found ? String(found.value) : "";
+}
+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"
+};
+function getGroupFromName(name) {
+	return name.split("-")[0];
+}
+function buildAllTokens(guidelinesTokens) {
+	const guidelinesMap = new Map(guidelinesTokens.map((t) => [t.name, t]));
+	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 = /* @__PURE__ */ 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;
+}
+function expandTokenPattern(token) {
+	const bracketRegex = /\[(.*?)\]/;
+	const match = token.name.match(bracketRegex);
+	if (!match) return [token];
+	return match[1].split(",").map((s) => s.trim()).map((variant) => ({
+		...token,
+		name: token.name.replace(bracketRegex, variant)
+	}));
+}
+function loadAllTokensWithGuidelines() {
+	try {
+		return buildAllTokens(parseDesignTokensSpec(loadDesignTokensSpec()));
+	} catch {
+		return buildAllTokens([]);
+	}
+}
+function loadDesignTokensGuide() {
+	return readFileSync(createRequire(import.meta.url).resolve("@primer/primitives/DESIGN_TOKENS_GUIDE.md"), "utf-8");
+}
+function loadDesignTokensSpec() {
+	return readFileSync(createRequire(import.meta.url).resolve("@primer/primitives/DESIGN_TOKENS_SPEC.md"), "utf-8");
+}
+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(--focus-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();
+}
+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(--focus-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();
+}
+function searchTokens(allTokens, query, group) {
+	const expandedTokens = allTokens.flatMap(expandTokenPattern);
+	const keywords = query.toLowerCase().split(/\s+/).filter((k) => k.length > 0);
+	return expandedTokens.filter((token) => {
+		const searchableText = `${token.name} ${token.useCase} ${token.rules} ${token.group}`.toLowerCase();
+		const matchesKeywords = keywords.every((word) => searchableText.includes(word));
+		const matchesGroup = !group || tokenMatchesGroup(token, group);
+		return matchesKeywords && matchesGroup;
+	});
+}
+const GROUP_ALIASES = {
+	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",
+	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",
+	stack: "stack",
+	controlstack: "controlStack",
+	padding: "stack",
+	margin: "stack",
+	gap: "stack",
+	spacing: "stack",
+	layout: "stack",
+	offset: "focus",
+	outline: "outline",
+	ring: "focus",
+	borderwidth: "borderWidth",
+	line: "borderColor",
+	stroke: "borderColor",
+	separator: "borderColor",
+	red: "danger",
+	green: "success",
+	yellow: "attention",
+	orange: "severe",
+	blue: "accent",
+	purple: "done",
+	pink: "sponsors",
+	grey: "neutral",
+	gray: "neutral",
+	light: "muted",
+	subtle: "muted",
+	dark: "emphasis",
+	strong: "emphasis",
+	intense: "emphasis",
+	bold: "emphasis",
+	vivid: "emphasis",
+	highlight: "emphasis"
+};
+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;
+}
+function formatBundle(bundleTokens) {
+	const grouped = bundleTokens.reduce((acc, token) => {
+		const group = GROUP_LABELS[token.group] || token.group || "Ungrouped";
+		if (!acc[group]) acc[group] = [];
+		acc[group].push(token);
+		return acc;
+	}, {});
+	return Object.entries(grouped).map(([group, groupTokens]) => {
+		return `## ${group}\n\n${groupTokens.map((t) => {
+			return `- ${t.value ? `\`${t.name}\` → \`${t.value}\`` : `\`${t.name}\``}\n  - **U**: ${t.useCase || "(none)"}\n  - **R**: ${t.rules || "(none)"}`;
+		}).join("\n")}`;
+	}).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.";
+	const uniqueGroups = Array.from(new Set(validTokens.map((t) => t.group)));
+	uniqueGroups.sort((a, b) => a.localeCompare(b));
+	return uniqueGroups.map((g) => `\`${g}\``).join(", ");
+}
+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);`"
+};
+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 = /* @__PURE__ */ 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();
+	});
+}
+//#endregion
+//#region src/server.ts
+const server = new McpServer({
+	name: "Primer",
+	version: "0.4.0"
+});
+const turndownService = new TurndownService();
+const allTokensWithGuidelines = loadAllTokensWithGuidelines();
+server.registerTool("init", {
+	description: "Setup or create a project that includes Primer React",
+	annotations: { readOnlyHint: true }
+}, 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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	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
+
+---
+
+${turndownService.turndown(source)}
+`
+	}] };
+});
+server.registerTool("list_components", {
+	description: "List all of the components available from Primer React",
+	annotations: { readOnlyHint: true }
+}, async () => {
+	return { content: [{
+		type: "text",
+		text: `The following components are available in the @primer/react in TypeScript projects:
+
+${listComponents().map((component) => {
+			return `- ${component.name}`;
+		}).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") },
+	annotations: { readOnlyHint: true }
+}, async ({ name }) => {
+	const match = listComponents().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: []
+	};
+	try {
+		const llmsUrl = new URL(`/product/components/${match.slug}/llms.txt`, "https://primer.style");
+		const llmsResponse = await fetch(llmsUrl);
+		if (llmsResponse.ok) return { content: [{
+			type: "text",
+			text: await llmsResponse.text()
+		}] };
+	} catch (_) {}
+	return {
+		isError: true,
+		errorMessage: `There was an error fetching documentation for ${name}. Ensure the component exists.`,
+		content: []
+	};
+});
+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") },
+	annotations: { readOnlyHint: true }
+}, async ({ name }) => {
+	const match = listComponents().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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	return { content: [{
+		type: "text",
+		text: `Here are some examples of how to use the \`${name}\` component from the @primer/react package:
+
+${turndownService.turndown(source)}`
+	}] };
+});
+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") },
+	annotations: { readOnlyHint: true }
+}, async ({ name }) => {
+	const match = listComponents().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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	return { content: [{
+		type: "text",
+		text: `Here are the usage guidelines for the \`${name}\` component from the @primer/react package:
+
+${turndownService.turndown(source)}`
+	}] };
+});
+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") },
+	annotations: { readOnlyHint: true }
+}, async ({ name }) => {
+	const match = listComponents().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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	return { content: [{
+		type: "text",
+		text: `Here are the accessibility guidelines for the \`${name}\` component from the @primer/react package:
+
+${turndownService.turndown(source)}`
+	}] };
+});
+server.registerTool("list_patterns", {
+	description: "List all of the patterns available from Primer React. Scenario patterns describe specific user tasks (copy, delete, filter, search). Prefer a scenario pattern when one fits the task, and fall back to the more generic UI patterns otherwise.",
+	annotations: { readOnlyHint: true }
+}, async () => {
+	const all = listPatterns();
+	const scenario = all.filter((pattern) => pattern.category === "scenario").map((pattern) => `- ${pattern.name}`);
+	const ui = all.filter((pattern) => pattern.category === "ui").map((pattern) => `- ${pattern.name}`);
+	return { content: [{
+		type: "text",
+		text: `The following patterns are available from \`@primer/react\` for use in TypeScript projects. Scenario patterns describe specific user tasks. Prefer a scenario pattern when one fits the task, and fall back to the UI patterns otherwise.
+
+## Scenario patterns
+
+${scenario.join("\n")}
+
+## UI patterns
+
+${ui.join("\n")}`
+	}] };
+});
+server.registerTool("get_pattern", {
+	description: "Get a specific pattern by name. Scenario patterns describe specific user tasks (copy, delete, filter, search). Prefer a scenario pattern when one fits the task, and fall back to the more generic UI patterns otherwise.",
+	inputSchema: { name: z.string().describe("The name of the pattern to retrieve") },
+	annotations: { readOnlyHint: true }
+}, async ({ name }) => {
+	const patterns = listPatterns();
+	const match = patterns.find((pattern) => pattern.category === "scenario" && pattern.name === name) ?? patterns.find((pattern) => 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 basePath = match.category === "scenario" ? "scenario-patterns" : "ui-patterns";
+	const url = new URL(`/product/${basePath}/${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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	return { content: [{
+		type: "text",
+		text: `Here are the guidelines for the \`${name}\` pattern for Primer:
+
+${turndownService.turndown(source)}`
+	}] };
+});
+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")
+	},
+	annotations: { readOnlyHint: true }
+}, async ({ query, group, limit }) => {
+	const resolvedGroup = group ? GROUP_ALIASES[group.toLowerCase().replace(/\s+/g, "")] || group : void 0;
+	const rawKeywords = query.toLowerCase().split(/\s+/).filter((k) => k.length > 0);
+	let effectiveGroup = resolvedGroup;
+	const filteredKeywords = [];
+	for (const kw of rawKeywords) {
+		const aliasMatch = GROUP_ALIASES[kw.replace(/\s+/g, "")];
+		if (aliasMatch && !effectiveGroup) effectiveGroup = aliasMatch;
+		else filteredKeywords.push(kw);
+	}
+	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."
+	}] };
+	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\"])") },
+	annotations: { readOnlyHint: true }
+}, async ({ groups }) => {
+	const resolvedGroups = groups.map((g) => {
+		return GROUP_ALIASES[g.toLowerCase().replace(/\s+/g, "")] || g;
+	});
+	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.",
+	annotations: { readOnlyHint: true }
+}, async () => {
+	const customRules = getDesignTokenSpecsText(listTokenGroups());
+	let text;
+	try {
+		text = `${customRules}\n\n---\n\n${loadDesignTokensGuide()}`;
+	} 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.",
+	annotations: { readOnlyHint: true }
+}, async () => {
+	const customPatterns = getTokenUsagePatternsText();
+	let text;
+	try {
+		const goldenExampleMatch = loadDesignTokensGuide().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() },
+	annotations: { readOnlyHint: true }
+}, async ({ css }) => {
+	try {
+		const { stdout } = await runStylelint(css);
+		return { content: [{
+			type: "text",
+			text: stdout || "✅ Stylelint passed (or was successfully autofixed)."
+		}] };
+	} catch (error) {
+		return { content: [{
+			type: "text",
+			text: `❌ Errors without autofix remaining:\n${error instanceof Error && "stdout" in error ? error.stdout : String(error)}`
+		}] };
+	}
+});
+server.registerTool("get_color_usage", {
+	description: "Get the guidelines for how to apply color to a user interface",
+	annotations: { readOnlyHint: true }
+}, 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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	return { content: [{
+		type: "text",
+		text: `Here is the documentation for color usage in Primer:\n\n${turndownService.turndown(source)}`
+	}] };
+});
+server.registerTool("get_typography_usage", {
+	description: "Get the guidelines for how to apply typography to a user interface",
+	annotations: { readOnlyHint: true }
+}, 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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	return { content: [{
+		type: "text",
+		text: `Here is the documentation for typography usage in Primer:\n\n${turndownService.turndown(source)}`
+	}] };
+});
+server.registerTool("list_icons", {
+	description: "List all of the icons (octicons) available from Primer Octicons React",
+	annotations: { readOnlyHint: true }
+}, async () => {
+	return { content: [{
+		type: "text",
+		text: `The following icons are available in the @primer/octicons-react package in TypeScript projects:
+
+${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");
+		}).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")
+	},
+	annotations: { readOnlyHint: true }
+}, async ({ name, size }) => {
+	const match = listIcons().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 source = cheerio.load(html)("main").html();
+	if (!source) return { content: [] };
+	return { content: [{
+		type: "text",
+		text: `Here is the documentation for the \`${name}\` icon at size: \`${size}\`:
+${turndownService.turndown(source)}`
+	}] };
+});
+server.registerTool("primer_coding_guidelines", {
+	description: "Get the guidelines when writing code that uses Primer or for UI code that you are creating",
+	annotations: { readOnlyHint: true }
+}, 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.
+`
+	}] };
+});
+/**
+* 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")
+	},
+	annotations: { readOnlyHint: true }
+}, async ({ surroundingText, alt, image }) => {
+	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: .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.`
+	};
+});
+//#endregion
+export { server as t };