@maltjoy/mcp-server 0.1.1 → 0.2.0

package/README.md

@@ -4,18 +4,23 @@ MCP (Model Context Protocol) server for the Joy Design System. This server expos
 
 ## Features
 
-- 🔍 List all available Joy Vue3 components
-- 📚 Access component documentation (props, events, slots)
+- 🔍 List all 74 available Joy Vue3 components
+- 📚 Access component documentation (props, events, slots, exposed members)
+- 🎨 List 132 design tokens (colors, spacing, typography, etc.)
+- 💅 List 272 CSS utility classes
 - 🤖 AI-friendly interface through MCP protocol
+- ✅ Automatic documentation generation on build
 
 ## Installation
 
 ```bash
 cd packages/joy-mcp-server
 pnpm install
-pnpm build
+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.
+
 ## Usage
 
 ### Running the Server
@@ -35,7 +40,7 @@ pnpm dev
 
 ## Available Tools
 
-### `joy_list_components`
+### 1. `joy_list_components`
 
 Lists all available Joy Vue3 components from the @maltjoy/core-vue library.
 
@@ -54,7 +59,7 @@ Lists all available Joy Vue3 components from the @maltjoy/core-vue library.
 }
 ```
 
-### `joy_get_component_info`
+### 2. `joy_get_component_info`
 
 Retrieves detailed information about a specific Joy Vue3 component including props, events, slots, and exposed members.
 
@@ -104,6 +109,44 @@ Retrieves detailed information about a specific Joy Vue3 component including pro
 }
 ```
 
+### 3. `joy_list_design_tokens`
+
+Lists all available Joy design tokens (CSS custom properties) organized by domain.
+
+**Parameters:** None
+
+**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", "..."]
+}
+```
+
+### 4. `joy_list_css_classes`
+
+Lists all available Joy CSS utility classes organized by domain.
+
+**Parameters:** None
+
+**Returns:**
+```json
+{
+  "colors": [".joy-color-primary-100", ".joy-bgcolor-primary-100", "..."],
+  "spacing": [".joy-m-1", ".joy-p-2", "..."],
+  "typography": [".joy-font-primary-1", "..."],
+  "elevation": [".joy-core-elevation-1", "..."],
+  "radius": [".joy-core-radius-1", "..."],
+  "misc": [".joy-link", ".joy-link_white"]
+}
+```
+
 ## Configuration for Claude Desktop
 
 Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
@@ -143,17 +186,28 @@ Add this to your Cursor MCP settings:
 ```
 joy-mcp-server/
 ├── src/
-│   ├── index.ts                  # Main server entry point
-│   ├── parser.ts                 # Markdown documentation parser
+│   ├── index.ts                    # Main server entry point
+│   ├── parser.ts                   # JSON documentation parser
+│   ├── json-metadata-generator.mjs # Generates component metadata
 │   └── tools/
-│       ├── list-components.ts    # Component listing tool
-│       └── get-component-info.ts # Component info retrieval tool
+│       ├── list-components.ts      # Component listing tool
+│       ├── get-component-info.ts   # Component info retrieval tool
+│       ├── list-design-tokens.ts   # Design tokens tool
+│       └── list-css-classes.ts     # CSS classes tool
+├── dist/
+│   └── doc/
+│       ├── index.json              # Index of all components
+│       ├── design-tokens.json      # All design tokens
+│       ├── css-classes.json        # All CSS classes
+│       └── VJoy*/                  # Component directories
+│           └── metadata.json       # Component metadata
 ├── package.json
 ├── tsconfig.json
-└── README.md
+├── README.md
+└── TROUBLESHOOTING.md              # Troubleshooting guide
 ```
 
