@primer/mcp 0.0.3 → 0.0.4

package/src/server.ts

@@ -4,6 +4,7 @@ import * as cheerio from 'cheerio'
 import {z} from 'zod'
 import TurndownService from 'turndown'
 import {listComponents, listPatterns, listIcons} from './primer'
+import {tokens, serialize} from './primitives'
 import packageJson from '../package.json' with {type: 'json'}
 
 const server = new McpServer({
@@ -413,430 +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') {
-    return `<token name="${token}"></token>`
-  }
-  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: [
@@ -1005,4 +590,100 @@ ${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}