Magic UI MCP Server

Instructions

Implementation Reference

• src/server.ts:252-283 (registration)

  Dynamic registration of the 'getWidgets' tool (and other category tools) using template literal `get${category}` where category='Widgets'
  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) { let errorMessage = `Error processing ${category} components`; if (error instanceof Error) { errorMessage += `: ${error.message}`; } return { content: [{ type: "text", text: errorMessage }], isError: true, }; } }, );
• src/server.ts:173-235 (handler)

  Core handler function executed by the getWidgets tool to fetch, process, and validate detailed information for all widgets components
  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 relevantExampleNames = exampleNamesByComponent.get(componentName) || []; // Generate installation instructions const installInstructions = `Install the component using the same process as \ shadcn/ui. If you run into linter or dependency errors, make sure to install the \ component using these instructions. For example, with npm/npx: npx shadcn@latest add \ "https://magicui.design/r/${componentName}.json" (Rules: make sure the URL is wrapped in \ double quotes and use shadcn not shadcn-ui, or the command will fail). After installation, \ you can import the component like this: import { ${formatComponentName(component.name)} } from \ "@/components/ui/${componentName}";`; const disclaimerText = `The code below is for context only. It helps you understand \ the component's props, types, and behavior. To actually install and use the \ component, refer to the install instructions above. After installing, the component \ will be available for import via: import { ${formatComponentName(component.name)} } \ from "@/components/ui/${componentName}";`; const exampleDetailsList = await Promise.all( relevantExampleNames.map((name) => fetchExampleDetails(name)), ); const formattedExamples = exampleDetailsList .filter((details) => details !== null) .map((details) => ({ name: details.name, type: details.type, description: details.description, content: details.files[0]?.content, })); 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; }
• src/server.ts:148-157 (helper)

  Definition of the 'Widgets' category components list used to determine which components are included in the getWidgets tool response
  Widgets: [ "animated-list", "tweet-card", "client-tweet-card", "lens", "pointer", "avatar-circles", "icon-cloud", "globe", ],
• src/utils/schemas.ts:19-23 (schema)

  Zod schema used to parse and validate individual component data in the getWidgets response
  export const IndividualComponentSchema = ComponentSchema.extend({ install: z.string(), content: z.string(), examples: z.array(ExampleSchema), });
• src/server.ts:52-82 (helper)

  Helper function to build a map of example names by component, used to associate examples with widgets in getWidgets response
  function buildExampleComponentMap( allExampleComponents: Array<{ name: string; registryDependencies?: string[]; }>, ): Map<string, string[]> { const exampleMap = new Map<string, string[]>(); for (const example of allExampleComponents) { if ( example.registryDependencies && Array.isArray(example.registryDependencies) ) { for (const depUrl of example.registryDependencies) { if (typeof depUrl === "string" && depUrl.includes("magicui.design")) { const componentNameMatch = depUrl.match(/\/r\/([^\/]+)$/); if (componentNameMatch && componentNameMatch[1]) { const componentName = componentNameMatch[1]; if (!exampleMap.has(componentName)) { exampleMap.set(componentName, []); } if (!exampleMap.get(componentName)?.includes(example.name)) { exampleMap.get(componentName)?.push(example.name); } } } } } } return exampleMap; }