reactbits-mcp-server/README.md

MCP Server for React Bits - Access 99+ React components with animations, backgrounds, and UI elements

# React Bits MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with access to 99+ React components from React Bits, including animations, backgrounds, and UI elements.

## Features

- **99+ React Components**: Access to a comprehensive library of React components
- **Multiple Categories**: Components organized into Animations, Backgrounds, Components, and TextAnimations
- **Source Code Access**: Get the complete source code for any component
- **Demo Examples**: Access demo code showing how to use each component
- **Component Metadata**: Retrieve detailed information about component props and dependencies
- **Search Functionality**: Find components by name or description
- **TypeScript Support**: Full TypeScript definitions included

## Installation

### Global Installation (Recommended)

```bash
npm install -g reactbits-mcp-server
```

### Local Installation

```bash
npm install reactbits-mcp-server
```

## Usage

### Command Line

```bash
# Show version
npx reactbits-mcp-server --version

# Show help
npx reactbits-mcp-server --help

# Start the MCP server
npx reactbits-mcp-server
```

### MCP Tools Available

#### `list_components`
Get all available React Bits components, optionally filtered by category.

```json
{
  "category": "TextAnimations" // Optional: Animations, Backgrounds, Components, TextAnimations
}
```

#### `get_component`
Get the source code for a specific React Bits component.

```json
{
  "componentName": "AnimatedList",
  "category": "Animations" // Optional but recommended for faster lookup
}
```

#### `get_component_demo`
Get demo code showing how to use a specific component.

```json
{
  "componentName": "BlobCursor",
  "category": "Backgrounds"
}
```

#### `get_component_metadata`
Get metadata about a component including dependencies and props.

```json
{
  "componentName": "TextCursor",
  "category": "TextAnimations"
}
```

#### `search_components`
Search for components by name or description.

```json
{
  "query": "animation",
  "category": "Animations" // Optional
}
```

## Component Categories

### Animations
Interactive animation components for enhanced user experience.

### Backgrounds
Dynamic background effects and visual elements.

### Components
General-purpose UI components for common use cases.

### TextAnimations
Specialized text animation and typography effects.

## Example Components

- **AnimatedList**: Smooth list animations with stagger effects
- **BlobCursor**: Interactive blob cursor that follows mouse movement
- **TextCursor**: Typewriter-style text animation
- **SplitText**: Character-by-character text animations
- **VariableProximity**: Text that responds to cursor proximity
- **TrueFocus**: Focus-based text highlighting effects

## Requirements

- Node.js >= 18.0.0
- React >= 16.8.0 (for hooks support)
- TypeScript >= 4.0.0 (optional but recommended)

## Dependencies

The components use modern React patterns and may require:

- **Framer Motion**: For advanced animations
- **Tailwind CSS**: For styling (most components)
- **React Hooks**: useState, useEffect, useRef, etc.

## Integration with AI Assistants

This MCP server is designed to work with AI assistants that support the Model Context Protocol. When integrated, AI assistants can:

1. Browse available React components
2. Retrieve component source code
3. Get usage examples and demos
4. Search for components by functionality
5. Access component metadata and dependencies

## Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/duocreativelabs/react-bits-mcp-server.git

# Install dependencies
npm install

# Start development server
npm start
```

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- GitHub Issues: https://github.com/duocreativelabs/react-bits-mcp-server/issues
- Documentation: https://github.com/duocreativelabs/react-bits-mcp-server#readme

## Version History

- **1.2.6**: Fixed path resolution issues on Windows
- **1.2.5**: Corrected version display and package.json references
- **1.2.4**: Fixed base path calculation for component discovery
- **1.2.3**: Added src/ directory to published package
- **1.0.0**: Initial release with basic MCP functionality