Add MCP component recommendations

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 32388d20-7134-40a1-af5d-8325d6bea553

Author: adierkens

.changeset/recommend-mcp-components.md

@@ -0,0 +1,5 @@
+---
+'@primer/mcp': minor
+---
+
+MCP: Add deterministic Primer pattern and public component recommendations for product UI intent.

packages/mcp/README.md

@@ -79,6 +79,17 @@ conversion. The compact parser intentionally fails when it cannot identify the
 page's guidance body, rather than returning navigation content as pattern
 guidance.
 
+## Recommendations
+
+`recommend_components` maps freeform product or UI intent to a bounded set of
+Primer patterns and public `@primer/react` component candidates. Optional
+surface, region, pattern-hint, state, constraint, existing-component, and
+preferred-component signals refine deterministic lexical ranking. Results
+include the source URLs and kinds for pattern links and package-derived
+composition evidence. Deprecated, incompatible, and Primer-internal references
+are excluded from installable component candidates; unresolved internal links
+remain source-labeled evidence.
+
 ## 🙌 Contributing
 
 We love collaborating with folks inside and outside of GitHub and welcome contributions! If you're interested, check out our [contributing docs](contributor-docs/CONTRIBUTING.md) for more info on how to get started.

packages/mcp/src/recommendations.test.ts

