@primer/mcp 0.3.3 → 0.4.0-rc.4d4be073a

package/dist/index.js

@@ -1,4 +1,4 @@
-export { s as server } from './server-C2QaEv-c.js';
+export { s as server } from './server-CkSoZOVD.js';
 import '@modelcontextprotocol/sdk/server/mcp.js';
 import 'cheerio';
 import 'zod';

package/dist/{server-C2QaEv-c.js → server-CkSoZOVD.js}

@@ -40,36 +40,63 @@ const components = Object.entries(componentsMetadata.components).map(([id, compo
 function listComponents() {
   return components;
 }
+// Scenario patterns are listed first so name resolution favours them over UI patterns.
 const patterns = [{
+  id: 'copy',
+  name: 'Copy',
+  category: 'scenario'
+}, {
+  id: 'delete',
+  name: 'Delete',
+  category: 'scenario'
+}, {
+  id: 'filter',
+  name: 'Filter',
+  category: 'scenario'
+}, {
+  id: 'search',
+  name: 'Search',
+  category: 'scenario'
+}, {
   id: 'data-visualization',
-  name: 'Data Visualization'
+  name: 'Data Visualization',
+  category: 'ui'
 }, {
   id: 'degraded-experiences',
-  name: 'Degraded Experiences'
+  name: 'Degraded Experiences',
+  category: 'ui'
 }, {
   id: 'empty-states',
-  name: 'Empty States'
+  name: 'Empty States',
+  category: 'ui'
 }, {
   id: 'feature-onboarding',
-  name: 'Feature Onboarding'
+  name: 'Feature Onboarding',
+  category: 'ui'
 }, {
   id: 'forms',
-  name: 'Forms'
+  name: 'Forms',
+  category: 'ui'
 }, {
   id: 'loading',
-  name: 'Loading'
+  name: 'Loading',
+  category: 'ui'
 }, {
   id: 'navigation',
-  name: 'Navigation'
+  name: 'Navigation',
+  category: 'ui'
 }, {
   id: 'notification-messaging',
-  name: 'Notification message'
+  name: 'Notification message',
+  category: 'ui'
 }, {
   id: 'progressive-disclosure',
-  name: 'Progressive disclosure'
+  name: 'Progressive disclosure',
+  category: 'ui'
 }, {
   id: 'saving',
-  name: 'Saving'
+  name: 'Saving',
+  category: 'ui'
 }];
 function listPatterns() {
   return patterns;
@@ -736,7 +763,7 @@ function runStylelint(css) {
   });
 }
 
-var version = "0.3.3";
+var version = "0.4.0";
 var packageJson = {
 	version: version};
 
@@ -753,7 +780,10 @@ const allTokensWithGuidelines = loadAllTokensWithGuidelines();
 // Project setup
 // -----------------------------------------------------------------------------
 server.registerTool('init', {
-  description: 'Setup or create a project that includes Primer React'
+  description: 'Setup or create a project that includes Primer React',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   const url = new URL(`/product/getting-started/react`, 'https://primer.style');
   const response = await fetch(url);
@@ -798,7 +828,10 @@ ${text}
 // Components
 // -----------------------------------------------------------------------------
 server.registerTool('list_components', {
-  description: 'List all of the components available from Primer React'
+  description: 'List all of the components available from Primer React',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   const components = listComponents().map(component => {
     return `- ${component.name}`;
@@ -818,6 +851,9 @@ server.registerTool('get_component', {
   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')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   name
@@ -858,6 +894,9 @@ server.registerTool('get_component_examples', {
   description: 'Get examples for how to use a component from Primer React',
   inputSchema: {
     name: z.string().describe('The name of the component to retrieve')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   name
@@ -906,6 +945,9 @@ server.registerTool('get_component_usage_guidelines', {
   description: 'Get usage information for how to use a component from Primer',
   inputSchema: {
     name: z.string().describe('The name of the component to retrieve')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   name
@@ -962,6 +1004,9 @@ server.registerTool('get_component_accessibility_guidelines', {
   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')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   name
@@ -1019,32 +1064,43 @@ ${text}`
 // Patterns
 // -----------------------------------------------------------------------------
 server.registerTool('list_patterns', {
-  description: 'List all of the patterns available from Primer React'
+  description: 'List all of the patterns available from Primer React. Scenario patterns describe specific user tasks (copy, delete, filter, search). Prefer a scenario pattern when one fits the task, and fall back to the more generic UI patterns otherwise.',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
-  const patterns = listPatterns().map(pattern => {
-    return `- ${pattern.name}`;
-  });
+  const all = listPatterns();
+  const scenario = all.filter(pattern => pattern.category === 'scenario').map(pattern => `- ${pattern.name}`);
+  const ui = all.filter(pattern => pattern.category === 'ui').map(pattern => `- ${pattern.name}`);
   return {
     content: [{
       type: 'text',
-      text: `The following patterns are available in the @primer/react in TypeScript projects:
+      text: `The following patterns are available from \`@primer/react\` for use in TypeScript projects. Scenario patterns describe specific user tasks. Prefer a scenario pattern when one fits the task, and fall back to the UI patterns otherwise.
+
+## Scenario patterns
+
+${scenario.join('\n')}
 
-${patterns.join('\n')}`
+## UI patterns
+
+${ui.join('\n')}`
     }]
   };
 });
 server.registerTool('get_pattern', {
-  description: 'Get a specific pattern by name',
+  description: 'Get a specific pattern by name. Scenario patterns describe specific user tasks (copy, delete, filter, search). Prefer a scenario pattern when one fits the task, and fall back to the more generic UI patterns otherwise.',
   inputSchema: {
     name: z.string().describe('The name of the pattern to retrieve')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   name
 }) => {
   const patterns = listPatterns();
-  const match = patterns.find(pattern => {
-    return pattern.name === name;
-  });
+  // Resolve scenario patterns first so a name clash favours the scenario pattern.
+  const match = patterns.find(pattern => pattern.category === 'scenario' && pattern.name === name) ?? patterns.find(pattern => pattern.name === name);
   if (!match) {
     return {
       content: [{
@@ -1053,7 +1109,8 @@ server.registerTool('get_pattern', {
       }]
     };
   }
-  const url = new URL(`/product/ui-patterns/${match.id}`, 'https://primer.style');
+  const basePath = match.category === 'scenario' ? 'scenario-patterns' : 'ui-patterns';
+  const url = new URL(`/product/${basePath}/${match.id}`, 'https://primer.style');
   const response = await fetch(url);
   if (!response.ok) {
     throw new Error(`Failed to fetch ${url} - ${response.statusText}`);
@@ -1091,6 +1148,9 @@ server.registerTool('find_tokens', {
     query: z.string().optional().default('').describe('Search keywords (e.g., "danger border", "success background")'),
     group: z.string().optional().describe('Filter by group (e.g., "fgColor", "border")'),
     limit: z.number().int().min(1).max(100).optional().default(15).describe('Maximum results to return to stay within context limits')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   query,
@@ -1172,6 +1232,9 @@ server.registerTool('get_token_group_bundle', {
   description: "PREFERRED FOR COMPONENTS. Fetch all tokens for complex UI (e.g., Dialogs, Cards) in one call by providing an array of groups like ['overlay', 'shadow']. Use this instead of multiple find_tokens calls to save context.",
   inputSchema: {
     groups: z.array(z.string()).describe('Array of group names (e.g., ["overlay", "shadow", "focus"])')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   groups
@@ -1206,7 +1269,10 @@ server.registerTool('get_token_group_bundle', {
   };
 });
 server.registerTool('get_design_token_specs', {
-  description: 'CRITICAL: CALL THIS FIRST. Provides the logic matrix and the list of valid group names. You cannot search accurately without this map.'
+  description: 'CRITICAL: CALL THIS FIRST. Provides the logic matrix and the list of valid group names. You cannot search accurately without this map.',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   const groups = listTokenGroups();
   const customRules = getDesignTokenSpecsText(groups);
@@ -1225,7 +1291,10 @@ server.registerTool('get_design_token_specs', {
   };
 });
 server.registerTool('get_token_usage_patterns', {
-  description: 'Provides "Golden Example" CSS for core patterns: Button (Interactions) and Stack (Layout). Use this to understand how to apply the Logic Matrix, Motion, and Spacing scales.'
+  description: 'Provides "Golden Example" CSS for core patterns: Button (Interactions) and Stack (Layout). Use this to understand how to apply the Logic Matrix, Motion, and Spacing scales.',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   const customPatterns = getTokenUsagePatternsText();
   let text;
@@ -1251,6 +1320,9 @@ server.registerTool('lint_css', {
   description: 'REQUIRED FINAL STEP. Use this to validate your CSS. You cannot complete a task involving CSS without a successful run of this tool.',
   inputSchema: {
     css: z.string()
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   css
@@ -1282,7 +1354,10 @@ server.registerTool('lint_css', {
 // Foundations
 // -----------------------------------------------------------------------------
 server.registerTool('get_color_usage', {
-  description: 'Get the guidelines for how to apply color to a user interface'
+  description: 'Get the guidelines for how to apply color to a user interface',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   const url = new URL(`/product/getting-started/foundations/color-usage`, 'https://primer.style');
   const response = await fetch(url);
@@ -1311,7 +1386,10 @@ server.registerTool('get_color_usage', {
   };
 });
 server.registerTool('get_typography_usage', {
-  description: 'Get the guidelines for how to apply typography to a user interface'
+  description: 'Get the guidelines for how to apply typography to a user interface',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   const url = new URL(`/product/getting-started/foundations/typography`, 'https://primer.style');
   const response = await fetch(url);
@@ -1344,7 +1422,10 @@ server.registerTool('get_typography_usage', {
 // Icons
 // -----------------------------------------------------------------------------
 server.registerTool('list_icons', {
-  description: 'List all of the icons (octicons) available from Primer Octicons React'
+  description: 'List all of the icons (octicons) available from Primer Octicons React',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   const icons = listIcons().map(icon => {
     const keywords = icon.keywords.map(keyword => {
@@ -1371,6 +1452,9 @@ server.registerTool('get_icon', {
   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')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   name,
@@ -1420,7 +1504,10 @@ ${text}`
 // Coding guidelines
 // -----------------------------------------------------------------------------
 server.registerTool('primer_coding_guidelines', {
-  description: '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',
+  annotations: {
+    readOnlyHint: true
+  }
 }, async () => {
   return {
     content: [{
@@ -1471,6 +1558,9 @@ server.registerTool('review_alt_text', {
     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')
+  },
+  annotations: {
+    readOnlyHint: true
   }
 }, async ({
   surroundingText,

package/dist/stdio.js

@@ -1,5 +1,5 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { s as server } from './server-C2QaEv-c.js';
+import { s as server } from './server-CkSoZOVD.js';
 import '@modelcontextprotocol/sdk/server/mcp.js';
 import 'cheerio';
 import 'zod';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@primer/mcp",
   "description": "An MCP server that connects AI tools to the Primer Design System",
-  "version": "0.3.3",
+  "version": "0.4.0-rc.4d4be073a",
   "type": "module",
   "bin": {
     "mcp": "./bin/mcp.js"
@@ -37,7 +37,7 @@
     "@modelcontextprotocol/sdk": "^1.24.0",
     "@primer/octicons": "^19.15.5",
     "@primer/primitives": "10.x || 11.x",
-    "@primer/react": "^38.20.0",
+    "@primer/react": "^38.30.0",
     "cheerio": "^1.0.0",
     "turndown": "^7.2.0",
     "zod": "^4.3.5"

package/src/primer.ts

@@ -40,48 +40,81 @@ function listComponents(): Array<Component> {
 type Pattern = {
   id: string
   name: string
+  // 'scenario' maps to the /product/scenario-patterns/ base path, 'ui' to /product/ui-patterns/
+  category: 'scenario' | 'ui'
 }
 
+// Scenario patterns are listed first so name resolution favours them over UI patterns.
 const patterns: Array<Pattern> = [
+  {
+    id: 'copy',
+    name: 'Copy',
+    category: 'scenario',
+  },
+  {
+    id: 'delete',
+    name: 'Delete',
+    category: 'scenario',
+  },
+  {
+    id: 'filter',
+    name: 'Filter',
+    category: 'scenario',
+  },
+  {
+    id: 'search',
+    name: 'Search',
+    category: 'scenario',
+  },
   {
     id: 'data-visualization',
     name: 'Data Visualization',
+    category: 'ui',
   },
   {
     id: 'degraded-experiences',
     name: 'Degraded Experiences',
+    category: 'ui',
   },
   {
     id: 'empty-states',
     name: 'Empty States',
+    category: 'ui',
   },
   {
     id: 'feature-onboarding',
     name: 'Feature Onboarding',
+    category: 'ui',
   },
   {
     id: 'forms',
     name: 'Forms',
+    category: 'ui',
   },
   {
     id: 'loading',
     name: 'Loading',
+    category: 'ui',
   },
   {
     id: 'navigation',
     name: 'Navigation',
+    category: 'ui',
   },
   {
     id: 'notification-messaging',
     name: 'Notification message',
+    category: 'ui',
   },
   {
     id: 'progressive-disclosure',
     name: 'Progressive disclosure',
+    category: 'ui',
   },
   {
     id: 'saving',
     name: 'Saving',
+    category: 'ui',
   },
 ]
 

package/src/server.ts

@@ -39,6 +39,7 @@ server.registerTool(
   'init',
   {
     description: 'Setup or create a project that includes Primer React',
+    annotations: {readOnlyHint: true},
   },
   async () => {
     const url = new URL(`/product/getting-started/react`, 'https://primer.style')
@@ -92,7 +93,7 @@ ${text}
 // -----------------------------------------------------------------------------
 server.registerTool(
   'list_components',
-  {description: 'List all of the components available from Primer React'},
+  {description: 'List all of the components available from Primer React', annotations: {readOnlyHint: true}},
   async () => {
     const components = listComponents().map(component => {
       return `- ${component.name}`
@@ -120,6 +121,7 @@ server.registerTool(
     inputSchema: {
       name: z.string().describe('The name of the component to retrieve'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({name}) => {
     const components = listComponents()
@@ -166,6 +168,7 @@ server.registerTool(
     inputSchema: {
       name: z.string().describe('The name of the component to retrieve'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({name}) => {
     const components = listComponents()
@@ -226,6 +229,7 @@ server.registerTool(
     inputSchema: {
       name: z.string().describe('The name of the component to retrieve'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({name}) => {
     const components = listComponents()
@@ -298,6 +302,7 @@ server.registerTool(
     inputSchema: {
       name: z.string().describe('The name of the component to retrieve'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({name}) => {
     const components = listComponents()
@@ -367,18 +372,28 @@ ${text}`,
 // -----------------------------------------------------------------------------
 server.registerTool(
   'list_patterns',
-  {description: 'List all of the patterns available from Primer React'},
+  {
+    description:
+      'List all of the patterns available from Primer React. Scenario patterns describe specific user tasks (copy, delete, filter, search). Prefer a scenario pattern when one fits the task, and fall back to the more generic UI patterns otherwise.',
+    annotations: {readOnlyHint: true},
+  },
   async () => {
-    const patterns = listPatterns().map(pattern => {
-      return `- ${pattern.name}`
-    })
+    const all = listPatterns()
+    const scenario = all.filter(pattern => pattern.category === 'scenario').map(pattern => `- ${pattern.name}`)
+    const ui = all.filter(pattern => pattern.category === 'ui').map(pattern => `- ${pattern.name}`)
     return {
       content: [
         {
           type: 'text',
-          text: `The following patterns are available in the @primer/react in TypeScript projects:
+          text: `The following patterns are available from \`@primer/react\` for use in TypeScript projects. Scenario patterns describe specific user tasks. Prefer a scenario pattern when one fits the task, and fall back to the UI patterns otherwise.
 
-${patterns.join('\n')}`,
+## Scenario patterns
+
+${scenario.join('\n')}
+
+## UI patterns
+
+${ui.join('\n')}`,
         },
       ],
     }
@@ -388,16 +403,19 @@ ${patterns.join('\n')}`,
 server.registerTool(
   'get_pattern',
   {
-    description: 'Get a specific pattern by name',
+    description:
+      'Get a specific pattern by name. Scenario patterns describe specific user tasks (copy, delete, filter, search). Prefer a scenario pattern when one fits the task, and fall back to the more generic UI patterns otherwise.',
     inputSchema: {
       name: z.string().describe('The name of the pattern to retrieve'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({name}) => {
     const patterns = listPatterns()
-    const match = patterns.find(pattern => {
-      return pattern.name === name
-    })
+    // Resolve scenario patterns first so a name clash favours the scenario pattern.
+    const match =
+      patterns.find(pattern => pattern.category === 'scenario' && pattern.name === name) ??
+      patterns.find(pattern => pattern.name === name)
     if (!match) {
       return {
         content: [
@@ -409,7 +427,8 @@ server.registerTool(
       }
     }
 
-    const url = new URL(`/product/ui-patterns/${match.id}`, 'https://primer.style')
+    const basePath = match.category === 'scenario' ? 'scenario-patterns' : 'ui-patterns'
+    const url = new URL(`/product/${basePath}/${match.id}`, 'https://primer.style')
     const response = await fetch(url)
     if (!response.ok) {
       throw new Error(`Failed to fetch ${url} - ${response.statusText}`)
@@ -469,6 +488,7 @@ server.registerTool(
         .default(15)
         .describe('Maximum results to return to stay within context limits'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({query, group, limit}) => {
     // Resolve group via aliases
@@ -566,6 +586,7 @@ server.registerTool(
     inputSchema: {
       groups: z.array(z.string()).describe('Array of group names (e.g., ["overlay", "shadow", "focus"])'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({groups}) => {
     // Normalize and resolve aliases
@@ -608,6 +629,7 @@ server.registerTool(
   {
     description:
       'CRITICAL: CALL THIS FIRST. Provides the logic matrix and the list of valid group names. You cannot search accurately without this map.',
+    annotations: {readOnlyHint: true},
   },
   async () => {
     const groups = listTokenGroups()
@@ -631,6 +653,7 @@ server.registerTool(
   {
     description:
       'Provides "Golden Example" CSS for core patterns: Button (Interactions) and Stack (Layout). Use this to understand how to apply the Logic Matrix, Motion, and Spacing scales.',
+    annotations: {readOnlyHint: true},
   },
   async () => {
     const customPatterns = getTokenUsagePatternsText()
@@ -659,6 +682,7 @@ server.registerTool(
     description:
       'REQUIRED FINAL STEP. Use this to validate your CSS. You cannot complete a task involving CSS without a successful run of this tool.',
     inputSchema: {css: z.string()},
+    annotations: {readOnlyHint: true},
   },
   async ({css}) => {
     try {
@@ -694,7 +718,7 @@ server.registerTool(
 // -----------------------------------------------------------------------------
 server.registerTool(
   'get_color_usage',
-  {description: 'Get the guidelines for how to apply color to a user interface'},
+  {description: 'Get the guidelines for how to apply color to a user interface', annotations: {readOnlyHint: true}},
   async () => {
     const url = new URL(`/product/getting-started/foundations/color-usage`, 'https://primer.style')
     const response = await fetch(url)
@@ -732,7 +756,10 @@ server.registerTool(
 
 server.registerTool(
   'get_typography_usage',
-  {description: 'Get the guidelines for how to apply typography to a user interface'},
+  {
+    description: 'Get the guidelines for how to apply typography to a user interface',
+    annotations: {readOnlyHint: true},
+  },
   async () => {
     const url = new URL(`/product/getting-started/foundations/typography`, 'https://primer.style')
     const response = await fetch(url)
@@ -773,7 +800,10 @@ server.registerTool(
 // -----------------------------------------------------------------------------
 server.registerTool(
   'list_icons',
-  {description: 'List all of the icons (octicons) available from Primer Octicons React'},
+  {
+    description: 'List all of the icons (octicons) available from Primer Octicons React',
+    annotations: {readOnlyHint: true},
+  },
   async () => {
     const icons = listIcons().map(icon => {
       const keywords = icon.keywords.map(keyword => {
@@ -808,6 +838,7 @@ server.registerTool(
       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'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({name, size}) => {
     const icons = listIcons()
@@ -865,7 +896,10 @@ ${text}`,
 // -----------------------------------------------------------------------------
 server.registerTool(
   'primer_coding_guidelines',
-  {description: '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',
+    annotations: {readOnlyHint: true},
+  },
   async () => {
     return {
       content: [
@@ -922,6 +956,7 @@ server.registerTool(
       alt: z.string().describe('The alt text of the image being evaluated'),
       image: z.string().describe('The image URL or file path being evaluated'),
     },
+    annotations: {readOnlyHint: true},
   },
   async ({surroundingText, alt, image}) => {
     // Call the LLM through MCP sampling