DEV Community

Cover image for How to build a MCP (model context protocol) server for UI libraries + repo
Marcello Novelli
Marcello Novelli

Posted on

How to build a MCP (model context protocol) server for UI libraries + repo

#mcp #ai #ui #webdev

Introduction

The Model Context Protocol (MCP) represents a paradigm shift in how AI assistants interact with external data sources and tools. Developed by Anthropic, MCP enables AI models like Claude to seamlessly access and utilize external resources through standardized server implementations. This creates powerful workflows where AI can directly interact with your UI component libraries, documentation, and tools.

For UI library maintainers and design system creators, MCP opens up unprecedented opportunities. Imagine an AI assistant that can instantly understand your component library structure, provide implementation details, suggest appropriate components based on context, and even help developers implement designs using your exact components.

In this guide, we'll walk through building a complete MCP server tailored for UI libraries.

Example Repo 👨‍💻

For a complete example implementation, including all the code discussed in this article, please refer to the mcp-starter repository available on GitHub.

Understanding the Model Context Protocol

What is MCP?

The Model Context Protocol is a standardized way for AI assistants to communicate with external services and data sources.

Think of it as an API specifically designed for AI consumption. Unlike traditional REST APIs that return data for human consumption, MCP servers provide structured data and tools that AI models can understand and utilize effectively.

MCP servers expose a set of tools that AI models can invoke, allowing them to fetch data, perform actions, and interact with external systems in a way that is context-aware and intelligent.

Why MCP for UI Libraries?

UI libraries face unique challenges in AI integration:

  1. Component Discovery: Developers often struggle to find the right component for their needs
  2. Implementation Guidance: Understanding component props, usage patterns, and best practices
  3. Context-Aware Suggestions: Recommending components based on design context
  4. Code Generation: Generating proper implementation code with correct imports and usage

MCP addresses these challenges by providing AI models with direct access to your component registry, enabling intelligent recommendations and code generation.

The Registry Format Foundation

Many modern UI libraries follow the "registry" format popularized by shadcn/ui. This format provides:

  • Structured Component Definitions: JSON files describing each component
  • Standardized Metadata: Type information, descriptions, and dependencies
  • Version Control: Trackable changes and updates
  • CLI Integration: Easy installation and updates

Our MCP server leverages this existing structure, making it ideal for libraries already following this pattern.
Learn more about the registry format in the shadcn/ui documentation.

Project Architecture Overview

Before diving into implementation, let's understand the architecture of our MCP server:

mcp-server/ ├── src/ │ ├── server.ts # Main MCP server implementation │ ├── lib/ │ │ ├── config.ts # Configuration settings │ │ └── categories.ts # Component organization │ └── utils/ │ ├── api.ts # Registry API interactions │ ├── schemas.ts # Data validation │ ├── formatters.ts # Data transformation │ └── index.ts # Utility exports ├── package.json # Dependencies and scripts └── tsconfig.json # TypeScript configuration
Enter fullscreen mode Exit fullscreen mode

This architecture separates concerns cleanly:

  • Server Layer: Handles MCP protocol communication
  • Configuration Layer: Manages project-specific settings
  • API Layer: Fetches and processes registry data
  • Validation Layer: Ensures data integrity
  • Transformation Layer: Formats data for AI consumption

You can of couse extend this architecture as needed, adding new utilities, categories, or API endpoints to suit your specific requirements.
This is just a starting point to get you going.

Step-by-Step Implementation

Step 1: Project Setup and Dependencies

First, let's understand why we need each dependency:

{ "dependencies": { "@modelcontextprotocol/sdk": "^1.13.1", "zod": "^3.25.67" }, "devDependencies": { "@modelcontextprotocol/inspector": "^0.14.2", "@types/node": "^22.14.1", "tsup": "^8.5.0", "tsx": "^4.20.3", "typescript": "^5.8.3" } }
Enter fullscreen mode Exit fullscreen mode

Why these dependencies?

  • @modelcontextprotocol/sdk: The core SDK for building MCP servers. It handles protocol communication, request/response formatting, and transport management.
  • zod: Runtime type validation. Essential for ensuring data integrity when fetching from external registries.
  • @modelcontextprotocol/inspector: Development tool for testing MCP servers interactively.
  • tsup: Fast TypeScript bundler optimized for Node.js applications.
  • tsx: TypeScript execution with hot reloading for development.