@@ -0,0 +1,174 @@
+import {describe, expect, it} from 'vitest'
+import type {CompactPatternDetails} from './patterns'
+import {createRecommendation, formatRecommendation, rankPatterns, type RecommendationComponent} from './recommendations'
+import {listPatterns} from './primer'
+
+const sourceUrl = 'https://primer.style/product/components/text-input'
+const searchDetails: CompactPatternDetails = {
+  detail: 'compact',
+  pattern: {
+    id: 'search',
+    name: 'Search',
+    category: 'scenario',
+    sourceUrl: 'https://primer.style/product/scenario-patterns/search',
+  },
+  summary: 'Search guidance.',
+  components: [
+    {id: 'text-input', name: 'TextInput', source: 'primer-public', sourceUrl},
+    {
+      id: 'filter',
+      name: 'Filter',
+      source: 'primer-internal',
+      sourceUrl: 'https://primer.style/product/internal-components/filter',
+    },
+    {
+      id: 'octicon',
+      name: 'Octicon',
+      source: 'primer-public',
+      sourceUrl: 'https://primer.style/product/components/octicon',
+    },
+  ],
+  relatedPatterns: [],
+  guidance: {implementation: '', accessibility: [], states: []},
+}
+const filterDetails: CompactPatternDetails = {
+  ...searchDetails,
+  pattern: {
+    id: 'filter',
+    name: 'Filter',
+    category: 'scenario',
+    sourceUrl: 'https://primer.style/product/scenario-patterns/filter',
+  },
+  components: [
+    {
+      id: 'action-menu',
+      name: 'ActionMenu',
+      source: 'primer-public',
+      sourceUrl: 'https://primer.style/product/components/action-menu',
+    },
+  ],
+}
+const components: Array<RecommendationComponent> = [
+  {
+    id: 'text_input',
+    name: 'TextInput',
+    importPath: '@primer/react',
+    sourceUrl,
+    searchTerms: ['TextInput', 'query', 'search'],
+  },
+  {
+    id: 'action_menu',
+    name: 'ActionMenu',
+    importPath: '@primer/react',
+    sourceUrl: 'https://primer.style/product/components/action-menu',
+    searchTerms: ['ActionMenu', 'filter'],
+    composition: {
+      apiParentChild: [],
+      apiSubcomponents: [],
+      observed: {
+        parentChild: [{parent: 'ActionMenu.Overlay', child: 'ActionList', sourceCount: 2}],
+        adjacentSibling: [],
+        variants: [],
+        relatedComponents: [],
+      },
+    },
+  },
+  {
+    id: 'action_list',
+    name: 'ActionList',
+    importPath: '@primer/react',
+    sourceUrl: 'https://primer.style/product/components/action-list',
+    searchTerms: ['ActionList'],
+  },
+  {
+    id: 'octicon',
+    name: 'Octicon',
+    importPath: '@primer/react/deprecated',
+    status: 'deprecated',
+    sourceUrl: 'https://primer.style/product/components/octicon',
+    searchTerms: ['Octicon'],
+  },
+]
+
+describe('component recommendations', () => {
+  it('matches simple intent to authoritative pattern-linked public components', () => {
+    const input = {intent: 'Add a search query'}
+    const result = createRecommendation(input, rankPatterns(listPatterns(), input), [searchDetails], components)
+
+    expect(result.status).toBe('matched')
+    expect(result.patterns[0]?.pattern.name).toBe('Search')
+    expect(result.components[0]?.component).toMatchObject({name: 'TextInput', sourceKind: 'primer-public'})
+    expect(formatRecommendation(result)).toContain('Public components')
+  })
+
+  it('lets structured pattern hints outweigh freeform intent', () => {
+    const input = {intent: 'search', patternHints: ['filter']}
+    const result = createRecommendation(
+      input,
+      rankPatterns(listPatterns(), input),
+      [searchDetails, filterDetails],
+      components,
+    )
+
+    expect(result.patterns[0]?.pattern.name).toBe('Filter')
+    expect(result.matchedSignals.patternHints).toEqual(['filter'])
+  })
+
+  it('expands source-derived composition relationships without inventing mappings', () => {
+    const input = {intent: 'filter'}
+    const result = createRecommendation(input, rankPatterns(listPatterns(), input), [filterDetails], components)
+
+    expect(result.components.map(candidate => candidate.component.name)).toEqual(['ActionMenu', 'ActionList'])
+    expect(result.components[1]?.evidence[0]).toMatchObject({sourceKind: 'composition'})
+  })
+
+  it('reports ambiguous and no-match intent with actionable states', () => {
+    const ambiguous = {intent: 'search filter'}
+    const noMatch = {intent: 'calendar'}
+
+    expect(
+      createRecommendation(
+        ambiguous,
+        rankPatterns(listPatterns(), ambiguous),
+        [searchDetails, filterDetails],
+        components,
+      ).status,
+    ).toBe('ambiguous')
+    expect(createRecommendation(noMatch, rankPatterns(listPatterns(), noMatch), [], components)).toMatchObject({
+      status: 'no-match',
+      nextAction: expect.stringContaining('pattern hint'),
+    })
+  })
+
+  it('excludes deprecated candidates and retains internal references as unresolved evidence', () => {
+    const input = {intent: 'search'}
+    const result = createRecommendation(input, rankPatterns(listPatterns(), input), [searchDetails], components)
+
+    expect(result.components.map(candidate => candidate.component.name)).not.toContain('Octicon')
+    expect(result.exclusions).toContainEqual({name: 'Octicon', source: 'primer-public', reason: 'deprecated'})
+    expect(result.unresolvedReferences).toContainEqual(
+      expect.objectContaining({name: 'Filter', source: 'primer-internal', reason: 'internal-reference'}),
+    )
+  })
+
+  it('uses stable lexical ordering and bounded payloads', () => {
+    const input = {intent: 'search filter', limit: 1}
+    const first = createRecommendation(
+      input,
+      rankPatterns(listPatterns(), input),
+      [searchDetails, filterDetails],
+      components,
+    )
+    const second = createRecommendation(
+      input,
+      rankPatterns(listPatterns(), input),
+      [searchDetails, filterDetails],
+      components,
+    )
+
+    expect(first).toEqual(second)
+    expect(first.patterns).toHaveLength(1)
+    expect(first.components).toHaveLength(1)
+    expect(JSON.stringify(first).length).toBeLessThan(5_000)
+  })
+})