@moontra/moonui-mcp-server/README.md

Model Context Protocol server for MoonUI component library - AI-native component access

# MoonUI MCP Server 🌙🤖

Model Context Protocol (MCP) server for MoonUI component library. Enables AI assistants like Claude to seamlessly interact with MoonUI components, featuring smart environment detection, CDN support, and Pro component security.

[![npm version](https://badge.fury.io/js/%40moontra%2Fmoonui-mcp-server.svg)](https://badge.fury.io/js/%40moontra%2Fmoonui-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)

## What's New in v1.0.5

### 📚 Complete Documentation Update
- Updated README files for all packages with comprehensive documentation
- Added CDN usage examples for both MoonUI (v2.3.3) and MoonUI-Pro (v2.24.4)
- Enhanced performance optimization guides
- Complete component listings and feature descriptions

### 🔗 Latest Package Integration
- Full integration with MoonUI v2.3.3 (742KB CDN bundle)
- Complete MoonUI-Pro v2.24.4 support (2.86MB CDN bundle)
- Updated component registry with latest features
- Enhanced Pro component documentation and examples

### 🎯 Smart Environment Detection
- Automatic detection of artifact vs. NPM environments
- Context-aware import recommendations (CDN vs NPM)
- Smart code generation based on execution environment
- Optimized for Claude Desktop artifacts and playgrounds

### 📦 CDN Support Integration
- Full CDN compatibility for browser/artifact environments  
- Auto-switch between NPM imports and script tags
- JSDelivr and unpkg.com CDN links included
- React dependency management for CDN usage

### 🔧 Enhanced Code Generation
- Environment-aware code examples
- Automatic script vs import selection
- Context detection for artifact environments
- Mixed environment support with fallbacks

## Previous Updates (v1.0.3-v1.0.4)

### 🔒 Pro Component Security Layer
- Enhanced protection against reverse engineering attempts
- Rate limiting for Pro component access
- Suspicious pattern detection (rapid-fire, systematic scanning, prop mining)
- Minimal information exposure for unlicensed Pro component requests

### 🎨 Theming Helper Tool
- Comprehensive theming and customization guidance
- CSS variable configuration
- Dark mode implementation
- Custom color palettes
- Animation and transition support

### 🔄 Semi-automated Registry Updates
- Automatic component detection from source code
- TypeScript AST parsing for prop extraction
- Change detection and review system
- Script: `npm run update-registry`

## Features

### 🔧 Tools
- **suggest_component** - Find the best MoonUI component for any use case
- **fix_imports** - Automatically fix missing or incorrect imports
- **generate_code** - Generate component code for specific scenarios
- **validate_usage** - Validate component usage and suggest fixes
- **theming_helper** - Get theming and customization guidance
- **detect_environment** - Auto-detect execution environment and provide optimal setup

### 📚 Resources
- Component metadata and documentation
- Usage examples and best practices
- Props documentation and type definitions
- Dependency information

### 📝 Prompts
- Form wizard generation
- Dashboard layout creation
- Component composition templates

## Installation

### For Claude Desktop

1. Install the MCP server:
```bash
npm install -g @moontra/moonui-mcp-server
```

2. Configure Claude Desktop by adding to your config:

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

```json
{
  "mcpServers": {
    "moonui": {
      "command": "npx",
      "args": ["@moontra/moonui-mcp-server"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "MOONUI_LICENSE": "your-license-key"
      }
    }
  }
}
```

3. Restart Claude Desktop

## Usage

Once configured, Claude will automatically have access to MoonUI components. You can:

### Find Components
```
"I need a component for displaying data in a table"
```
Claude will use the `suggest_component` tool to find DataTable.

### Fix Imports
```
"Fix the imports in this code: <Button>Click</Button>"
```
Claude will add the missing import statement.

### Generate Code
```
"Create a login form with validation"
```
Claude will generate complete code with all necessary imports.

### Validate Usage
```
"Check if this component usage is correct"
```
Claude will validate props, variants, and accessibility.

## Environment Variables

- `PROJECT_PATH` - Path to your project directory
- `MOONUI_PRO_LICENSE` - Your MoonUI Pro license key (optional)
- `DEBUG` - Enable debug logging (set to `moonui:*`)
- `MOONUI_ANALYTICS` - Enable usage analytics (default: true)
- `MOONUI_LEARNING` - Enable learning from usage (default: true)

## 📦 Supported Packages

### MoonUI v2.3.3 (Base Library)
- **NPM**: `@moontra/moonui@2.3.3`
- **CDN**: `https://cdn.jsdelivr.net/npm/@moontra/moonui@2.3.3/dist/index.global.js`
- **Bundle Size**: 742KB (IIFE)
- **Components**: 50+ free components
- **License**: MIT

### MoonUI-Pro v2.24.4 (Premium Library)
- **NPM**: `@moontra/moonui-pro@2.24.4`
- **CDN**: `https://cdn.jsdelivr.net/npm/@moontra/moonui-pro@2.24.4/dist/index.global.js`
- **Bundle Size**: 2.86MB (IIFE)
- **Components**: 50+ premium components
- **License**: Commercial (requires license key)

## 🔄 Environment Detection Examples

### NPM Environment
```jsx
import { Button, Card } from '@moontra/moonui';
import { DataTable, Charts } from '@moontra/moonui-pro';

function App() {
  return (
    <Card>
      <Button>Click me</Button>
      <DataTable data={data} columns={columns} />
    </Card>
  );
}
```

### CDN/Artifact Environment
```html
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@moontra/moonui@2.3.3/dist/index.global.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@moontra/moonui-pro@2.24.4/dist/index.global.js"></script>

<script>
  const { Button, Card } = window.MoonUI;
  const { DataTable, Charts } = window.MoonUIPro;
  
  function App() {
    return React.createElement(Card, null,
      React.createElement(Button, null, 'Click me'),
      React.createElement(DataTable, { data, columns })
    );
  }
</script>
```

## Development

### Running Locally

1. Clone the repository:
```bash
git clone https://github.com/moonui/mcp-server.git
cd packages/mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

4. Run in development mode:
```bash
npm run dev
```

### Testing

Run the test suite:
```bash
npm test
```

### Project Structure

```
packages/mcp-server/
├── src/
│   ├── index.ts           # Entry point
│   ├── server.ts          # MCP server implementation
│   ├── types.ts           # TypeScript definitions
│   ├── metadata/          # Component registry
│   ├── tools/             # MCP tools
│   ├── resources/         # MCP resources
│   └── prompts/           # MCP prompts
├── tests/                 # Test files
├── package.json
└── README.md
```

## API Reference

### Tools

#### suggest_component
Find the best component for a use case:
```json
{
  "description": "I need a form input",
  "context": "login form",
  "preferPro": false
}
```

#### fix_imports
Fix missing imports in code:
```json
{
  "code": "<Button>Click</Button>",
  "filePath": "app.tsx"
}
```

#### generate_code
Generate component code:
```json
{
  "component": "DataTable",
  "useCase": "user list",
  "variant": "pro",
  "typescript": true
}
```

#### validate_usage
Validate component usage:
```json
{
  "code": "<Button variant='invalid'>Test</Button>",
  "strict": true
}
```

### Resources

- `moonui://components` - List all components
- `moonui://components/free` - List free components
- `moonui://components/pro` - List pro components
- `moonui://component/{id}` - Component details
- `moonui://component/{id}/examples` - Usage examples
- `moonui://component/{id}/props` - Props documentation

### Prompts

- `form_wizard` - Multi-step form creation
- `dashboard_layout` - Dashboard layout generation

## Troubleshooting

### Server not starting
- Check that Node.js >= 18 is installed
- Verify the MCP server is installed globally
- Check Claude Desktop configuration

### Components not found
- Ensure PROJECT_PATH is set correctly
- Verify MoonUI is installed in your project
- Check debug logs with `DEBUG=moonui:*`

### Pro components not accessible
- Verify MOONUI_PRO_LICENSE is set
- Check license validity
- Ensure you have a valid Pro subscription

### CDN bundles not loading
- Check network connectivity to JSDelivr/unpkg
- Verify version numbers in CDN URLs
- Try alternative CDN (JSDelivr vs unpkg)
- For new versions, allow time for CDN sync

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

MIT © MoonUI Team

## Support

- Documentation: [moonui.dev/docs/mcp](https://moonui.dev/docs/mcp)
- Issues: [GitHub Issues](https://github.com/moonui/mcp-server/issues)
- Discord: [Join our community](https://discord.gg/moonui)