Step 2: Configuration Management

Configuration is crucial for making your MCP server adaptable. I like to keep everything in one file so here's our configuration structure:

// src/lib/config.ts export const mcpConfig = { projectName: "your-ui-library", baseUrl: "https://your-ui-library.com", registryUrl: "https://your-ui-library.com/r", registryFileUrl: "https://your-ui-library.com/registry.json", };
Enter fullscreen mode Exit fullscreen mode

The configuration assumes your registry follows this URL structure:

  • Registry Index: /registry.json - Lists all available components
  • Component Details: /r/{component-name}.json - Individual component implementations

Step 3: Data Validation with Zod Schemas

I use zod for validation to ensure that all data fetched from the registry adheres to expected formats. This is an example of the schemas we will use:

// src/utils/schemas.ts import { z } from "zod"; export const ComponentSchema = z.object({ name: z.string(), type: z.string(), description: z.string().optional(), }); export const ComponentDetailSchema = z.object({ name: z.string(), type: z.string(), files: z.array( z.object({ content: z.string(), }) ), }); export const IndividualComponentSchema = ComponentSchema.extend({ install: z.string(), content: z.string(), examples: z.array( z.object({ name: z.string(), type: z.string(), description: z.string(), content: z.string(), }) ), });
Enter fullscreen mode Exit fullscreen mode

We will use these schemas later when fetching and processing component data.

Step 4: API Layer Implementation

We then create the API layer that interacts with our component registry. This layer fetches component data, validates it, and prepares it for use by the MCP server.

The API layer handles all interactions with your component registry:

// src/utils/api.ts import { mcpConfig } from "../lib/config.js"; import { ComponentDetailSchema, ComponentSchema } from "./schemas.js"; export async function fetchUIComponents() { try { const response = await fetch(mcpConfig.registryFileUrl); if (!response.ok) { throw new Error(`Failed to fetch registry: ${response.statusText}`); } const data = await response.json(); return data.registry .filter((item: any) => item.type === "registry:component") .map((item: any) => { try { return ComponentSchema.parse(item); } catch (parseError) { console.error(`Invalid component data for ${item.name}:`, parseError); return null; } }) .filter(Boolean); } catch (error) { console.error("Error fetching components:", error); return []; } } export async function fetchComponentDetails(componentName: string) { try { const response = await fetch( `${mcpConfig.registryUrl}/${componentName}.json` ); if (!response.ok) { throw new Error( `Failed to fetch component ${componentName}: ${response.statusText}` ); } const data = await response.json(); return ComponentDetailSchema.parse(data); } catch (error) { console.error(`Error fetching component ${componentName}:`, error); throw error; } }
Enter fullscreen mode Exit fullscreen mode

This API layer provides two main functions:

  • fetchUIComponents: Retrieves the list of all components from the registry
  • fetchComponentDetails: Fetches detailed implementation data for a specific component

You can extend this layer to include additional API endpoints as needed, such as fetching specific categories or related components.

Step 5: Component Organization and Categories

To make it easier for AI models to find and use components, we categorize them based on their functionality. This is especially important for large libraries where a flat list of components would be unwieldy. Also, some AI models and IDEs have limits on the number of tools they can handle, so categorizing helps to keep the number of tools manageable.

For example, we can define categories like "Buttons", "Forms", "Navigation", and "Data Display":

// src/lib/categories.ts export const componentCategories = { Buttons: [ "button-primary", "button-secondary", "button-ghost", "button-outline", ], Forms: ["input-text", "input-email", "textarea", "select", "checkbox"], Navigation: ["navbar", "sidebar", "breadcrumbs", "pagination"], DataDisplay: ["table", "card", "badge", "avatar", "tooltip"], };
Enter fullscreen mode Exit fullscreen mode

The way you define categories can vary based on your component library's structure and the needs of your users. The key is to create logical groupings that make sense for developers looking to implement UI components.

Step 6: Data Transformation and Formatting

We add a formatter function to format the component names and generate installation instructions. This preparares the data for AI consumption, ensuring that the AI models receive consistent and actionable information.

This is also where you could add any additional formatting or transformation logic needed for your specific use case, such as generating import statements or usage examples.