-The server reads the generated documentation from `packages/core-vue/dist/doc/joy-all-components.md` to provide up-to-date component information.
+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`.
 
 ## Development
 
@@ -163,6 +217,51 @@ To add new tools:
 2. Define the tool schema and handler
 3. Register the tool in `src/index.ts`
 
+### Available Scripts
+
+```bash
+# Build and generate documentation
+pnpm run build
+
+# Watch mode for development
+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
+
+# Run with MCP inspector for debugging
+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
+- **Server fails to start:** Check that `dist/doc/index.json` exists
+
 ## License
 
 MIT

package/dist/doc/VJoyAvatar/metadata.json

@@ -103,7 +103,7 @@
         "key",
         "user-photo",
         "link",
-        "... (200 more)"
+        "... (207 more)"
       ]
     },
     {

package/dist/doc/VJoyButton/metadata.json

@@ -92,7 +92,7 @@
       "type": "string",
       "required": false,
       "description": "Name of the icon, placed before the text",
-      "possibleValues": "TJoyIconsNames (210 values)"
+      "possibleValues": "TJoyIconsNames (217 values)"
     },
     {
       "name": "id",

package/dist/doc/VJoyCollapseItem/metadata.json

@@ -65,7 +65,7 @@
         "key",
         "user-photo",
         "link",
-        "... (200 more)"
+        "... (207 more)"
       ]
     }
   ],

package/dist/doc/VJoyHighlight/metadata.json

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

package/dist/doc/VJoyIcon/metadata.json

@@ -65,7 +65,7 @@
         "key",
         "user-photo",
         "link",
