Proposal: add source-derived component composition metadata

[adierkens]

Changelog

New

• Proposal: publish structured, source-derived component composition metadata from @primer/react/generated/components.json.
• Add the read-only get_component_composition MCP tool and package-backed component documentation sources for get_component and get_component_batch.

Changed

• Package-mode batches return compact, composition-first summaries: identity/import/status, documented API relationships, and at most three highest-evidence observations per relationship type.
• Batch results include omitted-observation counts, deterministic occurrence/source-count confidence evidence, and no props, story source, global derivation, or source summary payloads.

Removed

• N/A

Rollout strategy

• Patch release
• Minor release
• Major release; if selected, include a written rollout or migration plan
• None; if selected, include a brief description as to why

Testing & Reviewing

Composition metadata is generated from canonical public Primer React sources, rather than separately maintained MCP-specific prose. API declarations describe documented availability only; observed records require at least two distinct source units and do not claim universal semantic correctness. Dynamic JSX and runtime children are excluded.

MCP consumption: get_component_composition exposes full filtered package-backed composition. get_component and get_component_batch default to hosted Primer Style documentation, or return installed metadata with source: "package" / PRIMER_COMPONENT_DOCS_SOURCE=package. Package-mode batches intentionally omit full generated documents and retain get_component for full documentation and provenance.

Truncation guard: SDK protocol tests cover NavList, SegmentedControl, CounterLabel, and Avatar below 20 KB, plus the high-connectivity ActionList plus SegmentedControl batch below 15 KB. Batch summaries cap observed rows to the three strongest records per type and surface omitted counts.

Package/canary boundary: packed React metadata contains composition schema version 1. The current MCP canary artifact is primer-mcp-0.5.0.tgz with SHA-256 c0a4c10e23235b9dc9e4510c08828a9d183f303c52821cc4f57e0757c3900306.

Validated with:

• npm run build (Node 26.4.0)
• npm run type-check -w @primer/react
• npm run type-check -w @primer/mcp
• npm test -w @primer/mcp
• npm run lint
• npm run lint:md
• npm run format:diff
• npx vitest --config vitest.config.mts --run src/__tests__/component-composition.test.ts (from packages/react)
• package builds and npm pack checks for @primer/react and @primer/mcp

[changeset-bot]

🦋 Changeset detected

Latest commit: e24f81d

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

This PR includes changesets to release 2 packages

Name	Type
@primer/react	Minor
@primer/mcp	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]

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.