# NeoPOP Web MCP Server

A Model Context Protocol (MCP) server providing AI assistants with comprehensive access to [NeoPOP Web](https://github.com/CRED-CLUB/neopop-web) components library, APIs, examples, and documentation.

## Features

- 🎨 **Complete NeoPOP Component Coverage**: Access to all NeoPOP Web React components
- 📚 **Rich Documentation**: Built-in guides for getting started, customization, and theming
- 🎯 **Interactive Examples**: Ready-to-use code examples for common patterns
- 🔍 **Smart Search**: Find relevant examples and documentation quickly
- ⚡ **Performance Tips**: Best practices for NeoPOP components
- 💅 **Design System**: Access to primitives, colors, typography, and elevation effects

## What is NeoPOP?

NeoPOP is CRED's design system library for building modern web applications with a distinctive, futuristic visual style. It features:

- Elevated components with signature 3D effects
- Dark and light color modes
- Fluid, highly optimized animations
- Mobile-first design approach
- Comprehensive React component library

## Installation

### Via npm
```bash
npm install -g @cred/neopop-web-mcp-server
```

### Via npx (recommended)
```bash
npx @cred/neopop-web-mcp-server
```

## Usage

### Basic Usage
```bash
# Start the server
npx @cred/neopop-web-mcp-server

# With GitHub API token for enhanced features
npx @cred/neopop-web-mcp-server --github-api-key YOUR_GITHUB_TOKEN
```

### Environment Variables
```bash
export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here
export LOG_LEVEL=info  # debug, info, warn, error
```

## MCP Tools

### Component Information
- **get_neopop_component**: Get detailed info about specific NeoPOP components
- **list_neopop_components**: Browse all available components by category

### Examples and Tutorials
- **get_neopop_example**: Get complete code examples for NeoPOP patterns
- **search_neopop_examples**: Search through examples by keywords
- **get_neopop_docs**: Access comprehensive documentation topics

## Available Components

### Interactive Components
- Button - Elevated, flat, and link variants
- Back, Chevron, Pointer, Cross - Navigation and icon components

### Form Components
- InputField - With label and error handling
- Checkbox, Radio, Toggle - Custom styled controls
- SearchBar - Search input
- Dropdown - Selection component
- Slider - Range input

### Layout Components
- ElevatedCard - Cards with 3D elevation effects
- Header - Page headers
- Row, Column - Flex containers
- PageContainer - Page wrapper
- HorizontalSpacer, VerticalSpacer - Spacing components
- HorizontalDivider - Divider lines

### Display Components
- Typography - Consistent text styling
- Tag - Labels and badges
- ScoreMeter - Animated score display

### Overlay Components
- BottomSheet - Mobile-first modal
- Toast - Notification system

## Example Usage with Claude

```
# Get started with NeoPOP
"How do I create an elevated button with custom colors?"

# Explore specific features
"Show me form examples with validation"

# Search for patterns
"Find examples with bottom sheets"

# Get documentation
"Explain NeoPOP theming and customization"
```

## API Reference

### Tools Available

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_neopop_component` | Get component documentation | `componentName` (required) |
| `list_neopop_components` | List all components | `category` (optional) |
| `get_neopop_example` | Get code example | `exampleType` (required) |
| `search_neopop_examples` | Search examples | `query` (required) |
| `get_neopop_docs` | Get documentation | `topic` (required) |

### Categories

- **Interactive**: Buttons, navigation elements
- **Forms**: Input fields, checkboxes, radios, toggles
- **Layout**: Cards, containers, spacers
- **Display**: Typography, tags, score meters
- **Overlays**: Bottom sheets, toasts
- **Typography**: Text components

### Example Types

- `button-elevated` - Elevated button examples
- `form-complete` - Complete form with validation
- `card-layout` - Card-based layouts
- `bottom-sheet-modal` - Bottom sheet modals
- `toast-notifications` - Toast notifications

### Documentation Topics

- `getting-started` - Installation and basic usage
- `customization` - Customizing components
- `theming` - Creating themes
- `animations` - Animation system
- `primitives` - Design tokens and primitives

## Configuration

### Claude Desktop Integration

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "neopop-web": {
      "command": "npx",
      "args": ["@cred/neopop-web-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Development Setup

```bash
# Clone and install
git clone https://github.com/CRED-CLUB/neopop-web-mcp-server.git
cd neopop-web-mcp-server
npm install

# Build and run
npm run build
npm start

# Development mode
npm run dev
```

## Architecture

The server follows MCP best practices with:

- **Request Validation**: Zod schema validation for all inputs
- **Error Handling**: Comprehensive error handling and logging
- **Caching**: Intelligent caching for performance
- **Circuit Breakers**: Resilient external API calls
- **Logging**: Configurable logging levels

## Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## License

Apache-2.0 License - see [LICENSE](LICENSE) file for details.

## Related Projects

- [NeoPOP Web](https://github.com/CRED-CLUB/neopop-web) - The React components library
- [NeoPOP Playground](https://playground.cred.club) - Interactive documentation
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol standard
- [Claude Desktop](https://claude.ai/) - AI assistant that can use this server

## Support

- 📖 [NeoPOP Documentation](https://playground.cred.club)
- 🐛 [Issue Tracker](https://github.com/CRED-CLUB/neopop-web-mcp-server/issues)
- 💬 [Discussions](https://github.com/CRED-CLUB/neopop-web-mcp-server/discussions)

---

Built with ❤️ for the design community by CRED