Blend MCP Server

An MCP (Model Context Protocol) server for the Blend design system that provides tools for generating React components, documentation, and UI patterns.

Features

• List Components: Get a list of all available Blend components
• Component Props: Retrieve detailed prop information for any component
• Generate Components: Create React code with proper props and children
• Scaffold Patterns: Generate common UI patterns like dashboards and data tables
• Documentation: Generate comprehensive component documentation

Installation

Using npx (Recommended for testing)

You can run the MCP server directly from GitHub without installing:

# Clone and run in one command
npx degit design-juspay/cloved/packages/mcp blend-mcp-temp && cd blend-mcp-temp && npm install && node index.js

Or use node directly with the raw file from GitHub:

curl -s https://raw.githubusercontent.com/design-juspay/cloved/main/packages/mcp/index.js | node -

Local Installation

1. Clone the repository:

git clone https://github.com/design-juspay/cloved.git
cd cloved/packages/mcp

2. Install dependencies:

npm install

3. Run the server:

node index.js

Configuration

Environment Variables

• BLEND_LIBRARY_PATH: Path to the Blend components directory (auto-detected by default)
• BLEND_LIBRARY_PACKAGE_NAME: Package name for imports (default: "blend-v1")
• META_PATH: Path to component metadata files (auto-detected by default)

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "blend": {
            "command": "node",
            "args": ["/path/to/cloved/packages/mcp/index.js"],
            "env": {
                "BLEND_LIBRARY_PACKAGE_NAME": "blend-v1"
            }
        }
    }
}

Or if you have blend-v1 installed as a dependency:

{
    "mcpServers": {
        "blend": {
            "command": "npx",
            "args": [
                "degit",
                "design-juspay/cloved/packages/mcp",
                "blend-mcp-temp",
                "&&",
                "cd",
                "blend-mcp-temp",
                "&&",
                "npm",
                "install",
                "&&",
                "node",
                "index.js"
            ],
            "env": {
                "BLEND_LIBRARY_PACKAGE_NAME": "blend-v1",
                "BLEND_LIBRARY_PATH": "./node_modules/blend-v1/dist/components"
            }
        }
    }
}

Note: When using blend-v1 as an npm package, the components are typically located in ./node_modules/blend-v1/dist/components rather than lib/components. The MCP server will automatically try both paths, but you can set the correct one explicitly using the BLEND_LIBRARY_PATH environment variable.

VS Code with Continue/Cline

Add to your MCP settings:

{
    "mcpServers": {
        "blend": {
            "command": "node",
            "args": ["/path/to/cloved/packages/mcp/index.js"],
            "env": {
                "BLEND_LIBRARY_PACKAGE_NAME": "blend-v1"
            }
        }
    }
}

Available Tools

1. list_blend_components

Lists all available components in the Blend design system.

Usage:

Tool: list_blend_components
Arguments: {}

Returns: Array of component names

2. get_blend_component_props

Retrieves detailed prop information for a specific component.

Usage:

Tool: get_blend_component_props
Arguments: {
  "componentName": "Button"
}

Returns: Object with component description and prop details

3. generate_blend_component

Generates React code for a component with specified props.

Usage:

Tool: generate_blend_component
Arguments: {
  "componentName": "Button",
  "props": {
    "text": "Click me",
    "variant": "primary"
  },
  "includeImports": true
}

Returns: React component code with imports

4. scaffold_dashboard_section

Generates common UI patterns for dashboards.

Available patterns:

• fintech_kpi_summary_with_chart: KPI cards with charts
• transaction_list_with_controls: Data table with filters

Usage:

Tool: scaffold_dashboard_section
Arguments: {
  "sectionType": "fintech_kpi_summary_with_chart",
  "options": {
    "title": "Financial Overview",
    "kpis": [
      {
        "title": "Revenue",
        "value": "$1.2M",
        "changeValue": 15,
        "changeDirection": "positive"
      }
    ]
  }
}

5. generate_component_documentation

Generates markdown documentation for a component.

Usage:

Tool: generate_component_documentation
Arguments: {
  "componentName": "Button"
}

Returns: Markdown documentation with props, features, and examples

Examples

Example 1: Generate a Button

// Request
{
  "tool": "generate_blend_component",
  "arguments": {
    "componentName": "Button",
    "props": {
      "text": "Submit",
      "variant": "primary",
      "size": "medium"
    }
  }
}

// Response
import { Button } from "blend-v1";

<Button text="Submit" variant="primary" size="medium" />

Example 2: Create a Dashboard Section

// Request
{
  "tool": "scaffold_dashboard_section",
  "arguments": {
    "sectionType": "transaction_list_with_controls",
    "options": {
      "title": "Recent Transactions",
      "columns": [
        { "header": "ID", "field": "id" },
        { "header": "Amount", "field": "amount" },
        { "header": "Status", "field": "status" }
      ]
    }
  }
}

Development

Running Locally

1. Make sure you have Node.js 18+ installed
2. Clone the repository
3. Install dependencies: npm install
4. Run the server: node index.js

Testing with MCP Inspector

npm run inspector

This will open the MCP Inspector to test the server's tools interactively.

Troubleshooting

"Could not find Blend library" Error

