@maltjoy/mcp-server 0.3.1 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@ MCP (Model Context Protocol) server for the Joy Design System. This server expos
 
 ## Features
 
-- 🔍 List all 74 available Joy Vue3 components
+- 🔍 List all available Joy Vue3 components with descriptions
 - 📚 Access component documentation (props, events, slots, exposed members)
 - 🏷️ Retrieve TypeScript types definitions for component props (variants, sizes, etc.)
 - 🎨 List 132 design tokens (colors, spacing, typography, etc.)
@@ -20,7 +20,7 @@ pnpm install
 pnpm build  # This also generates component documentation JSON files
 ```
 
-> **Note:** The build process automatically generates JSON documentation for all 74 components. This is required for the server to work.
+> **Note:** The build process automatically generates JSON documentation for all components. This is required for the server to work.
 
 ## Usage
 
@@ -43,7 +43,7 @@ pnpm dev
 
 ### 1. `joy_list_components`
 
-Lists all available Joy Vue3 components from the @maltjoy/core-vue library.
+Lists all available Joy Vue3 components from the @maltjoy/core-vue library, with descriptions extracted from Storybook stories.
 
 **Parameters:** None
 
@@ -51,9 +51,10 @@ Lists all available Joy Vue3 components from the @maltjoy/core-vue library.
 ```json
 {
   "components": [
-    "VJoyAdminBanner",
-    "VJoyAvailability",
-    "VJoyAvatar",
+    {
+      "name": "VJoyButton",
+      "description": "A versatile button component supporting multiple variants, sizes, and states."
+    },
     "..."
   ],
   "count": 74
@@ -217,7 +218,7 @@ joy-mcp-server/
 ├── src/
 │   ├── index.ts                    # Main server entry point
 │   ├── parser.ts                   # JSON documentation parser
-│   ├── json-metadata-generator.mjs # Generates component metadata
+│   ├── json-metadata-generator.mjs # Generates MCP metadata from component markdown
 │   └── tools/
 │       ├── list-components.ts      # Component listing tool
 │       ├── get-component-info.ts   # Component info retrieval tool
@@ -234,12 +235,30 @@ joy-mcp-server/
 │           └── *.types.ts          # Component TypeScript types
 ├── package.json
 ├── tsconfig.json
-├── README.md
-└── TROUBLESHOOTING.md              # Troubleshooting guide
+└── README.md
 ```
 
 The server reads the generated JSON documentation from `dist/doc/` which is automatically created during the build process by extracting metadata from Vue component files in `@maltjoy/core-vue`.
 
+Component metadata is authored in `packages/core-vue/src/components/**/JoyComponentName.metadata.md` using Markdown with YAML frontmatter. This keeps a short structured summary in frontmatter while allowing richer Markdown content in the body for multiline descriptions and future code examples. Storybook and the MCP generator both consume the same Markdown source. Storybook JSDoc comments remain a fallback when a component metadata file does not provide a description yet.
+
+Example:
+
+```md
+---
+category: Buttons
+description: >
+  Short summary used in list views and quick MCP responses.
+ignoreMcpDocumentation: false
+---
+
+Longer Markdown documentation rendered in Storybook and exposed by the MCP.
+
+```vue
+<VJoyButton variant="primary">Save</VJoyButton>
+```
+```
+
 ## Development
 
 To add new tools:
@@ -260,12 +279,6 @@ pnpm run dev
 # Generate only documentation (no compilation)
 pnpm run generate:components-docs:json
 
-# Test the server locally
-pnpm run test
-
-# Reload the server (kill MCP process)
-pnpm run reload
-
 # Start the server
 pnpm start
 
@@ -275,23 +288,12 @@ pnpm run inspector
 
 ## Troubleshooting
 
-### MCP server returns 0 components in Cursor
-
-If you're getting an empty list of components in Cursor but the server works fine locally:
-
-1. **Quick fix:** Use Cursor Command Palette → `Developer: Reload Window`
-
-2. **Or run:** `pnpm run reload` to kill the old server process
-
-3. **Verify locally:** `pnpm run test` should show 74 components
-
-For detailed troubleshooting steps, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
-
 ### Common Issues
 
 - **Documentation not generated:** Run `pnpm run build` to compile and generate docs
-- **Changes not taking effect:** Reload Cursor window to restart MCP server
+- **Changes not taking effect:** Reload your editor window to restart the MCP server
 - **Server fails to start:** Check that `dist/doc/index.json` exists
+- **0 components returned:** Reload your editor window (`Developer: Reload Window` in Cursor/VS Code)
 
 ## License
 

package/dist/doc/VJoyAdminBanner/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyAdminBanner",
   "displayName": "VJoyAdminBanner",
+  "description": "The AdminBanner component displays a visual indicator when users are viewing the application in admin mode.\nIt features a distinctive banner with an eye icon and customizable label, typically positioned at the top of the interface to clearly communicate the current viewing context to administrators.",
+  "category": "Admin",
   "props": [
     {
       "name": "label",

package/dist/doc/VJoyAvailability/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyAvailability",
   "displayName": "VJoyAvailability",
+  "description": "A status indicator component for displaying user availability information.\nFeatures colored dots and optional labels to communicate different availability states such as available, not available, available soon, or partially available.\nCan be displayed as a simple dot indicator or with descriptive text labels that handle long content gracefully.",
+  "category": "View",
   "props": [
     {
       "name": "label",

package/dist/doc/VJoyAvatar/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyAvatar",
   "displayName": "VJoyAvatar",
+  "description": "A versatile avatar component for displaying user profile pictures, initials, or placeholders depending on given properties.\nSupports multiple sizes, fallback to initials when no photo is provided, anonymous states with icons, numeric indicators for \"more users\" displays, and special variants like strategy profiles and company avatars.\nCan be styled as clickable links and includes empty states for various use cases.",
+  "category": "View",
   "props": [
     {
       "name": "size",

package/dist/doc/VJoyAvatarsList/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyAvatarsList",
   "displayName": "VJoyAvatarsList",
+  "description": "A container component for displaying multiple avatars in a styled group layout.\nProvides consistent spacing and alignment for avatar collections, with an optional compressed mode for more compact displays.\nDesigned to work seamlessly with VJoyAvatar components.",
+  "category": "View",
   "props": [
     {
       "name": "compress",

package/dist/doc/VJoyBadge/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyBadge",
   "displayName": "VJoyBadge",
+  "description": "A versatile badge component for labeling, categorizing, and highlighting content with colored indicators.\nSupports various color variants for different semantic meanings, optional bulletpoint dots for visual emphasis,\nand can display either text labels or numeric values. Perfect for status indicators, tags, and notification counters.",
+  "category": "View",
   "props": [
     {
       "name": "label",

package/dist/doc/VJoyBadgeLevel/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyBadgeLevel",
   "displayName": "VJoyBadgeLevel",
+  "description": "A specialized badge component for displaying user achievement levels and status indicators.\nFeatures custom SVG icons for different categories including SuperMalter levels (with crown icons),\nHigh Potential badges (with diamond icons), verified status, and special designations like Malt Linker.\nCan display icons only or with accompanying text labels for different user recognition levels.",
+  "category": "View",
   "props": [
     {
       "name": "superMalterLevel",

package/dist/doc/VJoyBlockSkeleton/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyBlockSkeleton",
   "displayName": "VJoyBlockSkeleton",
+  "description": "A highly configurable skeleton loading component for creating placeholder blocks during content loading.\nFeatures customizable dimensions, circle variant for avatars, and smooth shimmer animations to improve perceived performance.\nMore flexible than VJoyFormFieldSkeleton and integrates seamlessly with VJoyWrapper for responsive layouts.",
+  "category": "Skeletons",
   "props": [
     {
       "name": "circle",

package/dist/doc/VJoyBottomSheet/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyBottomSheet",
   "displayName": "VJoyBottomSheet",
+  "description": "A mobile-optimized bottom sheet component that slides up from the bottom of the screen.\nFeatures drag-to-dismiss functionality, customizable content slots, and teleportation support.\n\n**IMPORTANT** : for documentation purpose, you can't hide the bottom sheets here.\n\nBy default, the component is teleported to the body root. You can override this by passing a teleport value.\n\nHow to use:\n\n```html\n<template>\n   <VJoyBottomSheet ref=\"bottomSheet\">\n      <template #bottom-sheet-content>\n         The content\n      </template>\n   </VJoyBottomSheet>\n</template>\n\n<script lang=\"ts\" setup>\nimport {ref} from 'vue';\nimport {VJoyBottomSheet} from '@maltjoy/core-vue';\n\n// declare the VJoyBottomSheet ref using the component type definition\nconst bottomSheet = ref<InstanceType<typeof VJoyBottomSheet> | null>(null);\n\n// use this function when you need to (onMounted, when clicking on any trigger...)\nfunction openBottomSheet() {\n   bottomSheet.value?.show();\n}\n\n</script>\n```\n\n> You can use the `VJoyBottomSheetTrigger` subcomponent if it's easier for you.",
+  "category": "Overlays",
   "props": [
     {
       "name": "closeLabel",

package/dist/doc/VJoyBottomSheetTrigger/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyBottomSheetTrigger",
   "displayName": "VJoyBottomSheetTrigger",
+  "description": "",
+  "category": "Overlays",
   "props": [
     {
       "name": "bottomSheet",

package/dist/doc/VJoyButton/metadata.json

@@ -1,6 +1,8 @@
 {
   "name": "JoyButton",
   "displayName": "VJoyButton",
+  "description": "A button component supporting multiple variants, sizes, and states.\nFeatures icon support, loading states and can function as either a button or link element.\nIncludes ripple effects and comprehensive styling options for different use cases from primary actions to subtle ghost buttons.\n\n**Tips:** set a \"href\" attribute to make the button a link.",
+  "category": "Buttons",
   "props": [
     {
       "name": "size",

package/dist/doc/VJoyButtonCard/JoyButtonCard.types.ts

@@ -0,0 +1,15 @@
+import type {Component} from 'vue';
+
+export type TJoyButtonCardType = 'a' | 'button' | Component;
+export type TJoyButtonCardAlign = 'left' | 'center' | 'right';
+
+export interface VJoyButtonCardProps {
+    /** Disabled state */
+    disabled?: boolean;
+    /** Native href for anchor rendering */
+    href?: string;
+    /** HTML element or Vue component to render */
+    type?: TJoyButtonCardType;
+    /** Content alignment inside the card */
+    align?: TJoyButtonCardAlign;
+}

package/dist/doc/VJoyButtonCard/metadata.json

@@ -0,0 +1,78 @@
+{
+  "name": "JoyButtonCard",
+  "displayName": "VJoyButtonCard",
+  "description": "This component is a CTA or a link used to render complex interactive buttons.\n\nIf your goal is to only use a short string, use `VJoyButton` instead.\n\nPlease note that you have to deal with the content and its style by yourself.",
+  "category": "Buttons",
+  "props": [
+    {
+      "name": "disabled",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "Disabled state",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "href",
+      "type": "string | undefined",
+      "required": false,
+      "description": "Native href for anchor rendering",
+      "possibleValues": [
+        "string"
+      ]
+    },
+    {
+      "name": "type",
+      "type": "TJoyButtonCardType | undefined",
+      "required": false,
+      "default": "\"button\"",
+      "description": "HTML element or Vue component to render",
+      "possibleValues": null
+    },
+    {
+      "name": "align",
+      "type": "TJoyButtonCardAlign | undefined",
+      "required": false,
+      "default": "\"left\"",
+      "description": "Content alignment inside the card",
+      "possibleValues": [
+        "left",
+        "right",
+        "center"
+      ]
+    }
+  ],
+  "events": [],
+  "slots": [
+    {
+      "name": "default",
+      "description": "Main content for the card"
+    }
+  ],
+  "exposed": [
+    {
+      "name": "type",
+      "type": "TJoyButtonCardType",
+      "isMethod": false
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "isMethod": false
+    },
+    {
+      "name": "align",
+      "type": "TJoyButtonCardAlign",
+      "isMethod": false
+    },
+    {
+      "name": "href",
+      "type": "string | undefined",
+      "isMethod": false
+    }
+  ],
+  "hasVModel": false
+}

package/dist/doc/VJoyCheckbox/JoyCheckbox.types.ts

@@ -0,0 +1,26 @@
+export interface VJoyCheckboxProps {
+    /** Can't be used in addition of v-model. See usage : https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes */
+    indeterminate?: boolean;
+    /**
+     * Internal purpose in order to prevent double focus mark on selectable-item
+     * @internal
+     */
+    displayFocus?: boolean;
+    /** Use it to replace the default slot */
+    label?: string;
+    /** Checked state of the component */
+    checked?: boolean;
+    /**
+     * Invalid state of the component
+     *
+     * Note: A checked checkbox cannot be invalid (the `checked` state takes priority over `invalid` state).
+     */
+    invalid?: boolean;
+    /** The value is used in multiselection context in order to build array of values. */
+    value?: string;
+    /** Removes any interactivity if disabled */
+    disabled?: boolean;
+    id?: string;
+    name?: string;
+    required?: boolean;
+}

package/dist/doc/VJoyCheckbox/metadata.json

@@ -1,57 +1,57 @@
 {
   "name": "JoyCheckbox",
   "displayName": "VJoyCheckbox",
+  "description": "A form checkbox component with support for standard, indeterminate, and disabled states.\nFeatures accessible labeling, focus indicators, form integration with validation feedback, and additional content slots.\nSupports both single selections scenarios with proper event handling and state management.",
+  "category": "Forms",
   "props": [
     {
-      "name": "invalid",
+      "name": "indeterminate",
       "type": "boolean | undefined",
       "required": false,
       "default": "false",
-      "description": "Invalid state of the component\n\nNote: A checked checkbox cannot be invalid (the `checked` state takes priority over `invalid` state).",
+      "description": "Can't be used in addition of v-model. See usage : https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes",
       "possibleValues": [
         "false",
         "true"
       ]
     },
     {
-      "name": "required",
+      "name": "displayFocus",
       "type": "boolean | undefined",
       "required": false,
-      "default": "false",
-      "description": "",
+      "default": "true",
+      "description": "Internal purpose in order to prevent double focus mark on selectable-item",
       "possibleValues": [
         "false",
         "true"
       ]
     },
     {
-      "name": "indeterminate",
-      "type": "boolean | undefined",
+      "name": "label",
+      "type": "string | undefined",
       "required": false,
-      "default": "false",
-      "description": "Can't be used in addition of v-model. See usage : https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes",
+      "description": "Use it to replace the default slot",
       "possibleValues": [
-        "false",
-        "true"
+        "string"
       ]
     },
     {
-      "name": "displayFocus",
+      "name": "checked",
       "type": "boolean | undefined",
       "required": false,
-      "default": "true",
-      "description": "Internal purpose in order to prevent double focus mark on selectable-item",
+      "default": "false",
+      "description": "Checked state of the component",
       "possibleValues": [
         "false",
         "true"
       ]
     },
     {
-      "name": "checked",
+      "name": "invalid",
       "type": "boolean | undefined",
       "required": false,
       "default": "false",
-      "description": "Checked state of the component",
+      "description": "Invalid state of the component\n\nNote: A checked checkbox cannot be invalid (the `checked` state takes priority over `invalid` state).",
       "possibleValues": [
         "false",
         "true"
@@ -79,16 +79,16 @@
       ]
     },
     {
-      "name": "label",
+      "name": "id",
       "type": "string | undefined",
       "required": false,
-      "description": "Use it to replace the default slot",
+      "description": "",
       "possibleValues": [
         "string"
       ]
     },
     {
-      "name": "id",
+      "name": "name",
       "type": "string | undefined",
       "required": false,
       "description": "",
@@ -97,12 +97,14 @@
       ]
     },
     {
-      "name": "name",
-      "type": "string | undefined",
+      "name": "required",
+      "type": "boolean | undefined",
       "required": false,
+      "default": "false",
       "description": "",
       "possibleValues": [
-        "string"
+        "false",
+        "true"
       ]
     }
   ],
@@ -144,6 +146,11 @@
       "type": "boolean",
       "isMethod": false
     },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "isMethod": false
+    },
     {
       "name": "indeterminate",
       "type": "boolean",
@@ -164,11 +171,6 @@
       "type": "string",
       "isMethod": false
     },
-    {
-      "name": "disabled",
-      "type": "boolean",
-      "isMethod": false
-    },
     {
       "name": "label",
       "type": "string | undefined",

package/dist/doc/VJoyCheckboxCard/JoyCheckboxCard.types.ts

@@ -0,0 +1,8 @@
+import type {VJoyCheckboxProps} from '../JoyCheckbox/JoyCheckbox.types';
+
+export interface VJoyCheckboxCardProps extends Omit<VJoyCheckboxProps, 'displayFocus'> {
+    /** Secondary label displayed below the main label */
+    subLabel?: string;
+    /** Whether the checkbox card should fit its content */
+    fitContent?: boolean;
+}