Add Primer Brand MCP server

[rezrah]

Summary

Adds the Primer Brand MCP server (@primer/brand-mcp) to the monorepo + NPM registry.

Ships with 8 tools right now, all of which help Agents understand how to use Primer Brand without needing to learn it all from scratch through online fetching.

For provenance, I've manually released the first version to NPM, but all future releases will ship through CI like other packages.

Towards https://github.com/github/brand-experience/issues/248

🔗 Docs preview

List of notable changes:

• Adds the package under /packages/mcp
• Publish flows to NPM are same as existing flows: changeset, canary-compatible, etc
• Added a docs page: https://primer-3ccd672b42-26139705.drafts.github.io/brand/introduction/mcp/
• Fixed two Hero issues, which were preventing the MCP tools from building the page correctly. One was related to invalid prop combinations on gridline-epressive variants. You can no longer use align="center" there anymore.

Steps to test:

1. Go to our brandx-evals dashborad here and see how the harness invokes mcp tools. Flag anything that looks off.
2. Install the server in Copilot CLI or Desktop App and try it yourself

Contributor checklist:

• All new and existing CI checks pass
• Tests prove that the feature works and covers both happy and unhappy paths
• Any drop in coverage, breaking changes or regressions have been documented above
• UI Changes contain new visual snapshots (generated by adding update snapshots label to the PR)
• All developer debugging and non-functional logging has been removed
• Related issues have been referenced in the PR description

Reviewer checklist:

• Check that pull request and proposed changes adhere to our contribution guidelines and code of conduct
• Check that tests prove the feature works and covers both happy and unhappy paths
• Check that there aren't other open Pull Requests for the same update/change

Screenshots:

Eval output from our eval test suite

Agent self-invoking tools:

For the following prompt:

Refresh the GitHub Skills landing page to match current modern GitHub branding: a clean hero section and a grid of the available learning pathways. Do not add new functionality like user profiles, login states, or achievement badges. Keep it simple and educational.

We get the following results with the MCP server enabled

Before MCP server (No Primer Brand usage)	With MCP Server (100% Primer Brand usage)

Hero component fix to prevent align='center' being used when variant="gridline-expressive"

Before	After

[changeset-bot]

🦋 Changeset detected

Latest commit: 5cbe92b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 9 packages

Name	Type
@primer/react-brand	Minor
@primer/brand-mcp	Minor
@primer/brand-docs	Minor
@primer/brand-css	Minor
@primer/brand-primitives	Minor
@primer/brand-e2e	Minor
@primer/brand-fonts	Minor
@primer/brand-config	Minor
@primer/brand-storybook	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🟢 No design token changes found

[github-actions]

🟢 Bundle size report

Check	Main	Branch	Change
UMD — full bundle (JS)	101.20 kB	101.33 kB	⬆️ +136 B (+0.1%)
UMD — full bundle (CSS)	66.78 kB	66.78 kB	🟢 No change
ESM — full bundle (JS + CSS)	1.51 MB	1.51 MB	✅ -106 B (-0.0%)
ESM — tree-shaken simple (Button)	69.66 kB	69.66 kB	🟢 No change
ESM — tree-shaken complex (ActionMenu)	78.44 kB	78.44 kB	🟢 No change

[github-actions]

🟢 Unit test coverage changes found

Unit test coverage has been updated through this PR.

Changes: 0 new tests, 0 removed tests, 1 improved, 0 decreased

Component/Hook	Statements	Functions	Branches	Change
Hero	93.3% 93.8%	88.9%	91.9% 92.4%	+0.5%

[github-actions]

🟢 No visual differences found

Our visual comparison tests did not find any differences in the UI.

[Copilot]

Pull request overview

Adds a new @primer/brand-mcp package that exposes an MCP (Model Context Protocol) server for Primer Brand guidance/tools, and updates the Heading component’s JSDoc to clarify semantic vs visual sizing. CI is also updated to run an MCP smoke test.

Changes:

• Introduce packages/mcp (Node stdio MCP server) with tool modules (primer_brand_setup, primer_brand_component, primer_brand_examples, primer_brand_tokens, primer_brand_asset, primer_brand_docs, primer_brand_review), catalog loading/generation, and supporting utilities.
• Add unit tests + an end-to-end smoke script for the MCP server and wire the smoke step into CI.
• Add JSDoc guidance to Heading props (as, size) and component-level doc.

Show a summary per file

