@maltjoy/mcp-server 0.3.2 → 0.4.0

package/README.md

@@ -218,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
@@ -238,7 +238,26 @@ joy-mcp-server/
 └── 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 descriptions are extracted from JSDoc comments in Storybook story files.
+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
 

package/dist/doc/VJoyAdminBanner/metadata.json

@@ -1,7 +1,8 @@
 {
   "name": "JoyAdminBanner",
   "displayName": "VJoyAdminBanner",
-  "description": "The AdminBanner component displays a visual indicator when users are viewing the application in admin mode. It 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.",
+  "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,7 +1,8 @@
 {
   "name": "JoyAvailability",
   "displayName": "VJoyAvailability",
-  "description": "A status indicator component for displaying user availability information. Features colored dots and optional labels to communicate different availability states such as available, not available, available soon, or partially available. Can be displayed as a simple dot indicator or with descriptive text labels that handle long content gracefully.",
+  "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,7 +1,8 @@
 {
   "name": "JoyAvatar",
   "displayName": "VJoyAvatar",
-  "description": "A versatile avatar component for displaying user profile pictures, initials, or placeholders depending on given properties. Supports 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. Can be styled as clickable links and includes empty states for various use cases.",
+  "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,7 +1,8 @@
 {
   "name": "JoyAvatarsList",
   "displayName": "VJoyAvatarsList",
-  "description": "A container component for displaying multiple avatars in a styled group layout. Provides consistent spacing and alignment for avatar collections, with an optional compressed mode for more compact displays. Designed to work seamlessly with VJoyAvatar components.",
+  "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,7 +1,8 @@
 {
   "name": "JoyBadge",
   "displayName": "VJoyBadge",
-  "description": "A versatile badge component for labeling, categorizing, and highlighting content with colored indicators. Supports various color variants for different semantic meanings, optional bulletpoint dots for visual emphasis, and can display either text labels or numeric values. Perfect for status indicators, tags, and notification counters.",
+  "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,7 +1,8 @@
 {
   "name": "JoyBadgeLevel",
   "displayName": "VJoyBadgeLevel",
-  "description": "A specialized badge component for displaying user achievement levels and status indicators. Features custom SVG icons for different categories including SuperMalter levels (with crown icons), High Potential badges (with diamond icons), verified status, and special designations like Malt Linker. Can display icons only or with accompanying text labels for different user recognition levels.",
+  "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,7 +1,8 @@
 {
   "name": "JoyBlockSkeleton",
   "displayName": "VJoyBlockSkeleton",
-  "description": "A highly configurable skeleton loading component for creating placeholder blocks during content loading. Features customizable dimensions, circle variant for avatars, and smooth shimmer animations to improve perceived performance. More flexible than VJoyFormFieldSkeleton and integrates seamlessly with VJoyWrapper for responsive layouts.",
+  "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,7 +1,8 @@
 {
   "name": "JoyBottomSheet",
   "displayName": "VJoyBottomSheet",
-  "description": "",
+  "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

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

package/dist/doc/VJoyButton/metadata.json

@@ -1,7 +1,8 @@
 {
   "name": "JoyButton",
   "displayName": "VJoyButton",
-  "description": "A button component supporting multiple variants, sizes, and states. Features icon support, loading states and can function as either a button or link element. Includes ripple effects and comprehensive styling options for different use cases from primary actions to subtle ghost buttons. **Tips:** set a \"href\" attribute to make the button a link.",
+  "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,58 +1,57 @@
 {
   "name": "JoyCheckbox",
   "displayName": "VJoyCheckbox",
-  "description": "A form checkbox component with support for standard, indeterminate, and disabled states. Features accessible labeling, focus indicators, form integration with validation feedback, and additional content slots. Supports both single selections scenarios with proper event handling and state management.",
+  "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"
@@ -80,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": "",
@@ -98,12 +97,14 @@
       ]
     },
     {
-      "name": "name",
-      "type": "string | undefined",
+      "name": "required",
+      "type": "boolean | undefined",
       "required": false,
+      "default": "false",
       "description": "",
       "possibleValues": [
-        "string"
+        "false",
+        "true"
       ]
     }
   ],
@@ -145,6 +146,11 @@
       "type": "boolean",
       "isMethod": false
     },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "isMethod": false
+    },
     {
       "name": "indeterminate",
       "type": "boolean",
@@ -165,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;
+}

package/dist/doc/VJoyCheckboxCard/metadata.json

@@ -0,0 +1,221 @@
+{
+  "name": "JoyCheckboxCard",
+  "displayName": "VJoyCheckboxCard",
+  "description": "",
+  "category": "Forms",
+  "props": [
+    {
+      "name": "subLabel",
+      "type": "string | undefined",
+      "required": false,
+      "default": "\"\"",
+      "description": "Secondary label displayed below the main label",
+      "possibleValues": [
+        "string"
+      ]
+    },
+    {
+      "name": "fitContent",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "Whether the checkbox card should fit its content",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "invalid",
+      "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).",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "label",
+      "type": "string | undefined",
+      "required": false,
+      "description": "Use it to replace the default slot",
+      "possibleValues": [
+        "string"
+      ]
+    },
+    {
+      "name": "required",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "id",
+      "type": "string | undefined",
+      "required": false,
+      "description": "",
+      "possibleValues": [
+        "string"
+      ]
+    },
+    {
+      "name": "disabled",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "Removes any interactivity if disabled",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "indeterminate",
+      "type": "boolean | 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",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "checked",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "Checked state of the component",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "value",
+      "type": "string | undefined",
+      "required": false,
+      "default": "\"on\"",
+      "description": "The value is used in multiselection context in order to build array of values.",
+      "possibleValues": [
+        "string"
+      ]
+    },
+    {
+      "name": "name",
+      "type": "string | undefined",
+      "required": false,
+      "description": "",
+      "possibleValues": [
+        "string"
+      ]
+    }
+  ],
+  "events": [
+    {
+      "name": "blur",
+      "description": "",
+      "signature": "(event: \"blur\"): void"
+    },
+    {
+      "name": "focus",
+      "description": "",
+      "signature": "(event: \"focus\"): void"
+    },
+    {
+      "name": "update:checked",
+      "description": "",
+      "signature": "(event: \"update:checked\", value: boolean): void"
+    }
+  ],
+  "slots": [
+    {
+      "name": "header-right",
+      "description": "Right aligned free slot, displayed next to the main label."
+    },
+    {
+      "name": "checkbox-card-content",
+      "description": "Free content slot, displayed below label and sublabel."
+    }
+  ],
+  "exposed": [
+    {
+      "name": "invalid",
+      "type": "boolean",
+      "isMethod": false
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "isMethod": false
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "isMethod": false
+    },
+    {
+      "name": "indeterminate",
+      "type": "boolean",
+      "isMethod": false
+    },
+    {
+      "name": "checked",
+      "type": "boolean",
+      "isMethod": false
+    },
+    {
+      "name": "value",
+      "type": "string",
+      "isMethod": false
+    },
+    {
+      "name": "subLabel",
+      "type": "string",
+      "isMethod": false
+    },
+    {
+      "name": "fitContent",
+      "type": "boolean",
+      "isMethod": false
+    },
+    {
+      "name": "label",
+      "type": "string | undefined",
+      "isMethod": false
+    },
+    {
+      "name": "id",
+      "type": "string | undefined",
+      "isMethod": false
+    },
+    {
+      "name": "name",
+      "type": "string | undefined",
+      "isMethod": false
+    },
+    {
+      "name": "onBlur",
+      "type": "(() => any) | undefined",
+      "isMethod": true
+    },
+    {
+      "name": "onFocus",
+      "type": "(() => any) | undefined",
+      "isMethod": true
+    },
+    {
+      "name": "onUpdate:checked",
+      "type": "((value: boolean) => any) | undefined",
+      "isMethod": true
+    }
+  ],
+  "hasVModel": true
+}