@maltjoy/mcp-server 0.4.0 → 0.5.0

package/README.md

@@ -7,7 +7,8 @@ MCP (Model Context Protocol) server for the Joy Design System. This server expos
 - 🔍 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.)
+- 🎨 Search design tokens by intent (`joy_search_tokens`) with usage docs from `$extensions.com.maltjoy.docs`
+- 🧭 Token groups and usage rules (`joy_get_token_group`, `joy_get_token_usage`)
 - 💅 List 272 CSS utility classes
 - 🤖 AI-friendly interface through MCP protocol
 - ✅ Automatic documentation generation on build
@@ -138,28 +139,49 @@ Retrieves the TypeScript types definition files associated with a specific Joy V
 }
 ```
 
-### 4. `joy_list_design_tokens`
+### 4. `joy_search_tokens`
 
+Find design tokens by intent or name. Prefer this over listing the full catalog.
 
-Lists all available Joy design tokens (CSS custom properties) organized by domain.
+**Parameters:**
+- `query` (string, required): intent (`page title`), path (`color.text.heading`), or CSS name
+- `layer` (string, optional): `semantic` (default), `primitive`, or `all`
+- `domain` (string, optional): `color`, `spacing`, `radius`, `elevation`, `zIndex`, `typography`, `motion`, `forms`, `links`
+- `includeDeprecated` (boolean, optional)
+- `limit` (number, optional): default 8, max 25
 
-**Parameters:** None
+**Returns:** compact hits (`name`, `css`, `layer`, `description`, `useFor`, `score`).
 
-**Returns:**
-```json
-{
-  "colors": ["--joy-color-primary-100", "..."],
-  "spacing": ["--joy-core-spacing-1", "..."],
-  "typography": ["--joy-font-size-primary-1", "..."],
-  "radius": ["--joy-core-radius-1", "..."],
-  "elevation": ["--joy-core-elevation-1", "..."],
-  "zIndex": ["--joy-core-z-index-modal", "..."],
-  "transitions": ["--joy-transition-fast", "..."],
-  "forms": ["--joy-form-height-medium", "..."]
-}
-```
+### 5. `joy_get_token`
+
+Full record for one token, including `com.maltjoy.docs` (`useFor`, `doNotUseFor`, `pairWith`, `replaces`).
+
+**Parameters:**
+- `name` (string, required): `color.text.heading` or `--joy-color-text-heading`
+
+### 6. `joy_get_token_group`
+
+All tokens in a group. Aliases: `text`, `background`, `border`, `spacing`, `color`, `forms`, `typography`.
+
+Semantic groups are returned first so sibling roles can be compared.
+
+### 7. `joy_get_token_usage`
+
+Decision tree plus the relevant semantic tokens.
+
+**Parameters:**
+- `topic` (string, required): `text` | `background` | `border` | `color` | `spacing`
+
+### 8. `joy_list_design_tokens`
+
+Compact list. Defaults to the **semantic** layer only. Prefer `joy_search_tokens` when you know the intent.
+
+**Parameters:**
+- `layer` (optional): `semantic` (default), `primitive`, `all`
+- `domain` (optional)
+- `includeDeprecated` (optional)
 
-### 5. `joy_list_css_classes`
+### 9. `joy_list_css_classes`
 
 Lists all available Joy CSS utility classes organized by domain.
 
@@ -219,12 +241,19 @@ joy-mcp-server/
 │   ├── index.ts                    # Main server entry point
 │   ├── parser.ts                   # JSON documentation parser
 │   ├── json-metadata-generator.mjs # Generates MCP metadata from component markdown
-│   └── tools/
+│   ├── tools/
 │       ├── list-components.ts      # Component listing tool
 │       ├── get-component-info.ts   # Component info retrieval tool
 │       ├── get-component-types.ts  # Component types retrieval tool
-│       ├── list-design-tokens.ts   # Design tokens tool
+│       ├── list-design-tokens.ts   # Compact token listing (semantic by default)
+│       ├── search-tokens.ts        # Token search by intent
+│       ├── get-token.ts            # Single token + docs
+│       ├── get-token-group.ts      # Token group bundle
+│       ├── get-token-usage.ts      # Usage rules / decision tree
 │       └── list-css-classes.ts     # CSS classes tool
+│   └── tokens/
+│       ├── build-catalog.ts        # Flatten DTCG JSON into design-tokens.json
+│       └── query.ts                # Search / get / group / usage
 ├── dist/
 │   └── doc/
 │       ├── index.json              # Index of all components

package/dist/doc/VJoyAvatar/metadata.json

@@ -106,7 +106,7 @@
         "key",
         "user-photo",
         "link",
-        "... (210 more)"
+        "... (243 more)"
       ]
     },
     {

package/dist/doc/VJoyButton/metadata.json

@@ -29,17 +29,6 @@
         "true"
       ]
     },
-    {
-      "name": "circle",
-      "type": "boolean | undefined",
-      "required": false,
-      "default": "false",
-      "description": "If you only need a button with an icon. To keep your component accessible, you can give a text as slot, it will be used as title and aria-label.\nThis property takes effect only if icon property is set",
-      "possibleValues": [
-        "false",
-        "true"
-      ]
-    },
     {
       "name": "variant",
       "type": "TJoyButtonVariants | undefined",
@@ -94,7 +83,7 @@
       "type": "string",
       "required": false,
       "description": "Name of the icon, placed before the text",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     },
     {
       "name": "id",
@@ -124,11 +113,6 @@
       "type": "boolean",
       "isMethod": false
     },
-    {
-      "name": "circle",
-      "type": "boolean",
-      "isMethod": false
-    },
     {
       "name": "variant",
       "type": "TJoyButtonVariants",

package/dist/doc/VJoyCollapseItem/metadata.json

@@ -67,7 +67,7 @@
         "key",
         "user-photo",
         "link",
-        "... (210 more)"
+        "... (243 more)"
       ]
     }
   ],

package/dist/doc/VJoyDropdownList/metadata.json

@@ -265,7 +265,7 @@
     },
     {
       "name": "dropdown-list-items",
-      "description": "Free slot in order to render any kind of component. Can be handy to use it with VJoyMultiCheckbox for instance."
+      "description": "Free slot in order to render any kind of component. Can be handy to use it with VJoyCheckboxGroup for instance."
     },
     {
       "name": "dropdown-list-item",

package/dist/doc/VJoyDropzone/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyDropzone",
   "displayName": "VJoyDropzone",
-  "description": "A file upload component with drag-and-drop functionality for handling file selection and management.\nSupports single or multiple file uploads, file validation and customizable file displays.\nFeatures visual feedback for drag states, error handling, and flexible content slots for file information and actions.\n\nThe dropzone required as `v-model` an array containing objects with at least the \"name\" property.",
+  "description": "A file upload component with drag-and-drop functionality for handling file selection and management.\nSupports single or multiple file uploads, file validation and customizable file displays.\nFeatures visual feedback for disabled, invalid, and drag states, error handling, and flexible content slots for file information and actions.\n\nThe dropzone requires a `v-model` bound to an array containing objects with at least the `name` property (or `File` instances).\n\nUse `label` to display a label above the dropzone. Use `canDelete` (default `true`) to hide the delete button on file items while keeping update available. Set `disabled` to block uploads, drag-and-drop, and file actions. Set `invalid` for parent form feedback (e.g. required empty field); it adds invalid styling but does not replace format/size validation. The exposed `invalid` ref only reflects file validation (`accept`, `maxSize`); the `invalid` prop is for external form state—both can apply the invalid appearance.\n\nSlots: `dropzone-description` for the main instruction (default text with browse link), `dropzone-subtitle` for an optional hint line (empty by default), `dropzone-legend` for helper text below the zone, `file-information` and `file-actions` for per-file content (slot prop `file`). In single-file mode, `dropzone-legend` is hidden when a format or size error is shown (`VJoyFormError` instead); in multiple mode, errors appear on each file item and the legend stays visible.",
   "category": "Forms",
   "props": [
     {
@@ -18,6 +18,15 @@
       "description": "Dropzone input name. Must be unique on the page.",
       "possibleValues": null
     },
+    {
+      "name": "label",
+      "type": "string | undefined",
+      "required": false,
+      "description": "Display a label on top of the dropzone.",
+      "possibleValues": [
+        "string"
+      ]
+    },
     {
       "name": "multiple",
       "type": "boolean | undefined",
@@ -115,6 +124,28 @@
         "false",
         "true"
       ]
+    },
+    {
+      "name": "disabled",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "Disable the dropzone.",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "name": "invalid",
+      "type": "boolean | undefined",
+      "required": false,
+      "default": "false",
+      "description": "When true, applies invalid styling (e.g. parent form required + dirty). Does not replace file format/size validation.",
+      "possibleValues": [
+        "false",
+        "true"
+      ]
     }
   ],
   "events": [],
@@ -127,6 +158,10 @@
       "name": "dropzone-description",
       "description": "Block description of the dropzone"
     },
+    {
+      "name": "dropzone-subtitle",
+      "description": "Block subtitle of the dropzone"
+    },
     {
       "name": "file-information",
       "description": "Add information under the file name"

package/dist/doc/VJoyFormError/metadata.json

@@ -26,15 +26,6 @@
         "true"
       ]
     },
-    {
-      "name": "noHtmlErrorText",
-      "type": "string | undefined",
-      "required": false,
-      "description": "Error message to display. If you need a list of errors, use the slot instead",
-      "possibleValues": [
-        "string"
-      ]
-    },
     {
       "name": "errors",
       "type": "string[] | undefined",
@@ -69,11 +60,6 @@
       "type": "boolean",
       "isMethod": false
     },
-    {
-      "name": "noHtmlErrorText",
-      "type": "string | undefined",
-      "isMethod": false
-    },
     {
       "name": "errors",
       "type": "string[] | undefined",

package/dist/doc/VJoyHighlight/metadata.json

@@ -56,7 +56,7 @@
       "type": "string",
       "required": false,
       "description": "Based on maltjoy/icons availabilities. Works in pair with displayIcon boolean prop.",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     }
   ],
   "events": [],

package/dist/doc/VJoyIcon/JoyIcon.types.ts

@@ -3,6 +3,6 @@ import {TSizes, TLevels} from '../../types';
 
 export type TJoyIconsColors = TLevels | 'neutral-50' | 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'brand-primary' | 'brand-secondary' | 'white';
 
-export type TJoyIconSizes = Extract<TSizes, 'xxsmall' | 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'>;
+export type TJoyIconSizes = Extract<TSizes, 'xxsmall' | 'xsmall' | 'small' | 'medium' | 'large'>;
 
 export type TJoyIconsNames = JoyIconsId;

package/dist/doc/VJoyIcon/metadata.json

@@ -12,7 +12,6 @@
       "description": "Use `TJoyIconSizes`",
       "possibleValues": [
         "medium",
-        "xlarge",
         "large",
         "small",
         "xsmall",
@@ -67,7 +66,7 @@
         "key",
         "user-photo",
         "link",
-        "... (210 more)"
+        "... (243 more)"
       ]
     },
     {

package/dist/doc/VJoyIconButton/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyIconButton",
   "displayName": "VJoyIconButton",
-  "description": "A dedicated icon-button component built on top of `VJoyButton`.\nUse this component instead of the deprecated `circle` prop from `VJoyButton`.",
+  "description": "A dedicated icon-button component built on top of `VJoyButton`.\nIcon-only button with an accessible label.",
   "category": "Buttons",
   "props": [
     {
@@ -61,7 +61,7 @@
       "type": "string",
       "required": true,
       "description": "Name of the icon displayed inside the button",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     },
     {
       "name": "id",

package/dist/doc/VJoyInput/JoyInput.types.ts

@@ -26,13 +26,8 @@ export interface VJoyInputProps {
     /** Add a JoyIcon / joy-icon with given name on left-side. */
     icon?: TJoyIconsNames;
     size?: TJoyInputSizes;
-    /**
-     * @deprecated Password mode is deprecated on VJoyInput.
-     * Use VJoyInputPassword for password fields and toggle behavior.
-     */
+    /** HTML input type. Use VJoyInputPassword for password fields. */
     type?: string;
-    /** Adds a legend like symbol on the right of the component. Made for number based values */
-    unit?: string;
     /** Activates the readonly mode for the input */
     readonly?: boolean;
     /** When using the clearable property, you have to specific an aria-label for accessibility. */

package/dist/doc/VJoyInput/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyInput",
   "displayName": "VJoyInput",
-  "description": "A comprehensive form input component with extensive customization and validation features.\nSupports multiple input types, icon support, clearable functionality, unit displays, and comprehensive validation states.\nFeatures auto-focus capabilities, accessibility compliance, and seamless integration with form validation systems.",
+  "description": "A comprehensive form input component with extensive customization and validation features.\nSupports multiple input types, icon support, clearable functionality, and comprehensive validation states.\nFeatures auto-focus capabilities, accessibility compliance, and seamless integration with form validation systems.",
   "category": "Forms",
   "props": [
     {
@@ -144,7 +144,7 @@
       "type": "string",
       "required": false,
       "description": "Add a JoyIcon / joy-icon with given name on left-side.",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     },
     {
       "name": "size",
@@ -163,18 +163,9 @@
       "type": "string | undefined",
       "required": false,
       "default": "\"text\"",
-      "description": "",
+      "description": "HTML input type. Use VJoyInputPassword for password fields.",
       "possibleValues": null
     },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "required": false,
-      "description": "Adds a legend like symbol on the right of the component. Made for number based values",
-      "possibleValues": [
-        "string"
-      ]
-    },
     {
       "name": "readonly",
       "type": "boolean | undefined",
@@ -311,9 +302,9 @@
       "isMethod": true
     },
     {
-      "name": "unit",
-      "type": "string | undefined",
-      "isMethod": false
+      "name": "focus",
+      "type": "() => void",
+      "isMethod": true
     }
   ],
   "hasVModel": true

package/dist/doc/VJoyInputNumber/metadata.json

@@ -29,7 +29,7 @@
       "type": "string | undefined",
       "required": false,
       "default": "\"number\"",
-      "description": "",
+      "description": "HTML input type. Use VJoyInputPassword for password fields.",
       "possibleValues": null
     },
     {
@@ -59,7 +59,7 @@
       "type": "string",
       "required": false,
       "description": "Add a JoyIcon / joy-icon with given name on left-side.",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     },
     {
       "name": "id",
@@ -85,7 +85,7 @@
       "name": "name",
       "type": "string | undefined",
       "required": false,
-      "default": "\"joy-input-password\"",
+      "default": "\"joy-input-number\"",
       "description": "",
       "possibleValues": [
         "string"
@@ -155,16 +155,6 @@
         "Partial<Record<\"number\" | \"trim\" | \"lazy\", boolean>>"
       ]
     },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "required": false,
-      "default": "\"\\u20AC\"",
-      "description": "Adds a legend like symbol on the right of the component. Made for number based values",
-      "possibleValues": [
-        "string"
-      ]
-    },
     {
       "name": "readonly",
       "type": "boolean | undefined",
@@ -175,6 +165,16 @@
         "false",
         "true"
       ]
+    },
+    {
+      "name": "unit",
+      "type": "string | undefined",
+      "required": false,
+      "default": "\"\\u20AC\"",
+      "description": "Unit label displayed on the right side of the number input.",
+      "possibleValues": [
+        "string"
+      ]
     }
   ],
   "events": [
@@ -184,7 +184,12 @@
       "signature": "(event: \"update:modelValue\", value: string): void"
     }
   ],
-  "slots": [],
+  "slots": [
+    {
+      "name": "default",
+      "description": ""
+    }
+  ],
   "exposed": [
     {
       "name": "invalid",
@@ -232,13 +237,13 @@
       "isMethod": false
     },
     {
-      "name": "unit",
-      "type": "string",
+      "name": "readonly",
+      "type": "boolean",
       "isMethod": false
     },
     {
-      "name": "readonly",
-      "type": "boolean",
+      "name": "unit",
+      "type": "string",
       "isMethod": false
     },
     {

package/dist/doc/VJoyInputPassword/metadata.json

@@ -51,7 +51,7 @@
       "type": "string",
       "required": false,
       "description": "Add a JoyIcon / joy-icon with given name on left-side.",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     },
     {
       "name": "id",
@@ -146,15 +146,6 @@
       "possibleValues": [
         "Partial<Record<\"number\" | \"trim\" | \"lazy\", boolean>>"
       ]
-    },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "required": false,
-      "description": "Adds a legend like symbol on the right of the component. Made for number based values",
-      "possibleValues": [
-        "string"
-      ]
     }
   ],
   "events": [
@@ -246,11 +237,6 @@
       "type": "((value: string) => any) | undefined",
       "isMethod": true
     },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "isMethod": false
-    },
     {
       "name": "focus",
       "type": "() => void",

package/dist/doc/VJoyLink/metadata.json

@@ -27,7 +27,7 @@
       "type": "string",
       "required": false,
       "description": "",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     },
     {
       "name": "href",

package/dist/doc/VJoyListItem/metadata.json

@@ -9,7 +9,7 @@
       "type": "string",
       "required": false,
       "description": "",
-      "possibleValues": "TJoyIconsNames (220 values)"
+      "possibleValues": "TJoyIconsNames (253 values)"
     }
   ],
   "events": [

package/dist/doc/VJoyMenu/metadata.json

@@ -115,6 +115,8 @@
                       "\"accomodation\"",
                       "\"add-circle\"",
                       "\"add\"",
+                      "\"analytics-hover\"",
+                      "\"analytics\"",
                       "\"android\"",
                       "\"apple\"",
                       "\"archive-explicit\"",
@@ -167,9 +169,12 @@
                       "\"cookie\"",
                       "\"cost-plus\"",
                       "\"creditcard\"",
+                      "\"cross-circle\"",
                       "\"cross\"",
                       "\"crown\"",
                       "\"customer-support\"",
+                      "\"dashboard-hover\"",
+                      "\"dashboard\"",
                       "\"dataviz\"",
                       "\"dollar-circle\"",
                       "\"dots-vertical\"",
@@ -188,9 +193,13 @@
                       "\"file-check\"",
                       "\"file-pdf\"",
                       "\"file\"",
+                      "\"find-free-hover\"",
+                      "\"find-free\"",
                       "\"five-day\"",
                       "\"flag\"",
                       "\"freelancer-placeholder\"",
+                      "\"freelancer-pool-hover\"",
+                      "\"freelancer-pool\"",
                       "\"fullscren\"",
                       "\"gasoline\"",
                       "\"globe-hover\"",
@@ -208,15 +217,23 @@
                       "\"heart-people\"",
                       "\"heart\"",
                       "\"heartbroken\"",
+                      "\"help-center-hover\"",
+                      "\"help-center\"",
                       "\"home\"",
                       "\"ico-list\"",
                       "\"identity-switch\"",
                       "\"image\"",
+                      "\"inbox-hover\"",
+                      "\"inbox\"",
                       "\"info-circle\"",
                       "\"instagram\"",
                       "\"insurance\"",
+                      "\"invite-freelancer-hover\"",
+                      "\"invite-freelancer\"",
                       "\"invite\"",
+                      "\"invoice-hover\"",
                       "\"invoice-sent\"",
+                      "\"invoice\"",
                       "\"legal-check\"",
                       "\"legal\"",
                       "\"linkedin\"",
@@ -226,6 +243,8 @@
                       "\"lock\"",
                       "\"logo-brew\"",
                       "\"man-woman\"",
+                      "\"manage-project-hover\"",
+                      "\"manage-project\"",
                       "\"marketing\"",
                       "\"meal\"",
                       "\"medal-thumbsup\"",
@@ -237,6 +256,8 @@
                       "\"mood-bad\"",
                       "\"mood-good\"",
                       "\"newspaper\"",
+                      "\"notification-center-hover\"",
+                      "\"notification-center\"",
                       "\"open-conversation\"",
                       "\"paperclip\"",
                       "\"pen\"",
@@ -259,6 +280,8 @@
                       "\"receipt\"",
                       "\"refresh\"",
                       "\"remove-circle\"",
+                      "\"resource-center-hover\"",
+                      "\"resource-center\"",
                       "\"robot\"",
                       "\"rocket\"",
                       "\"school\"",
@@ -266,7 +289,10 @@
                       "\"search\"",
                       "\"security\"",
                       "\"sendit\"",
+                      "\"settings-hover\"",
                       "\"settings-outline\"",
+                      "\"settings\"",
+                      "\"side-panel\"",
                       "\"single-report\"",
                       "\"social-share\"",
                       "\"social\"",
@@ -279,6 +305,8 @@
                       "\"star-message\"",
                       "\"star\"",
                       "\"super-malter\"",
+                      "\"swap-company-hover\"",
+                      "\"swap-company\"",
                       "\"swipe\"",
                       "\"switch\"",
                       "\"sync-reset\"",
@@ -286,7 +314,9 @@
                       "\"tab\"",
                       "\"taxi\"",
                       "\"three-dots\"",
+                      "\"thumbdown-fill\"",
                       "\"thumbdown\"",
+                      "\"thumbup-fill\"",
                       "\"thumbup\"",
                       "\"thunder\"",
                       "\"traffic-signs\"",
@@ -298,6 +328,9 @@
                       "\"user-add\"",
                       "\"user-check\"",
                       "\"user-edit\"",
+                      "\"user-hover\"",
+                      "\"user-lighter-deprecated-hover\"",
+                      "\"user-lighter-deprecated\"",
                       "\"user-lighter\"",
                       "\"user-remove\"",
                       "\"user\"",