// src/utils/formatters.ts export function formatComponentName(componentName: string): string { return componentName .split("-") .map((part) => part.charAt(0).toUpperCase() + part.slice(1)) .join(""); } export function generateInstallInstructions(componentName: string): string { const formattedName = formatComponentName(componentName); return `You can install the component using shadcn/ui CLI: npx shadcn@latest add "${mcpConfig.registryUrl}/${componentName}.json" Once installed, import it like this: import { ${formattedName} } from "@/components/ui/${componentName}";`; }
Enter fullscreen mode Exit fullscreen mode

Step 7: Core MCP Server Implementation

Now we implement the main server logic.

Since we are using the MCP SDK, creating the server is straightforward. The server will handle incoming requests, invoke tools, and return structured responses that AI models can understand.

All you need to do to create a basic MCP server is to initialize the McpServer class and connect it to a transport layer. In this case, we will use the StdioServerTransport, which allows the server to communicate over standard input/output streams.

MCP SDK supports other transports. Please refer to the MCP SDK documentation for more details.

// src/server.ts #!/usr/bin/env node  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { fetchUIComponents, fetchComponentDetails } from "./utils/index.js"; import { componentCategories } from "./lib/categories.js"; // Initialize the MCP Server const server = new McpServer({ name: "your-ui-library-mcp", version: "1.0.0", });
Enter fullscreen mode Exit fullscreen mode

This initializes the MCP server with a name and version. You can customize these values to match your project.

Step 8: Implementing MCP Tools

Ok, now that we have a MCP server, we can start implementing tools that AI models can invoke. Tools are the core functionality that allows AI models to interact with your component library.

As already mentioned, this step can vary dramatically based on your specific use cases.

In this example, we will register a tool to fetch all UI components and another tool for each category of components.
This allows AI models to discover all components and understand their usage.

// Main tool for getting all components server.tool( "getUIComponents", "Provides a comprehensive list of all UI components.", {}, async () => { try { const uiComponents = await fetchUIComponents(); return { content: [ { type: "text", text: JSON.stringify(uiComponents, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text", text: "Failed to fetch components", }, ], isError: true, }; } } );
Enter fullscreen mode Exit fullscreen mode

What this code is doing is essentially registering a tool named getUIComponents that AI models can invoke. When called, it fetches all UI components from the registry and returns them in a structured format.

Step 9: Dynamic Category Tool Generation

Now that we have a generic tool for fetching all components, we can dynamically generate more "specialized" tools for each category defined in componentCategories. This allows AI models to access specific groups of components without overwhelming them with too many options.

