@rpironato/mcp-reactbits-server/README.md

Enhanced MCP server for accessing ReactBits component library with GitHub API integration, advanced search, and comprehensive metadata - 107 components with real code access from DavidHDev/react-bits repository

# ReactBits MCP Server v2.0.0

🚀 **Enhanced Model Context Protocol (MCP) server for the ReactBits component library**

## 🎯 Overview

This MCP server provides comprehensive programmatic access to the ReactBits component library, allowing AI systems to browse, search, and retrieve React components with their source code. Version 2.0.0 includes major improvements with real code retrieval, advanced search capabilities, and comprehensive metadata support.

## ✨ Features

### 🔍 **Complete Component Access**
- **107 ReactBits Components**: Full access to all components with real code
- **4 Variants Per Component**: JS, JS+Tailwind, TS, TS+Tailwind (428 total implementations)
- **Real Code Retrieval**: Actual component source code + intelligent fallback templates
- **Smart Search**: Strategic keyword-based search system

### 📊 **Advanced Functionality**
- **Comprehensive Metadata**: Dependencies, keywords, usage statistics
- **Documentation Generation**: Automatic component documentation with examples
- **CLI Integration**: jsrepo commands + multi-package-manager support
- **Advanced Analytics**: Component statistics, dependency analysis, trends

### 🛠️ **Developer Tools**
- **Installation Commands**: npm, yarn, pnpm, bun support
- **Component Categories**: TextAnimations, Animations, Components, Backgrounds
- **Usage Examples**: TypeScript and JavaScript examples
- **Accessibility Guidelines**: Built-in accessibility documentation

## 📦 Installation

```bash
npm install -g @rpironato/mcp-reactbits-server
```

## 🔧 Usage

### With Claude Desktop

Add to your Claude Desktop MCP configuration (`mcp.json`):

```json
{
  "servers": {
    "ReactBits": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@rpironato/mcp-reactbits-server@latest"
      ]
    }
  }
}
```

### Direct Usage

```bash
npx @rpironato/mcp-reactbits-server@latest
```

## 🛠️ Available Tools

### 📋 `list_components`
List all ReactBits components with comprehensive metadata.

**Parameters:**
- `category` (optional): Filter by category
- `limit` (optional): Maximum components (1-107, default: 107)
- `offset` (optional): Pagination offset

**Returns:** Complete component information with descriptions, keywords, dependencies, and versions.

### 💻 `get_component_code`
Retrieve real component source code with metadata.

**Parameters:**
- `name` (required): Component name
- `version` (required): js | js-tailwind | ts | ts-tailwind

**Returns:** Real code + metadata, CLI commands, dependencies, examples

### 🔍 `search_components`
Intelligent search with strategic keywords.

**Parameters:**
- `search` (required): Search term (button, menu, card, animation, etc.)
- `category` (optional): Filter by category
- `limit` (optional): Maximum results (default: 10)

**Returns:** Matching components with relevance ranking.

### 📚 `list_categories`
List categories with component counts and details.

**Parameters:**
- `includeComponents` (optional): Include component lists (default: false)

**Returns:** All 4 categories with counts and descriptions.

### 📦 `install_component`
Generate installation commands with dependencies.

**Parameters:**
- `name` (required): Component name
- `version` (required): Component version
- `package_manager` (optional): npm | yarn | pnpm | bun

**Returns:** Complete installation guide with commands and usage examples.

### 📊 `get_reactbits_stats`
Comprehensive library statistics and analytics.

**Parameters:**
- `includeReport` (optional): Include markdown report (default: false)
- `includeDependencies` (optional): Include dependency stats (default: true)
- `includeKeywords` (optional): Include keyword analysis (default: true)

**Returns:** Complete library analytics, dependency usage, popular keywords.

### 🔍 `advanced_search`
Advanced search with multiple filters.

**Parameters:**
- `query` (optional): Search term
- `category` (optional): Filter by category
- `dependencies` (optional): Filter by dependencies
- `keywords` (optional): Filter by keywords
- `sortBy` (optional): name | category | relevance
- `limit` (optional): Maximum results (default: 10)

**Returns:** Filtered and sorted component results.

### 📖 `get_component_docs`
Comprehensive component documentation.

**Parameters:**
- `name` (required): Component name or URL slug
- `includeRelated` (optional): Include related components (default: true)

**Returns:** Complete documentation with examples, props, styling, accessibility guidelines.

## 📊 ReactBits Library Stats

- **Total Components:** 107
- **Total Implementations:** 428 (4 variants each)
- **Categories:** 4
- **Dependencies Supported:** React, Framer Motion, Three.js, GSAP, Tailwind CSS
- **Package:** @rpironato/react-components

### 📂 Categories

| Category | Count | Description |
|----------|-------|-------------|
| **TextAnimations** | 23 | Animated text effects and typography |
| **Animations** | 23 | General animation components and effects |
| **Components** | 34 | UI components, widgets, and interfaces |
| **Backgrounds** | 27 | Background effects, patterns, and visuals |

## 🚀 What's New in v2.0.0

### ✅ **Major Fixes**
- **Fixed Search**: `search_components` now returns results for common terms like "button"
- **Real Code**: `get_component_code` returns actual component source code
- **Complete Database**: All 107 ReactBits components with real metadata

### 🆕 **New Features**
- **Advanced Search**: Multi-filter search with dependencies, keywords, categories
- **Statistics & Analytics**: Comprehensive library insights and trends
- **Component Documentation**: Auto-generated docs with examples and guidelines
- **Enhanced CLI**: jsrepo integration with multi-package-manager support

### 🔧 **Technical Improvements**
- **TypeScript**: Complete type safety and validation
- **Performance**: Optimized search algorithms and caching
- **Error Handling**: Robust error handling with fallback systems
- **Code Quality**: 100% documented with inline comments

## 🛠️ Development

```bash
# Clone repository
git clone https://github.com/rpironato/mcp-reactbits-server.git
cd mcp-reactbits-server

# Install dependencies
npm install

# Build
npm run build

# Run development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint
```

## 📋 Requirements

- **Node.js:** >= 18.0.0
- **npm:** >= 8.0.0
- **TypeScript:** >= 5.0.0

## 🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

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 [LICENSE](LICENSE) file for details.

## 🔗 Related Projects

- [ReactBits](https://reactbits.dev) - The official component library
- [@rpironato/react-components](https://npmjs.com/@rpironato/react-components) - Component distribution package
- [Model Context Protocol](https://modelcontextprotocol.io) - Protocol specification

## 📞 Support

- **Issues:** [GitHub Issues](https://github.com/rpironato/mcp-reactbits-server/issues)
- **Email:** contact@rpironato.dev
- **Documentation:** [ReactBits Docs](https://reactbits.dev/docs)

---

**Made with ❤️ by RPironato | ReactBits v2.0.0 | MCP Compatible**