@maltjoy/mcp-server

MCP (Model Context Protocol) server for the Joy Design System. This server exposes information about Vue3 components from the @maltjoy/core-vue library, making it easy to discover and use components through AI assistants.

Features

• 🔍 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

cd packages/joy-mcp-server
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.

Usage

Running the Server

pnpm start

The server runs on stdio and is ready to receive MCP protocol messages.

Development

# Watch mode for development
pnpm dev

Available Tools

1. joy_list_components

Lists all available Joy Vue3 components from the @maltjoy/core-vue library.

Parameters: None

Returns:

{
  "components": [
    "VJoyAdminBanner",
    "VJoyAvailability",
    "VJoyAvatar",
    "..."
  ],
  "count": 74
}

2. joy_get_component_info

Retrieves detailed information about a specific Joy Vue3 component including props, events, slots, and exposed members.

Parameters:

• componentName (string, required): The exact name of the component (e.g., "VJoyButton", "VJoyAvatar")

Returns:

{
  "name": "VJoyButton",
  "props": [
    {
      "name": "size",
      "type": "TJoyButtonSizes | undefined",
      "required": false,
      "default": "\"medium\"",
      "description": "Button or Link size",
      "possibleValues": "medium, large, small, xsmall, xxsmall"
    }
  ],
  "events": [
    {
      "name": "click",
      "description": "Emitted when the button is clicked"
    }
  ],
  "slots": [
    {
      "name": "default",
      "description": "Default slot for button text"
    }
  ],
  "exposedMembers": [
    {
      "name": "size",
      "type": "TJoyButtonSizes",
      "kind": "Property"
    }
  ]
}

Error Response:

{
  "error": "Component \"VJoyNonExistent\" not found. Use joy_list_components to get a list of available components."
}

3. joy_list_design_tokens

Lists all available Joy design tokens (CSS custom properties) organized by domain.

Parameters: None

Returns:

{
  "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:

{
  "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):

{
  "mcpServers": {
    "joy-design-system": {
      "command": "node",
      "args": [
        "/absolute/path/to/design-system/packages/joy-mcp-server/dist/index.js"
      ]
    }
  }
}

Configuration for Cursor

Add this to your Cursor MCP settings:

{
  "mcpServers": {
    "joy-design-system": {
      "command": "node",
      "args": [
        "/absolute/path/to/design-system/packages/joy-mcp-server/dist/index.js"
      ]
    }
  }
}

Architecture

joy-mcp-server/
├── src/
│   ├── 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-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
└── TROUBLESHOOTING.md              # Troubleshooting guide

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

To add new tools:

1. Create a new file in src/tools/
2. Define the tool schema and handler
3. Register the tool in src/index.ts

Available Scripts

# 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

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