async function registerComponentsCategoryTools() { const [components, allExampleComponents] = await Promise.all([ fetchUIComponents(), fetchExampleComponents(), ]); for (const [category, categoryComponents] of Object.entries( componentCategories )) { const componentNamesString = categoryComponents.join(", "); server.tool( `get${category}`, `Provides implementation details for ${componentNamesString} components.`, {}, async () => { try { const categoryResults = await fetchComponentsByCategory( categoryComponents, components, exampleNamesByComponent ); return { content: [ { type: "text", text: JSON.stringify(categoryResults, null, 2), }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error processing ${category} components` }, ], isError: true, }; } } ); } }
Enter fullscreen mode Exit fullscreen mode

This function registers a tool for each category defined in componentCategories. Each tool fetches the relevant components and returns their details in a structured format.

This dynamic registration allows you to easily add or remove categories without changing the core server logic.

Step 10: Advanced Component Processing

The component processing logic handles the complex task of enriching component data.

It fetches detailed implementation data, generates installation instructions, and formats the content for AI consumption. This is where we ensure that AI models receive all necessary context to understand and use the components effectively.

Also, with zod, we can validate the data at runtime to ensure it adheres to our expected schemas.

async function fetchComponentsByCategory( categoryComponents: string[], allComponents: any[], exampleNamesByComponent: Map<string, string[]> ) { const componentResults = []; for (const componentName of categoryComponents) { const component = allComponents.find((c) => c.name === componentName); if (!component) continue; try { const componentDetails = await fetchComponentDetails(componentName); const componentContent = componentDetails.files[0]?.content; const installInstructions = generateInstallInstructions(componentName); const disclaimerText = generateDisclaimerText(componentName); const validatedComponent = IndividualComponentSchema.parse({ name: component.name, type: component.type, description: component.description, install: installInstructions, content: componentContent && disclaimerText + componentContent, examples: formattedExamples, }); componentResults.push(validatedComponent); } catch (error) { console.error(`Error processing component ${componentName}:`, error); } } return componentResults; }
Enter fullscreen mode Exit fullscreen mode

Step 11: Server Lifecycle Management

As one of the final steps, we need to create a function to start the server and handle any errors gracefully. This ensures that even if some components fail to load, the server can still operate with limited functionality and / or provide useful error messages.

async function startServer() { try { // Initialize category tools first await registerComponentsCategoryTools(); // Connect to stdio transport const transport = new StdioServerTransport(); await server.connect(transport); console.log("✅ MCP server started successfully"); } catch (error) { console.error("❌ Error starting MCP server:", error); // Try to start server anyway with basic functionality try { const transport = new StdioServerTransport(); await server.connect(transport); console.error("⚠️ MCP server started with limited functionality"); } catch (connectionError) { console.error("❌ Failed to connect to transport:", connectionError); process.exit(1); } } } // Start the server startServer();
Enter fullscreen mode Exit fullscreen mode

Development and Testing

Now that we have a basic MCP server implementation, let's discuss how to develop and test it effectively.

Development Workflow

The project includes several development scripts:

{ "scripts": { "build": "tsup src/server.ts --format esm,cjs --dts --out-dir dist", "dev": "tsx watch src/server.ts", "inspect": "mcp-inspector node dist/server.js", "start": "node dist/server.js" } }
Enter fullscreen mode Exit fullscreen mode

Using the MCP Inspector

One of fastest and easiest way to test your MCP server is to use the MCP Inspector. This tool provides a web interface for interacting with your MCP server, allowing you to invoke tools, view responses, and debug issues.

If you install the inspector as a dev dependency, you can run it with:

pnpm run inspect
Enter fullscreen mode Exit fullscreen mode

Or if you prefer to run it without installing, you can use:

npx mcp-inspector
Enter fullscreen mode Exit fullscreen mode

This opens a web interface where you can:

  1. Test Tools: Invoke tools with different parameters
  2. View Responses: See exactly what AI models receive
  3. Debug Errors: Identify issues in tool implementations
  4. Validate Schema: Ensure data matches expected formats

Testing Your Implementation

Before deploying, test your MCP server thoroughly:

  1. Component Discovery: Verify all components are found
  2. Category Tools: Test each category tool individually
  3. Error Handling: Test with invalid component names
  4. Performance: Check response times with large component libraries
  5. Data Integrity: Validate all returned data matches schemas

Deployment and Integration

Local Development Setup

For local development with Claude Desktop:

  1. Build the server: 
pnpm run build
Enter fullscreen mode Exit fullscreen mode
  1. Configure Claude Desktop (~/.config/Claude Desktop/claude_desktop_config.json): 
{ "mcpServers": { "your-ui-library": { "command": "node", "args": ["/absolute/path/to/your/dist/server.js"] } } }
Enter fullscreen mode Exit fullscreen mode
  1. Restart Claude Desktop to load the new server

Production Deployment

For production deployment, consider:

  1. NPM Package: Publish as an NPM package for easy installation
  2. Docker Container: Containerize for consistent deployment
  3. Server Hosting: Deploy on cloud platforms for remote access
  4. CI/CD Integration: Automate builds and deployments

Configuration Management

In production, externalize configuration:

export const mcpConfig = { projectName: process.env.PROJECT_NAME || "your-ui-library", baseUrl: process.env.BASE_URL || "https://your-ui-library.com", registryUrl: process.env.REGISTRY_URL || "https://your-ui-library.com/r", registryFileUrl: process.env.REGISTRY_FILE_URL || "https://your-ui-library.com/registry.json", };
Enter fullscreen mode Exit fullscreen mode

Conclusion

Building an MCP server for UI libraries represents a significant leap forward in how developers can interact with component systems. By providing AI assistants with direct access to your component registry, you enable intelligent recommendations, automated code generation, and contextual guidance that dramatically improves the developer experience.

Example Repo

For a complete example implementation, including all the code discussed in this article, please refer to the mcp-starter repository.

References and Further Reading

Awknowledgments

This was originally inspired by Magic UI MCP Server.

Top comments (0)