File	Description
packages/react/src/Heading/Heading.tsx	Adds JSDoc clarifying as (semantic) vs size (visual) usage for Heading.
packages/mcp/tsconfig.json	TypeScript config for the new MCP workspace (NodeNext/strict build).
packages/mcp/tsconfig.eslint.json	ESLint TS project config for the MCP workspace.
packages/mcp/src/util/text.ts	Adds text helpers for escaping regex and deterministic relevance ranking.
packages/mcp/src/tools/types.ts	Defines shared tool context/result/module types for MCP tool implementations.
packages/mcp/src/tools/register.ts	Registers MCP tools with the server and centralizes tool execution/error handling.
packages/mcp/src/tools/primer-brand-tokens/primer-brand-tokens.ts	Implements primer_brand_tokens (intent-based token search + grouping).
packages/mcp/src/tools/primer-brand-tokens/primer-brand-tokens.test.ts	Unit tests for token lookup, intent mapping, grouping, and empty-catalog errors.
packages/mcp/src/tools/primer-brand-tokens/index.ts	Barrel export for primer_brand_tokens.
packages/mcp/src/tools/primer-brand-setup/primer-brand-setup.ts	Implements primer_brand_setup (framework-aware setup snippets + guidance).
packages/mcp/src/tools/primer-brand-setup/primer-brand-setup.test.ts	Unit tests for framework-specific setup output and guidance content.
packages/mcp/src/tools/primer-brand-setup/index.ts	Barrel export for primer_brand_setup.
packages/mcp/src/tools/primer-brand-review/primer-brand-review.ts	Implements primer_brand_review wrapper over the rule engine with formatting + CSS reminder.
packages/mcp/src/tools/primer-brand-review/primer-brand-review.test.ts	Unit tests for CSS reminder behavior and sample findings.
packages/mcp/src/tools/primer-brand-review/index.ts	Barrel export for primer_brand_review.
packages/mcp/src/tools/primer-brand-examples/primer-brand-examples.ts	Implements primer_brand_examples to rank and emit tested story examples.
packages/mcp/src/tools/primer-brand-examples/primer-brand-examples.test.ts	Unit tests for ranking, default fallback, and “no stub examples” behavior.
packages/mcp/src/tools/primer-brand-examples/index.ts	Barrel export for primer_brand_examples.
packages/mcp/src/tools/primer-brand-docs/primer-brand-docs.ts	Implements primer_brand_docs to index/search/read bundled or live docs.
packages/mcp/src/tools/primer-brand-docs/index.ts	Barrel export for primer_brand_docs.
packages/mcp/src/tools/primer-brand-component/primer-brand-component.ts	Implements primer_brand_component for component listing and per-component API output.
packages/mcp/src/tools/primer-brand-component/primer-brand-component.test.ts	Unit tests for listing, lookup, suggestions, and rendered content.
packages/mcp/src/tools/primer-brand-component/index.ts	Barrel export for primer_brand_component.
packages/mcp/src/tools/primer-brand-asset/primer-brand-asset.ts	Implements primer_brand_asset to search icons/illustrations and emit imports.
packages/mcp/src/tools/primer-brand-asset/primer-brand-asset.test.ts	Unit tests for query ranking, kind filtering, and origin note behavior.
packages/mcp/src/tools/primer-brand-asset/index.ts	Barrel export for primer_brand_asset.
packages/mcp/src/tools/format.ts	Adds shared formatting helpers (component rank fields, prop rendering, version provenance).
packages/mcp/src/test-support/catalog.ts	Adds deterministic catalog/context fixtures for MCP tool tests.
packages/mcp/src/server.ts	Creates the MCP server, loads catalog, detects installed Brand/assets/docs, registers tools.
packages/mcp/src/review/types.ts	Defines review rule/finding types and evidence snippet helper.
packages/mcp/src/review/rules.ts	Implements the on-brand rule set used by primer_brand_review.
packages/mcp/src/review/rules.test.ts	Unit tests for the rule set + guard against errors on generated catalog examples.
packages/mcp/src/logger.ts	Adds stderr-only logger to avoid corrupting the stdio JSON-RPC stream.
packages/mcp/src/index.ts	Adds the stdio entrypoint that connects the MCP server to the stdio transport.
packages/mcp/src/catalog/types.ts	Defines the build-generated catalog schema (components/assets/tokens).
packages/mcp/src/catalog/load.ts	Loads the bundled catalog.json, falling back to an empty catalog when unavailable.
packages/mcp/src/brand/resolve-install.ts	Detects an installed @primer/react-brand in the consumer project for version-awareness.
packages/mcp/src/brand/resolve-assets.ts	Extracts installed Octicons/Octovisuals exported names for version-accurate asset lookup.
packages/mcp/src/brand/resolve-assets.test.ts	Tests installed-asset resolution behavior (installed vs missing packages).
packages/mcp/src/brand/docs-source.ts	Implements bundled-docs-first, live-docs-fallback docs indexing/reading with caching and safety checks.
packages/mcp/src/brand/detect-framework.ts	Adds best-effort framework detection for tailored setup guidance.
packages/mcp/src/brand/detect-framework.test.ts	Tests framework detection behavior across Next/Vite/Astro/Remix/unknown.
packages/mcp/scripts/smoke.mjs	End-to-end stdio smoke test that spawns the built server and exercises tool calls.
packages/mcp/scripts/generate-catalog.mjs	Build-time generator for dist/catalog.json from repo source, docs, stories, assets, and tokens.
packages/mcp/README.md	Documents the MCP package purpose, tool list, and setup snippets.
packages/mcp/package.json	Declares the new package, scripts (build/test/smoke), bin entry, deps, and engines.
packages/mcp/jest.config.mjs	Jest config for ESM TypeScript tests in the MCP workspace.
packages/mcp/eslint.config.mjs	ESLint config tuned for machine-facing protocol text and NodeNext resolution.
packages/mcp/.prettierignore	Ignores build/test artifacts in the MCP workspace.
packages/mcp/.gitignore	Ignores build/test artifacts in the MCP workspace.
.github/workflows/ci.yml	Adds an MCP smoke-test step to CI after unit tests.
.changeset/primer-brand-mcp.md	Changeset introducing the new @primer/brand-mcp package (minor bump).
.changeset/heading-usage-guidance.md	Changeset for Heading JSDoc guidance (patch bump).

Review details

• Files reviewed: 53/54 changed files
• Comments generated: 4
• Review effort level: Low