-        "... (200 more)"
+        "... (207 more)"
       ]
     },
     {

package/dist/doc/VJoyInput/metadata.json

@@ -140,7 +140,7 @@
       "type": "string",
       "required": false,
       "description": "Add a JoyIcon / joy-icon with given name on left-side.",
-      "possibleValues": "TJoyIconsNames (210 values)"
+      "possibleValues": "TJoyIconsNames (217 values)"
     },
     {
       "name": "size",

package/dist/doc/VJoyLink/metadata.json

@@ -25,7 +25,7 @@
       "type": "string",
       "required": false,
       "description": "",
-      "possibleValues": "TJoyIconsNames (210 values)"
+      "possibleValues": "TJoyIconsNames (217 values)"
     },
     {
       "name": "text",

package/dist/doc/VJoyListItem/metadata.json

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

package/dist/doc/VJoyMenu/metadata.json

@@ -130,8 +130,6 @@
                       "\"block-shield\"",
                       "\"bricks\"",
                       "\"briefcase\"",
-                      "\"building-column\"",
-                      "\"business-suitcase\"",
                       "\"calendar\"",
                       "\"camcorder\"",
                       "\"camera-device\"",
@@ -163,6 +161,7 @@
                       "\"conditions\"",
                       "\"conference\"",
                       "\"contact\"",
+                      "\"cookie\"",
                       "\"cost-plus\"",
                       "\"creditcard\"",
                       "\"cross\"",
@@ -188,11 +187,11 @@
                       "\"file\"",
                       "\"five-day\"",
                       "\"flag\"",
-                      "\"folder-arrow-down\"",
-                      "\"folder-text\"",
                       "\"freelancer-placeholder\"",
                       "\"fullscren\"",
                       "\"gasoline\"",
+                      "\"globe-hover\"",
+                      "\"globe\"",
                       "\"google\"",
                       "\"granular-report\"",
                       "\"graph-high\"",
@@ -209,6 +208,7 @@
                       "\"home\"",
                       "\"ico-list\"",
                       "\"identity-switch\"",
+                      "\"image\"",
                       "\"info-circle\"",
                       "\"instagram\"",
                       "\"insurance\"",
@@ -217,6 +217,7 @@
                       "\"legal-check\"",
                       "\"legal\"",
                       "\"linkedin\"",
+                      "\"list-file\"",
                       "\"list\"",
                       "\"location\"",
                       "\"lock\"",
@@ -232,11 +233,13 @@
                       "\"money\"",
                       "\"mood-bad\"",
                       "\"mood-good\"",
+                      "\"newspaper\"",
                       "\"open-conversation\"",
                       "\"paperclip\"",
                       "\"pen\"",
                       "\"pencil\"",
                       "\"phone\"",
+                      "\"plane-full\"",
                       "\"plus-circle\"",
                       "\"pound-circle\"",
                       "\"print\"",
@@ -265,9 +268,12 @@
                       "\"sort-asc\"",
                       "\"sort-desc\"",
                       "\"sparkle\"",
+                      "\"sparkles\"",
                       "\"star-fill\"",
                       "\"star-half\"",
+                      "\"star-message\"",
                       "\"star\"",
+                      "\"super-malter\"",
                       "\"swipe\"",
                       "\"switch\"",
                       "\"sync-reset\"",
@@ -300,6 +306,7 @@
                       "\"wallet\"",
                       "\"warning-triangle\"",
                       "\"warning\"",
+                      "\"waving-hand\"",
                       "\"web-design\"",
                       "\"wench\"",
                       "\"x\"",

package/dist/doc/VJoyMenuItem/metadata.json

@@ -23,7 +23,7 @@
       "type": "string",
       "required": false,
       "description": "",
-      "possibleValues": "TJoyIconsNames (210 values)"
+      "possibleValues": "TJoyIconsNames (217 values)"
     },
     {
       "name": "current",
@@ -50,7 +50,7 @@
       "type": "string",
       "required": false,
       "description": "",
-      "possibleValues": "TJoyIconsNames (210 values)"
+      "possibleValues": "TJoyIconsNames (217 values)"
     },
     {
       "name": "statusColor",

package/dist/doc/VJoyProductTour/metadata.json

@@ -7,7 +7,7 @@
       "type": "string",
       "required": false,
       "description": "",
-      "possibleValues": "TJoyIconsNames (210 values)"
+      "possibleValues": "TJoyIconsNames (217 values)"
     },
     {
       "name": "steps",

package/dist/doc/VJoySelectableItem/metadata.json

@@ -104,7 +104,7 @@
       "type": "string",
       "required": false,
       "description": "",
-      "possibleValues": "TJoyIconsNames (210 values)"
+      "possibleValues": "TJoyIconsNames (217 values)"
     }
   ],
   "events": [

package/dist/doc/VJoyTag/metadata.json

@@ -33,6 +33,7 @@
       "possibleValues": [
         "secondary",
         "primary",
+        "empty",
         "important",
         "inactive",
         "pending",
@@ -139,6 +140,11 @@
     }
   ],
   "events": [
+    {
+      "name": "remove",
+      "description": "",
+      "signature": "(event: \"remove\", value: IJoyTagRemoved): void"
+    },
     {
       "name": "click",
       "description": "",
@@ -148,11 +154,6 @@
       "name": "selected",
       "description": "",
       "signature": "(event: \"selected\", tag: IJoyTagSelected): void"
-    },
-    {
-      "name": "remove",
-      "description": "",
-      "signature": "(event: \"remove\", value: IJoyTagRemoved): void"
     }
   ],
   "slots": [
@@ -228,13 +229,13 @@
       "isMethod": false
     },
     {
-      "name": "onSelected",
-      "type": "((tag: IJoyTagSelected) => any) | undefined",
+      "name": "onRemove",
+      "type": "((value: IJoyTagRemoved) => any) | undefined",
       "isMethod": true
     },
     {
-      "name": "onRemove",
-      "type": "((value: IJoyTagRemoved) => any) | undefined",
+      "name": "onSelected",
+      "type": "((tag: IJoyTagSelected) => any) | undefined",
       "isMethod": true
     }
   ],

package/dist/doc/VJoyTagsInput/metadata.json

@@ -30,6 +30,7 @@
       "possibleValues": [
         "secondary",
         "primary",
+        "empty",
         "important",
         "inactive",
         "pending",