@primer/mcp 0.0.4 → 0.2.0

package/src/server.ts

@@ -1,7 +1,8 @@
 import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js'
 // eslint-disable-next-line import/no-namespace
 import * as cheerio from 'cheerio'
-import {z} from 'zod'
+// eslint-disable-next-line import/no-namespace
+import * as z from 'zod'
 import TurndownService from 'turndown'
 import {listComponents, listPatterns, listIcons} from './primer'
 import {tokens, serialize} from './primitives'
@@ -17,35 +18,40 @@ 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}`)
-  }
+server.registerTool(
+  'init',
+  {
+    description: '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 html = await response.text()
+    if (!html) {
+      return {
+        content: [],
+      }
     }
-  }
 
-  const $ = cheerio.load(html)
-  const source = $('main').html()
-  if (!source) {
-    return {
-      content: [],
+    const $ = cheerio.load(html)
+    const source = $('main').html()
+    if (!source) {
+      return {
+        content: [],
+      }
     }
-  }
 
-  const text = turndownService.turndown(source)
+    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:
+    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\`
@@ -58,37 +64,45 @@ server.tool('init', 'Setup or create a project that includes Primer React', asyn
 
 ${text}
 `,
-      },
-    ],
-  }
-})
+        },
+      ],
+    }
+  },
+)
 
 // -----------------------------------------------------------------------------
 // Components
 // -----------------------------------------------------------------------------
-server.tool('list_components', 'List all of the components available from Primer React', async () => {
-  const components = listComponents().map(component => {
-    return `- ${component.name}`
-  })
-  return {
-    content: [
-      {
-        type: 'text',
-        text: `The following components are available in the @primer/react in TypeScript projects:
+server.registerTool(
+  'list_components',
+  {description: 'List all of the components available from Primer React'},
+  async () => {
+    const components = listComponents().map(component => {
+      return `- ${component.name}`
+    })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `The following components are available in the @primer/react in TypeScript projects:
 
 ${components.join('\n')}
 
 You can use the \`get_component\` tool to get more information about a specific component. You can use these components from the @primer/react package.`,
-      },
-    ],
-  }
-})
+        },
+      ],
+    }
+  },
+)
 
-server.tool(
+server.registerTool(
   'get_component',
-  'Get a specific component by name',
   {
-    name: z.string().describe('The name of the component to retrieve'),
+    description:
+      'Retrieve documentation and usage details for a specific React component from the @primer/react package by its name. This tool provides the official Primer documentation for any listed component, making it easy to inspect, reuse, or integrate components in your project.',
+    inputSchema: {
+      name: z.string().describe('The name of the component to retrieve'),
+    },
   },
   async ({name}) => {
     const components = listComponents()
@@ -97,12 +111,27 @@ server.tool(
     })
     if (!match) {
       return {
-        content: [
-          {
-            type: 'text',
-            text: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`get_components\` tool.`,
-          },
-        ],
+        isError: true,
+        errorMessage: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`list_components\` tool.`,
+        content: [],
+      }
+    }
+
+    const llmsUrl = new URL(`/product/components/${match.slug}/llms.txt`, 'https://primer.style')
+    const llmsResponse = await fetch(llmsUrl)
+    if (llmsResponse.ok) {
+      try {
+        const llmsText = await llmsResponse.text()
+        return {
+          content: [
+            {
+              type: 'text',
+              text: llmsText,
+            },
+          ],
+        }
+      } catch (_: unknown) {
+        // If there's an error fetching or processing the llms.txt, we fall back to the regular documentation
       }
     }
 
@@ -141,11 +170,13 @@ ${text}`,
   },
 )
 
-server.tool(
+server.registerTool(
   'get_component_examples',
-  'Get examples for how to use a component from Primer React',
   {
-    name: z.string().describe('The name of the component to retrieve'),
+    description: 'Get examples for how to use a component from Primer React',
+    inputSchema: {
+      name: z.string().describe('The name of the component to retrieve'),
+    },
   },
   async ({name}) => {
     const components = listComponents()
@@ -199,11 +230,13 @@ ${text}`,
   },
 )
 
-server.tool(
+server.registerTool(
   'get_component_usage_guidelines',
-  'Get usage information for how to use a component from Primer',
   {
-    name: z.string().describe('The name of the component to retrieve'),
+    description: 'Get usage information for how to use a component from Primer',
+    inputSchema: {
+      name: z.string().describe('The name of the component to retrieve'),
+    },
   },
   async ({name}) => {
     const components = listComponents()
@@ -268,11 +301,14 @@ ${text}`,
   },
 )
 
-server.tool(
+server.registerTool(
   'get_component_accessibility_guidelines',
-  'Get accessibility information for how to use a component from Primer React',
   {
-    name: z.string().describe('The name of the component to retrieve'),
+    description:
+      'Retrieve accessibility guidelines and best practices for a specific component from the @primer/react package by its name. Use this tool to get official accessibility recommendations, usage tips, and requirements to ensure your UI components are inclusive and meet accessibility standards.',
+    inputSchema: {
+      name: z.string().describe('The name of the component to retrieve'),
+    },
   },
   async ({name}) => {
     const components = listComponents()
@@ -284,7 +320,7 @@ server.tool(
         content: [
           {
             type: 'text',
-            text: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`get_components\` tool.`,
+            text: `There is no component named \`${name}\` in the @primer/react package. For a full list of components, use the \`list_components\` tool.`,
           },
         ],
       }
