shadcn-vue-mcp

Instructions

Implementation Reference

• src/core/tools.ts:236-256 (registration)

  Registration of the 'component-quality-check' tool with FastMCP server. Defines the tool name, description, Zod input schema for componentCode, and execute handler that calls getComponentQualityCheckPrompt to generate the quality check prompt.
  // component-quality-check tool 组件质量检查 server.addTool({ name: "component-quality-check", description: "Automatically check Vue component quality and provide detailed feedback. Use this tool when you need to validate component quality, accessibility, performance, and best practices compliance. or when mentions /check.", parameters: z.object({ componentCode: z.string().describe("code of the component from component-builder tool"), }), execute: async (params) => { const prompt = getComponentQualityCheckPrompt(params.componentCode || ""); return { content: [ { type: "text", text: prompt, }, ], }; }, });
• src/core/prompts/componentPrompts.ts:215-328 (helper)

  Core helper function that generates the detailed prompt for Vue component quality auditing. Deserializes and validates input code, then constructs a comprehensive checklist covering accessibility, performance, consistency, maintainability, and DX with scoring system and refactoring instructions.
  export const getComponentQualityCheckPrompt = (componentCode: string) => { // Deserialize the escaped component code to properly formatted Vue component const formattedComponentCode = deserializeComponentCode(componentCode); // Validate that it's a proper Vue component if (!isValidVueComponent(formattedComponentCode)) { console.warn("Warning: The provided code may not be a valid Vue component"); } return ` You are an expert Vue.js code reviewer. Your goal is to provide a detailed quality analysis of a given Vue component based on a comprehensive checklist. **Your Task:** 1. Thoroughly analyze the Vue component code provided. 2. First, generate a complete **Quality Audit Report**. For each checklist item, mark its compliance with '✅' or '❌' and provide actionable feedback for any '❌' violations. 3. Next, generate a **Final Score & Recommendation** section based on the audit results and the provided scoring system. 4. Finally, provide a **Refactored Component Code** that addresses all identified violations and aims to achieve a perfect score. **Your entire output must follow this structure: 1. Report -> 2. Score -> 3. Refactored Code.** --- ## Component Code to Audit \`\`\`vue ${formattedComponentCode} \`\`\` Now, begin the audit for the component provided to you using the following checklist. --- ## Component Quality Checklist ### 1. Accessibility (A11y) > - \`[ ]\` **[A11y] Semantic HTML:** Ensure the component uses the most appropriate HTML5 semantic tags (e.g., \`<nav>\`, \`<main>\`, \`<table>\`, \`<button>\`). > - \`[ ]\` **[A11y] ARIA Roles & Landmarks:** Ensure proper landmark roles (e.g., \`role="main"\`) and ARIA attributes are used to define the structure. > - \`[ ]\` **[A11y] Headings:** Ensure heading levels (\`<h1>\` - \`<h6>\`) are structured logically and do not skip levels. > - \`[ ]\` **[A11y] ARIA Labels:** Ensure all non-descriptive interactive elements (like icon-only buttons) have a descriptive \`aria-label\`. > - \`[ ]\` **[A11y] ARIA States:** Ensure component states (e.g., \`aria-expanded\`, \`aria-selected\`, \`aria-current\`) are programmatically managed and accurately reflect the UI. > - \`[ ]\` **[A11y] ARIA Live Regions:** Ensure dynamic content updates are announced to screen readers using \`aria-live\` regions. > - \`[ ]\` **[A11y] Keyboard Navigable:** Verify all interactive elements are reachable and operable using the \`Tab\` key. > - \`[ ]\` **[A11y] Logical Focus Order:** Verify the keyboard focus order is logical and consistent with the visual layout. > - \`[ ]\` **[A11y] Visible Focus Indicator:** Verify a clear and highly visible focus indicator is present on all focusable elements. > - \`[ ]\` **[A11y] Focus Trapping:** Verify focus is trapped within modal dialogs or menus when they are active. > - \`[ ]\` **[A11y] Focus Restoration:** Verify focus returns to the triggering element after a modal or menu is closed. > - \`[ ]\` **[A11y] Standard Keyboard Interactions:** Verify standard keyboard shortcuts are supported (e.g., \`Escape\` to close, \`Enter\`/\`Space\` to activate). > - \`[ ]\` **[A11y] Color Contrast:** Verify all text-to-background color contrast ratios meet the WCAG 2.1 AA minimum of 4.5:1. > - \`[ ]\` **[A11y] Reduced Motion:** Verify animations and transitions are disabled or reduced when the \`prefers-reduced-motion\` media feature is detected. ### 2. Performance > - \`[ ]\` **[Performance] Render Optimization:** Confirm that the component avoids unnecessary re-renders (e.g., correct \`computed\` usage, no complex function calls in the template). > - \`[ ]\` **[Performance] Virtual Scrolling:** Implement virtual scrolling for any component that renders long lists of items. > - \`[ ]\` **[Performance] Lazy Loading:** Confirm that non-critical assets within the component (e.g., images below the fold, heavy libraries) are lazy-loaded. > - \`[ ]\` **[Performance] Tree-Shaking:** Confirm the component is side-effect-free at the top level to be compatible with tree-shaking. > - \`[ ]\` **[Performance] Event Listener Cleanup:** Ensure all manually attached event listeners are removed in the \`onUnmounted\` hook. > - \`[ ]\` **[Performance] Timer Cleanup:** Ensure all \`setInterval\` and \`setTimeout\` timers are cleared in the \`onUnmounted\` hook. > - \`[ ]\` **[Performance] Observer Cleanup:** Ensure all \`IntersectionObserver\`, \`MutationObserver\`, or other observers are disconnected in the \`onUnmounted\` hook. > - \`[ ]\` **[Performance] Mock Data Management:** Confirm internal mock data is clearly structured for demonstration and easily replaceable by props. It must not be included in the production bundle. ### 3. Consistency > - \`[ ]\` **[Consistency] Design Tokens:** Verify all styling (colors, spacing, typography, radii) strictly uses the CSS custom properties provided by the design system (shadcn-vue). > - \`[ ]\` **[Consistency] API Naming:** Verify \`props\` and \`emits\` naming conventions are consistent with the project's standards (e.g., \`is-\` prefix for booleans, \`onUpdate:modelValue\` for events). > - \`[ ]\` **[Consistency] Behavior:** Verify that common behaviors like loading states, error states, and empty states are handled in a way that is consistent with other components in the library. > - \`[ ]\` **[Consistency] Code Style:** Confirm the code passes all ESLint and Prettier checks without any errors or warnings. > - \`[ ]\` **[Consistency] JSDoc:** Confirm that all props, emits, and public functions have clear JSDoc comments. ### 4. Maintainability > - \`[ ]\` **[Maintainability] Single Responsibility Principle:** Verify the component adheres to the Single Responsibility Principle and is not overly complex. > - \`[ ]\` **[Maintainability] Composition API:** Verify logic is organized into logical blocks using the Composition API. > - \`[ ]\` **[Maintainability] Logic Extraction:** Verify that reusable or complex logic has been extracted into separate composable functions (\`use*.ts\`). > - \`[ ]\` **[Maintainability] Anti-Patterns:** Confirm the code contains no forbidden anti-patterns (e.g., no \`v-html\`, no modifying props directly, no deep \`v-if\` nesting). > - \`[ ]\` **[Maintainability] Cyclomatic Complexity:** Confirm that the cyclomatic complexity of all functions is low (ideally < 10). ### 5. Developer Experience (DX) > - \`[ ]\` **[DX] Strict TypeScript:** Enforce strict TypeScript for all \`props\`, \`emits\`, variables, and function signatures. **The \`any\` type is forbidden.** > - \`[ ]\` **[DX] API Intuitiveness:** Verify the component's API (\`props\`, \`emits\`, \`slots\`) is intuitive and self-documenting. > - \`[ ]\` **[DX] IDE Autocompletion:** Verify that the TypeScript definitions are precise enough to provide excellent IDE autocompletion for developers. > - \`[ ]\` **[DX] Clear Error Messages:** Verify the component provides clear, helpful console warnings or errors for invalid prop usage or incorrect configuration. > - \`[ ]\` **[DX] Mock Data Guidance:** Verify the code includes comments explaining the structure of the mock data and how to replace it with a real data source via props. --- ## Component Quality Scoring System - **Score Breakdown**: accessibility (14 items), performance (8 items), consistency (5 items), maintainability (5 items), developerExperience (6 items). Total items: 38. - **Scoring**: For each category, score = (passed_items / total_items_in_category) * 100. Total score = sum of category scores. - **Grades**: A+ (450-500), A (400-449), B+ (350-399), B (300-349), C (200-299), F (0-199). - **Recommendation:** [Provide a one-sentence summary, e.g., "Component is production-ready." or "Component requires refactoring to address critical accessibility and performance issues."] --- ## Refactored Component Code fix all items that are marked with a ❌, and make sure the checklist is fully green. \`\`\`vue // Your improved Vue component code goes here \`\`\` ## OPTIMIZATION GUIDELINES When generating optimized code, follow these principles: 1. **Targeted Fixes**: Address only the specific violations identified in the audit 2. **Preserve Functionality**: Never break existing component behavior 3. **Minimal Changes**: Make the smallest changes necessary to fix quality issues 4. **Vue 3 + shadcn/vue Compliance**: Ensure all fixes align with modern Vue.js and shadcn/vue standards 5. **Progressive Enhancement**: Improve quality without over-engineering 6. **Documentation**: Add comments explaining complex optimizations `; };
• src/core/utils/componentSerializer.ts:10-32 (helper)

  Utility function to deserialize escaped Vue component code strings (unescape \n, \", etc.) used in the quality check prompt generation to properly format the input code.
  export function deserializeComponentCode(escapedComponentCode: string): string { try { // Handle escaped newlines let formattedCode = escapedComponentCode.replace(/\\n/g, '\n'); // Handle escaped quotes formattedCode = formattedCode.replace(/\\"/g, '"'); formattedCode = formattedCode.replace(/\\'/g, "'"); // Handle escaped backslashes formattedCode = formattedCode.replace(/\\\\/g, '\\'); // Handle escaped tabs formattedCode = formattedCode.replace(/\\t/g, '\t'); // Handle escaped carriage returns formattedCode = formattedCode.replace(/\\r/g, '\r'); return formattedCode; } catch (error) { console.error('Error deserializing component code:', error); return escapedComponentCode; // Return original if deserialization fails }
• src/core/utils/componentSerializer.ts:73-77 (helper)

  Validation helper to check if code contains both <template> and <script> sections, ensuring it's a valid Vue SFC before processing in the prompt.
  export function isValidVueComponent(componentCode: string): boolean { const hasTemplate = /<template[\s\S]*?<\/template>/i.test(componentCode); const hasScript = /<script[\s\S]*?<\/script>/i.test(componentCode); return hasTemplate && hasScript;