If you see this error, the server cannot locate the Blend components. Set the path explicitly:

export BLEND_LIBRARY_PATH="/path/to/blend/lib/components"
node /path/to/cloved/packages/mcp/index.js

Meta Features Not Available

If component documentation features aren't working, ensure the meta files are available or set:

export META_PATH="/path/to/meta/files"

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Support

For issues and questions:

• Open an issue on GitHub
• Check existing issues for solutions
• Ensure you're using the latest version

Changelog

v1.1.0 - 🎉 COMPLETE SOLUTION: ALL 8 CRITICAL ISSUES RESOLVED

• 🎯 100% SUCCESS: All 8 major external usability issues completely fixed
• Smart Component Generation: Auto-generates AccordionItem children for Accordion components
• Perfect Prop Formatting: String props get quotes, enum values get proper enum syntax
• Auto-Enum Imports: Automatically imports required enum types (ButtonType, AlertVariant, etc.)
• Component Relationships: Documents and enforces sub-component relationships
• Prop Validation: Validates required prop combinations with helpful warnings
• Enhanced Metadata: Component relationship mapping and dependency validation
• 36 Components: Exact match with main.ts exports - 100% import success rate

Specific Fixes:

1. ✅ "Tags" → "Tag": Fixed component name mapping
2. ✅ String Quotes: text="Click Me" (proper quotes)
3. ✅ Enum Formatting: buttonType={ButtonType.PRIMARY} (proper enum syntax)
4. ✅ Props Accuracy: 14 props + 3 enums for Button (100% accurate)
5. ✅ Accordion Structure: Auto-generates AccordionItem children
6. ✅ Sub-component Relationships: 4/4 complex components mapped
7. ✅ Prop Combinations: Validation for 5 components with dependencies
8. ✅ Individual Inputs: TextInput, DropdownInput, etc. (no generic "Inputs")

New Features:

• Component Relationships System: Maps parent-child component requirements
• Smart Container Generation: Auto-generates children for complex components
• Enhanced Prop Validation: Warns about missing required props and combinations
• Enum Auto-Import: Automatically includes enum types in imports
• Comprehensive Testing: Full test suite validates all fixes

v1.0.8

• 🚨 CRITICAL FIX: Only lists components that are actually exported from blend-v1
• Export validation: Dynamically reads main.ts to filter only exported components
• Prevents import errors: Eliminates components like Directory, Dropdown, GradientBlur, Primitives, Select that aren't exported
• Improved accuracy: Reduced from 35 to 29 components - all guaranteed to work in external projects
• External usability: 100% of listed components now work with import { Component } from "blend-v1"

v1.0.7

• 🎯 PERFECT SOLUTION: ThemeProvider is now automatically included in ALL tools by default
• Simplified approach: Removed separate generate_app_setup tool - all existing tools now include ThemeProvider automatically
• Universal wrapping: Every generated component is automatically wrapped with ThemeProvider
• Zero manual setup: Users never need to worry about ThemeProvider configuration
• Consistent behavior: All tools (generate_blend_component, scaffold_dashboard_section) work the same way

v1.0.6

• 🎯 SOLVED THEMEPROVIDER ISSUES: Automatic ThemeProvider detection and wrapping
• New Tool: generate_app_setup - Creates complete React apps with proper ThemeProvider setup
• Auto-wrapping: Components requiring ThemeProvider are automatically wrapped when generated
• Smart imports: ThemeProvider is automatically imported when needed
• Setup instructions: Generated code includes comprehensive setup instructions
• Zero configuration: Works out of the box in any repository without manual ThemeProvider setup

v1.0.5

• Enhanced TypeScript parser: Now supports .tsx types files and multiple naming patterns
• Improved component coverage: Fixed parsing for Charts (13 props), Tags (9 props), and other components
• Better pattern matching: Handles ChartsProps, ComponentV2Props, and other naming variations
• Increased success rate: Now successfully parses 97.1% of components (33/34, excluding Primitives collection)
• Added test suite: Comprehensive testing script to validate parser against all components

v1.0.4

• MAJOR IMPROVEMENT: Added TypeScript parser for accurate component prop extraction
• Fixed prop value formatting: String props now correctly include quotes (e.g., title="Total Revenue" instead of title={Total Revenue})
• Enhanced component information: Now includes ThemeProvider requirements, enums, and nested types
• Improved accuracy: Props are now extracted directly from TypeScript source files when available
• Better error handling: Graceful fallback from TypeScript parsing to embedded metadata
• Added context awareness: Components that require ThemeProvider are now properly documented

v1.0.3

• Removed Text component from the available components list
• Updated scaffolding functions to use HTML h2 elements instead of Text component
• Fixed modal example to use standard HTML p element instead of Text component

v1.0.2

• Fixed path resolution for npm package installations (./node_modules/blend-v1/dist/components)
• Enhanced fallback logic to gracefully handle library path errors
• Improved error handling for better reliability across different repository setups
• Updated documentation with correct path configurations

v1.0.1

• Bug fixes and stability improvements

v1.0.0

• Initial release with core MCP tools
• Support for component generation and documentation
• Dashboard scaffolding patterns
• Auto-detection of Blend library paths