@@ -340,27 +376,33 @@ ${text}`,
 // -----------------------------------------------------------------------------
 // Patterns
 // -----------------------------------------------------------------------------
-server.tool('list_patterns', 'List all of the patterns available from Primer React', async () => {
-  const patterns = listPatterns().map(pattern => {
-    return `- ${pattern.name}`
-  })
-  return {
-    content: [
-      {
-        type: 'text',
-        text: `The following patterns are available in the @primer/react in TypeScript projects:
+server.registerTool(
+  'list_patterns',
+  {description: 'List all of the patterns available from Primer React'},
+  async () => {
+    const patterns = listPatterns().map(pattern => {
+      return `- ${pattern.name}`
+    })
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `The following patterns are available in the @primer/react in TypeScript projects:
 
 ${patterns.join('\n')}`,
-      },
-    ],
-  }
-})
+        },
+      ],
+    }
+  },
+)
 
-server.tool(
+server.registerTool(
   'get_pattern',
-  'Get a specific pattern by name',
   {
-    name: z.string().describe('The name of the pattern to retrieve'),
+    description: 'Get a specific pattern by name',
+    inputSchema: {
+      name: z.string().describe('The name of the pattern to retrieve'),
+    },
   },
   async ({name}) => {
     const patterns = listPatterns()
@@ -417,7 +459,7 @@ ${text}`,
 // -----------------------------------------------------------------------------
 // Design Tokens
 // -----------------------------------------------------------------------------
-server.tool('list_tokens', 'List all of the design tokens available from Primer', async () => {
+server.registerTool('list_tokens', {description: 'List all of the design tokens available from Primer'}, async () => {
   let text =
     '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'
 
@@ -436,108 +478,122 @@ server.tool('list_tokens', 'List all of the design tokens available from Primer'
 // -----------------------------------------------------------------------------
 // Foundations
 // -----------------------------------------------------------------------------
-server.tool('get_color_usage', 'Get the guidelines for how to apply color to a user interface', async () => {
-  const url = new URL(`/product/getting-started/foundations/color-usage`, 'https://primer.style')
-  const response = await fetch(url)
-  if (!response.ok) {
-    throw new Error(`Failed to fetch ${url} - ${response.statusText}`)
-  }
+server.registerTool(
+  'get_color_usage',
+  {description: 'Get the guidelines for how to apply color to a user interface'},
+  async () => {
+    const url = new URL(`/product/getting-started/foundations/color-usage`, '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 html = await response.text()
+    if (!html) {
+      return {
+        content: [],
+      }
     }
-  }
 
-  const $ = cheerio.load(html)
-  const source = $('main').html()
-  if (!source) {
-    return {
-      content: [],
+    const $ = cheerio.load(html)
+    const source = $('main').html()
+    if (!source) {
+      return {
+        content: [],
+      }
     }
-  }
 
-  const text = turndownService.turndown(source)
+    const text = turndownService.turndown(source)
 
-  return {
-    content: [
-      {
-        type: 'text',
-        text: `Here is the documentation for color usage in Primer:\n\n${text}`,
-      },
-    ],
-  }
-})
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Here is the documentation for color usage in Primer:\n\n${text}`,
+        },
+      ],
+    }
+  },
+)
 
-server.tool('get_typography_usage', 'Get the guidelines for how to apply typography to a user interface', async () => {
-  const url = new URL(`/product/getting-started/foundations/typography`, 'https://primer.style')
-  const response = await fetch(url)
-  if (!response.ok) {
-    throw new Error(`Failed to fetch ${url} - ${response.statusText}`)
-  }
+server.registerTool(
+  'get_typography_usage',
+  {description: 'Get the guidelines for how to apply typography to a user interface'},
+  async () => {
+    const url = new URL(`/product/getting-started/foundations/typography`, '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 html = await response.text()
+    if (!html) {
+      return {
+        content: [],
+      }
     }
-  }
 
-  const $ = cheerio.load(html)
-  const source = $('main').html()
-  if (!source) {
-    return {
-      content: [],
+    const $ = cheerio.load(html)
+    const source = $('main').html()
+    if (!source) {
+      return {
+        content: [],
+      }
     }
-  }
 
-  const text = turndownService.turndown(source)
+    const text = turndownService.turndown(source)
 
-  return {
-    content: [
-      {
-        type: 'text',
-        text: `Here is the documentation for typography usage in Primer:\n\n${text}`,
-      },
-    ],
-  }
-})
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Here is the documentation for typography usage in Primer:\n\n${text}`,
+        },
+      ],
+    }
+  },
+)
 
 // -----------------------------------------------------------------------------
 // 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>`
+server.registerTool(
+  'list_icons',
+  {description: '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 [`<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:
+    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(
+server.registerTool(
   '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'),
+    description: 'Get a specific icon (octicon) by name from Primer',
+    inputSchema: {
+      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()
@@ -593,9 +649,9 @@ ${text}`,
 // -----------------------------------------------------------------------------
 // Coding guidelines
 // -----------------------------------------------------------------------------
-server.tool(
+server.registerTool(
   'primer_coding_guidelines',
-  'Get the guidelines when writing code that uses Primer or for UI code that you are creating',
+  {description: 'Get the guidelines when writing code that uses Primer or for UI code that you are creating'},
   async () => {
     return {
       content: [
@@ -643,19 +699,15 @@ The following list of coding guidelines must be followed:
  *
  *
  **/
-server.tool(
+server.registerTool(
   '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'),
+    description: 'Evaluates image alt text against accessibility best practices and context relevance.',
+    inputSchema: {
+      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.string().describe('The image URL or file path being evaluated'),
+    },
   },
   async ({surroundingText, alt, image}) => {
     // Call the LLM through MCP sampling