@primer/mcp 0.0.2 → 0.0.4

package/src/server.ts

@@ -3,7 +3,8 @@ import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js'
 import * as cheerio from 'cheerio'
 import {z} from 'zod'
 import TurndownService from 'turndown'
-import {listComponents, listPatterns} from './primer'
+import {listComponents, listPatterns, listIcons} from './primer'
+import {tokens, serialize} from './primitives'
 import packageJson from '../package.json' with {type: 'json'}
 
 const server = new McpServer({
@@ -13,10 +14,59 @@ const server = new McpServer({
 
 const turndownService = new TurndownService()
 
+// -----------------------------------------------------------------------------
+// Project setup
+// -----------------------------------------------------------------------------
+server.tool('init', '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.tool('get_components', 'List all of the components available from Primer React', async () => {
+server.tool('list_components', 'List all of the components available from Primer React', async () => {
   const components = listComponents().map(component => {
     return `- ${component.name}`
   })
@@ -43,7 +93,7 @@ server.tool(
   async ({name}) => {
     const components = listComponents()
     const match = components.find(component => {
-      return component.name === name
+      return component.name === name || component.name.toLowerCase() === name.toLowerCase()
     })
     if (!match) {
       return {
@@ -56,7 +106,7 @@ server.tool(
       }
     }
 
-    const url = new URL(`/product/components/${match.id}`, 'https://primer.style')
+    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}`)
@@ -364,432 +414,14 @@ ${text}`,
   },
 )
 
-type Token = TokenCategory | string
-type TokenCategory = {
-  category: string
-  tokens: Array<Token>
-}
-
-const tokens: Array<Token> = [
-  {
-    category: 'color',
-    tokens: [
-      {
-        category: 'foreground',
-        tokens: [
-          '--fgColor-accent',
-          '--fgColor-attention',
-          '--fgColor-black',
-          '--fgColor-closed',
-          '--fgColor-danger',
-          '--fgColor-default',
-          '--fgColor-disabled',
-          '--fgColor-done',
-          '--fgColor-link',
-          '--fgColor-muted',
-          '--fgColor-neutral',
-          '--fgColor-onEmphasis',
-          '--fgColor-onInverse',
-          '--fgColor-open',
-          '--fgColor-severe',
-          '--fgColor-sponsors',
-          '--fgColor-success',
-          '--fgColor-upsell',
-          '--fgColor-white',
-        ],
-      },
-      {
-        category: 'background',
-        tokens: [
-          '--bgColor-accent-emphasis',
-          '--bgColor-accent-muted',
-          '--bgColor-attention-emphasis',
-          '--bgColor-attention-muted',
-          '--bgColor-black',
-          '--bgColor-closed-emphasis',
-          '--bgColor-closed-muted',
-          '--bgColor-danger-emphasis',
-          '--bgColor-danger-muted',
-          '--bgColor-default',
-          '--bgColor-disabled',
-          '--bgColor-done-emphasis',
-          '--bgColor-done-muted',
-          '--bgColor-emphasis',
-          '--bgColor-inset',
-          '--bgColor-inverse',
-          '--bgColor-muted',
-          '--bgColor-neutral-emphasis',
-          '--bgColor-neutral-muted',
-          '--bgColor-open-emphasis',
-          '--bgColor-open-muted',
-          '--bgColor-severe-emphasis',
-          '--bgColor-severe-muted',
-          '--bgColor-sponsors-emphasis',
-          '--bgColor-sponsors-muted',
-          '--bgColor-success-emphasis',
-          '--bgColor-success-muted',
-          '--bgColor-transparent',
-          '--bgColor-upsell-emphasis',
-          '--bgColor-upsell-muted',
-          '--bgColor-white',
-        ],
-      },
-      {
-        category: 'border',
-        tokens: [
-          '--borderColor-accent-emphasis',
-          '--borderColor-accent-muted',
-          '--borderColor-attention-emphasis',
-          '--borderColor-attention-muted',
-          '--borderColor-closed-emphasis',
-          '--borderColor-closed-muted',
-          '--borderColor-danger-emphasis',
-          '--borderColor-danger-muted',
-          '--borderColor-default',
-          '--borderColor-disabled',
-          '--borderColor-done-emphasis',
-          '--borderColor-done-muted',
-          '--borderColor-emphasis',
-          '--borderColor-muted',
-          '--borderColor-neutral-emphasis',
-          '--borderColor-neutral-muted',
-          '--borderColor-open-emphasis',
-          '--borderColor-open-muted',
-          '--borderColor-severe-emphasis',
-          '--borderColor-severe-muted',
-          '--borderColor-sponsors-emphasis',
-          '--borderColor-sponsors-muted',
-          '--borderColor-success-emphasis',
-          '--borderColor-success-muted',
-          '--borderColor-translucent',
-          '--borderColor-transparent',
-          '--borderColor-upsell-emphasis',
-          '--borderColor-upsell-muted',
-        ],
-      },
-      {
-        category: 'shadow',
-        tokens: [
-          '--shadow-floating-large',
-          '--shadow-floating-legacy',
-          '--shadow-floating-medium',
-          '--shadow-floating-small',
-          '--shadow-floating-xlarge',
-          '--shadow-inset',
-          '--shadow-resting-medium',
-          '--shadow-resting-small',
-          '--shadow-resting-xsmall',
-        ],
-      },
-      {
-        category: 'control',
-        tokens: [
-          '--control-bgColor-active',
-          '--control-bgColor-disabled',
-          '--control-bgColor-hover',
-          '--control-bgColor-rest',
-          '--control-bgColor-selected',
-          '--control-borderColor-danger',
-          '--control-borderColor-disabled',
-          '--control-borderColor-emphasis',
-          '--control-borderColor-rest',
-          '--control-borderColor-selected',
-          '--control-borderColor-success',
-          '--control-borderColor-warning',
-          '--control-checked-bgColor-active',
-          '--control-checked-bgColor-disabled',
-          '--control-checked-bgColor-hover',
-          '--control-checked-bgColor-rest',
-          '--control-checked-borderColor-active',
-          '--control-checked-borderColor-disabled',
-          '--control-checked-borderColor-hover',
-          '--control-checked-borderColor-rest',
-          '--control-checked-fgColor-disabled',
-          '--control-checked-fgColor-rest',
-          '--control-danger-bgColor-active',
-          '--control-danger-bgColor-hover',
-          '--control-danger-fgColor-hover',
-          '--control-danger-fgColor-rest',
-          '--control-fgColor-disabled',
-          '--control-fgColor-placeholder',
-          '--control-fgColor-rest',
-          '--control-iconColor-rest',
-          '--control-transparent-bgColor-active',
-          '--control-transparent-bgColor-disabled',
-          '--control-transparent-bgColor-hover',
-          '--control-transparent-bgColor-rest',
-          '--control-transparent-bgColor-selected',
-          '--control-transparent-borderColor-active',
-          '--control-transparent-borderColor-hover',
-          '--control-transparent-borderColor-rest',
-        ],
-      },
-      {
-        category: 'focus',
-        tokens: ['--focus-outlineColor'],
-      },
-      {
-        category: 'overlay',
-        tokens: ['--overlay-background-bgColor', '--overlay-bgColor', '--overlay-borderColor'],
-      },
-    ],
-  },
-  {
-    category: 'size',
-    tokens: [
-      {
-        category: 'base',
-        tokens: [
-          '--base-size-2',
-          '--base-size-4',
-          '--base-size-6',
-          '--base-size-8',
-          '--base-size-12',
-          '--base-size-16',
-          '--base-size-20',
-          '--base-size-24',
-          '--base-size-28',
-          '--base-size-32',
-          '--base-size-36',
-          '--base-size-40',
-          '--base-size-44',
-          '--base-size-48',
-          '--base-size-64',
-          '--base-size-80',
-          '--base-size-96',
-          '--base-size-112',
-          '--base-size-128',
-        ],
-      },
-      {
-        category: 'border',
-        tokens: [
-          {
-            category: 'border-size',
-            tokens: [
-              '--boxShadow-thick',
-              '--boxShadow-thicker',
-              '--boxShadow-thin',
-              '--borderWidth-default',
-              '--borderWidth-thick',
-              '--borderWidth-thicker',
-              '--borderWidth-thin',
-            ],
-          },
-          {
-            category: 'border-radius',
-            tokens: [
-              '--borderRadius-default',
-              '--borderRadius-full',
-              '--borderRadius-large',
-              '--borderRadius-medium',
-              '--borderRadius-small',
-            ],
-          },
-          {
-            category: 'outline',
-            tokens: ['--outline-focus-offset', '--outline-focus-width'],
-          },
-        ],
-      },
-      {
-        category: 'layout',
-        tokens: [
-          {
-            category: 'stack',
-            tokens: [
-              '--stack-gap-condensed',
-              '--stack-gap-normal',
-              '--stack-gap-spacious',
-              '--stack-padding-condensed',
-              '--stack-padding-normal',
-              '--stack-padding-spacious',
-            ],
-          },
-          {
-            category: 'controls',
-            tokens: [
-              '--controlStack-large-gap-auto',
-              '--controlStack-large-gap-condensed',
-              '--controlStack-large-gap-spacious',
-              '--controlStack-medium-gap-condensed',
-              '--controlStack-medium-gap-spacious',
-              '--controlStack-small-gap-condensed',
-              '--controlStack-small-gap-spacious',
-              '--controlStack-medium-gap-auto',
-              '--controlStack-small-gap-auto',
-
-              '--control-xsmall-gap',
-              '--control-small-gap',
-              '--control-medium-gap',
-              '--control-large-gap',
-              '--control-xlarge-gap',
-              '--control-xsmall-lineBoxHeight',
-              '--control-small-lineBoxHeight',
-              '--control-medium-lineBoxHeight',
-              '--control-large-lineBoxHeight',
-              '--control-xlarge-lineBoxHeight',
-              '--control-xsmall-paddingBlock',
-              '--control-small-paddingBlock',
-              '--control-medium-paddingBlock',
-              '--control-large-paddingBlock',
-              '--control-xlarge-paddingBlock',
-              '--control-xsmall-paddingInline-condensed',
-              '--control-small-paddingInline-condensed',
-              '--control-medium-paddingInline-condensed',
-              '--control-large-paddingInline-condensed',
-              '--control-xlarge-paddingInline-condensed',
-              '--control-xsmall-paddingInline-normal',
-              '--control-small-paddingInline-normal',
-              '--control-medium-paddingInline-normal',
-              '--control-large-paddingInline-normal',
-              '--control-xlarge-paddingInline-normal',
-              '--control-xsmall-paddingInline-spacious',
-              '--control-small-paddingInline-spacious',
-              '--control-medium-paddingInline-spacious',
-              '--control-large-paddingInline-spacious',
-              '--control-xlarge-paddingInline-spacious',
-              '--control-xsmall-size',
-              '--control-small-size',
-              '--control-medium-size',
-              '--control-large-size',
-              '--control-xlarge-size',
-            ],
-          },
-          {
-            category: 'overlay',
-            tokens: [
-              '--overlay-borderRadius',
-              '--overlay-height-large',
-              '--overlay-height-medium',
-              '--overlay-height-small',
-              '--overlay-height-xlarge',
-              '--overlay-offset',
-              '--overlay-padding-condensed',
-              '--overlay-padding-normal',
-              '--overlay-paddingBlock-condensed',
-              '--overlay-paddingBlock-normal',
-              '--overlay-width-large',
-              '--overlay-width-medium',
-              '--overlay-width-small',
-              '--overlay-width-xlarge',
-              '--overlay-width-xsmall',
-            ],
-          },
-        ],
-      },
-    ],
-  },
-  {
-    category: 'typography',
-    tokens: [
-      {
-        category: 'weight',
-        tokens: [
-          '--base-text-weight-light',
-          '--base-text-weight-normal',
-          '--base-text-weight-medium',
-          '--base-text-weight-semibold',
-        ],
-      },
-      {
-        category: 'font-family',
-        tokens: [
-          '--fontStack-monospace',
-          '--fontStack-sansSerif',
-          '--fontStack-sansSerifDisplay',
-          '--fontStack-system',
-        ],
-      },
-      {
-        category: 'font-shorthand',
-        tokens: [
-          '--text-body-shorthand-large',
-          '--text-body-shorthand-medium',
-          '--text-body-shorthand-small',
-          '--text-caption-shorthand',
-          '--text-codeBlock-shorthand',
-          '--text-codeInline-shorthand',
-          '--text-display-shorthand',
-          '--text-subtitle-shorthand',
-          '--text-title-shorthand-large',
-          '--text-title-shorthand-medium',
-          '--text-title-shorthand-small',
-        ],
-      },
-      {
-        category: 'display',
-        tokens: [
-          '--text-display-lineBoxHeight',
-          '--text-display-lineHeight',
-          '--text-display-size',
-          '--text-display-weight',
-        ],
-      },
-      {
-        category: 'title-large',
-        tokens: ['--text-title-lineHeight-large', '--text-title-size-large', '--text-title-weight-large'],
-      },
-      {
-        category: 'title-medium',
-        tokens: ['--text-title-lineHeight-medium', '--text-title-size-medium', '--text-title-weight-medium'],
-      },
-      {
-        category: 'title-small',
-        tokens: ['--text-title-lineHeight-small', '--text-title-size-small', '--text-title-weight-small'],
-      },
-      {
-        category: 'subtitle',
-        tokens: ['--text-subtitle-lineHeight', '--text-subtitle-size', '--text-subtitle-weight'],
-      },
-      {
-        category: 'body-large',
-        tokens: ['--text-body-lineHeight-large', '--text-body-size-large'],
-      },
-      {
-        category: 'body-medium',
-        tokens: ['--text-body-lineHeight-medium', '--text-body-size-medium'],
-      },
-      {
-        category: 'body-small',
-        tokens: ['--text-body-lineHeight-small', '--text-body-size-small'],
-      },
-      {
-        category: 'caption',
-        tokens: ['--text-caption-lineHeight', '--text-caption-size', '--text-caption-weight'],
-      },
-      {
-        category: 'code-block',
-        tokens: ['--text-codeBlock-lineHeight', '--text-codeBlock-size', '--text-codeBlock-weight'],
-      },
-      {
-        category: 'inline-code-block',
-        tokens: ['--text-codeInline-size', '--text-codeInline-weight'],
-      },
-    ],
-  },
-] as const
-
-function serialize(token: Token): string {
-  if (typeof token === 'string') {
-    // eslint-disable-next-line github/unescaped-html-literal
-    return `<token name="${token}"></token>`
-  }
-  // eslint-disable-next-line github/unescaped-html-literal
-  return `<token-category name="${token.category}">\n${token.tokens.map(serialize).join('\n')}\n</token-category>`
-}
-
 // -----------------------------------------------------------------------------
 // Design Tokens
 // -----------------------------------------------------------------------------
 server.tool('list_tokens', 'List all of the design tokens available from Primer', async () => {
   let text =
-    'Below is a list of all designs tokens available from Primer. They are organized by category. Tokens are used in CSS and CSS Modules. They can also be referred to in JavaScript files using the style attribute or prop in React components. To refer to the CSS Custom Property for a design token, wrap it in var(name-of-token). To learn how to use a specific token, use a corresponding usage tool for the category of the token. For example, if a token is a color token look for the get_color_usage tool. \n\n'
+    'Below is a list of all design tokens available from Primer. Tokens are used in CSS and CSS Modules. To refer to the CSS Custom Property for a design token, wrap it in var(--{name-of-token}). To learn how to use a specific token, use a corresponding usage tool for the category of the token. For example, if a token is a color token look for the get_color_usage tool. \n\n'
 
-  for (const token of tokens) {
-    text += serialize(token)
-    text += '\n'
-  }
+  text += serialize(tokens)
 
   return {
     content: [
@@ -872,4 +504,186 @@ server.tool('get_typography_usage', 'Get the guidelines for how to apply typogra
   }
 })
 
+// -----------------------------------------------------------------------------
+// Icons
+// -----------------------------------------------------------------------------
+server.tool('list_icons', '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.tool(
+  'get_icon',
+  'Get a specific icon (octicon) by name from Primer',
+  {
+    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.tool(
+  'primer_coding_guidelines',
+  '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 \`list_tokens\` tool to find the design token you need.
+- 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.tool(
+  'review_alt_text',
+  'Evaluates image alt text against accessibility best practices and context relevance.',
+  {
+    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
+      .union([
+        z.instanceof(File).describe('The image src file being evaluated'),
+        z.string().url().describe('The URL of the image src being evaluated'),
+        z.string().describe('The file path of the image src being evaluated'),
+      ])
+      .describe('The image file, file path, or URL 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}