Design System MCP Server

Instructions

Implementation Reference

• src/index.ts:274-373 (handler)

  The handler function for 'get-component-details' retrieves component data based on category and name, fetches content via the sourceManager, performs source filtering/internal access checks, and formats the response with attribution.

  async ({ category, componentName, includeInternal = false, sourceOnly, includeSailGuidance }) => {
    const normalizedCategory = category.toLowerCase();
    const normalizedComponentName = componentName.toLowerCase();
    
    if (!(normalizedCategory in designSystemData)) {
      return {
        content: [
          {
            type: "text",
            text: `Category not found. Available categories: ${Object.keys(designSystemData).join(", ")}`,
          },
        ],
      };
    }
    
    const categoryData = designSystemData[normalizedCategory];
    
    if (!(normalizedComponentName in categoryData)) {
      return {
        content: [
          {
            type: "text",
            text: `Component not found in ${normalizedCategory}. Available components: ${Object.keys(categoryData).join(", ")}`,
          },
        ],
      };
    }
    
    const component = categoryData[normalizedComponentName] as DesignSystemItem;
    
    // Use new source manager to get content
    const sourcedContent = await sourceManager.getContent(component.filePath);
    
    if (!sourcedContent) {
      console.error(`[ERROR] Unable to fetch content for ${component.title} at ${component.filePath}`);
      return {
        content: [
          {
            type: "text",
            text: `Failed to fetch details for ${component.title}.\n\nBasic information:\n${component.body}\n\nFile path: ${component.filePath}\n\nNote: This may be due to GitHub API limits, network issues, or authentication problems. Check server logs for details.`,
          },
        ],
      };
    }
  
    // Apply source filtering
    if (sourceOnly && sourceOnly !== 'all' && sourcedContent.source !== sourceOnly) {
      return {
        content: [
          {
            type: "text",
            text: `Component ${component.title} not available from ${sourceOnly} source. Available from: ${sourcedContent.source}`,
          },
        ],
      };
    }
  
    // Check internal access
    if (sourcedContent.source === 'internal' && !includeInternal) {
      return {
        content: [
          {
            type: "text",
            text: `Component ${component.title} is only available in internal documentation. Set includeInternal=true to access.`,
          },
        ],
      };
    }
    
    let response = `# ${component.title}\n\n${component.body}\n\n`;
    
    // Add source attribution
    response += `**Source:** ${sourcedContent.source.toUpperCase()}`;
    if (sourcedContent.overrides) {
      response += ` (overrides ${sourcedContent.overrides})`;
    }
    response += '\n';
    
    // Add frontmatter info if available
    if (Object.keys(sourcedContent.frontmatter).length > 0) {
      response += `**Status:** ${sourcedContent.frontmatter.status || 'Unknown'}\n`;
      if (sourcedContent.last_updated) {
        response += `**Last Updated:** ${sourcedContent.last_updated}\n`;
      }
      response += '\n';
    }
    
    // Parse content sections (reuse existing logic)
    const parsedContent = parseFrontmatter(sourcedContent.content);
    
    // Add Design section
    if (parsedContent.designSection) {
      response += `## Design\n\n${parsedContent.designSection}\n\n`;
    }
    
    // Add Development section
    if (parsedContent.developmentSection) {
      response += `## Development\n\n${parsedContent.developmentSection}`;
    }

• src/index.ts:264-273 (registration)

  Registration of the 'get-component-details' tool, including parameter schema validation using zod.

  server.tool(
    "get-component-details",
    "Get detailed information about a specific component with source attribution",
    {
      category: z.string().describe("Design system category (components, layouts, patterns)"),
      componentName: z.string().describe("Name of the component, layout, or pattern"),
      includeInternal: z.boolean().optional().describe("Include internal documentation if available (default: false)"),
      sourceOnly: z.enum(["public", "internal", "all"]).optional().describe("Filter by specific source"),
      includeSailGuidance: z.boolean().optional().describe("Include SAIL coding guidance (default: true for components/patterns/layouts)"),
    },