Design System MCP Server

Instructions

Implementation Reference

• src/index.ts:193-260 (handler)

  The handler implementation for the list-components tool. It validates the category, filters components based on source permissions, and formats the output.

  async ({ category, includeInternal, sourceOnly }) => {
    // Default to including internal if internal source is enabled
    const defaultIncludeInternal = sourceManager.getSourceStatus().some(s => s.name === 'internal' && s.enabled);
    const shouldIncludeInternal = includeInternal !== undefined ? includeInternal : defaultIncludeInternal;
    const normalizedCategory = category.toLowerCase();
    
    if (!(normalizedCategory in designSystemData)) {
      return {
        content: [
          {
            type: "text",
            text: `Category not found. Available categories: ${Object.keys(designSystemData).join(", ")}`,
          },
        ],
      };
    }
    
    const items = [];
    const categoryData = designSystemData[normalizedCategory];
    
    for (const [key, component] of Object.entries(categoryData)) {
      const item = component as DesignSystemItem;
      
      // Check if content exists and get source information
      const sourcedContent = await sourceManager.getContent(item.filePath);
      
      if (!sourcedContent) {
        continue; // Skip if content not available
      }
      
      // Apply access control
      if (sourcedContent.source === 'internal' && !shouldIncludeInternal) {
        continue; // Skip internal content when not requested
      }
      
      // Apply source filtering
      if (sourceOnly && sourceOnly !== 'all' && sourcedContent.source !== sourceOnly) {
        continue; // Skip if doesn't match source filter
      }
      
      // Add source attribution to the listing
      const sourceLabel = sourcedContent.source.toUpperCase();
      const overrideInfo = sourcedContent.overrides ? ` (overrides ${sourcedContent.overrides.toUpperCase()})` : '';
      
      items.push(`**${key}**: ${item.title} - ${item.body}\n  *Source: ${sourceLabel}${overrideInfo}*`);
    }
    
    if (items.length === 0) {
      const accessNote = !shouldIncludeInternal ? " (use includeInternal=true to see internal components)" : "";
      return {
        content: [
          {
            type: "text",
            text: `No accessible components found in ${normalizedCategory}${accessNote}`,
          },
        ],
      };
    }
    
    return {
      content: [
        {
          type: "text",
          text: `Components in ${normalizedCategory}:\n\n${items.join("\n\n")}`,
        },
      ],
    };
  },

• src/index.ts:188-192 (schema)

  Input schema validation for the list-components tool.

  {
    category: z.string().describe("Design system category (components, layouts, patterns)"),
    includeInternal: z.boolean().optional().describe("Include internal documentation components (default: false)"),
    sourceOnly: z.enum(["public", "internal", "all"]).optional().describe("Filter by specific source"),
  },

• src/index.ts:185-187 (registration)

  Registration of the list-components tool.

  server.tool(
    "list-components",
    "List components in a specific category with source information",