Magic UI MCP Server

Instructions

Implementation Reference

• src/server.ts:173-235 (handler)

  Main handler logic for fetching, processing, and formatting detailed information (code, install instructions, examples) for each widget component in the 'Widgets' category.
  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/utils/schemas.ts:19-23 (schema)

  Zod schema for validating the structure of individual component details (including install instructions, code content, and examples) returned by the getWidgets tool.
  export const IndividualComponentSchema = ComponentSchema.extend({ install: z.string(), content: z.string(), examples: z.array(ExampleSchema), });
• src/server.ts:252-283 (registration)

  Registers the getWidgets tool (via template `get${category}` when category='Widgets') with empty input schema and handler that fetches and returns JSON of widget components.
  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:148-157 (helper)

  Defines the exact list of Magic UI 'Widgets' components that are retrieved and detailed by the getWidgets tool.
  Widgets: [ "animated-list", "tweet-card", "client-tweet-card", "lens", "pointer", "avatar-circles", "icon-cloud", "globe", ],
• src/server.ts:52-82 (helper)

  Builds a mapping from widget components to their associated example implementations, used to include relevant examples in getWidgets output.
  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; }