@maltjoy/mcp-server 0.3.2 → 0.5.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 maltcommunity / apps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -9,6 +9,7 @@ MCP (Model Context Protocol) server for the Joy Design System. This server expos
 - 🏷️ Retrieve TypeScript types definitions for component props (variants, sizes, etc.)
 - 🎨 List 132 design tokens (colors, spacing, typography, etc.)
 - 💅 List 272 CSS utility classes
+- 📖 Search the locally extracted Zeroheight design-system documentation
 - 🤖 AI-friendly interface through MCP protocol
 - ✅ Automatic documentation generation on build
 
@@ -177,6 +178,23 @@ Lists all available Joy CSS utility classes organized by domain.
 }
 ```
 
+### 6. `joy_list_documentation_pages`
+
+Lists documentation pages extracted from Zeroheight. Results can be filtered with an optional `category` or `componentName`.
+
+### 7. `joy_get_documentation_page`
+
+Returns the Markdown content and extraction metadata for one page. Provide the stable `page` id or slug from `joy_list_documentation_pages`; use the optional `section` argument to retrieve a single section.
+
+### 8. `joy_search_documentation`
+
+Searches extracted Markdown and returns contextual excerpts.
+
+**Parameters:**
+- `query` (string, required): Case-insensitive text to search for.
+- `componentName` (string, optional): Restrict results to a Joy component.
+- `limit` (number, optional): Maximum number of results, default `10`.
+
 ## Configuration for Claude Desktop
 
 Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
@@ -218,7 +236,9 @@ 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
+│   ├── zeroheight-parser.ts         # Extracted Zeroheight documentation parser
+│   ├── zeroheight-metadata-generator.mjs
 │   └── tools/
 │       ├── list-components.ts      # Component listing tool
 │       ├── get-component-info.ts   # Component info retrieval tool
@@ -233,12 +253,32 @@ joy-mcp-server/
 │       └── VJoy*/                  # Component directories
 │           ├── metadata.json       # Component metadata
 │           └── *.types.ts          # Component TypeScript types
+│       └── zeroheight/             # Extracted design-system Markdown and index
 ├── package.json
 ├── tsconfig.json
 └── 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;
+}