ai-react-animations 1.2.0 → 1.2.1

package/MCP-GUIDE.md

@@ -0,0 +1,390 @@
+# MCP Server Setup Guide
+
+This guide explains how to set up and use the AI React Animations MCP (Model Context Protocol) server with Claude Code or other AI assistants.
+
+---
+
+## Table of Contents
+
+1. [What is MCP?](#what-is-mcp)
+2. [Prerequisites](#prerequisites)
+3. [Installation](#installation)
+4. [Configuration](#configuration)
+5. [Available Tools](#available-tools)
+6. [Usage Examples](#usage-examples)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## What is MCP?
+
+MCP (Model Context Protocol) is a standard that allows AI assistants like Claude to interact with external tools and services. With the AI React Animations MCP server, you can ask Claude to:
+
+- List all available animation components
+- Get detailed information about any component
+- Add components to your project with proper source code
+- Get installation commands for dependencies
+
+---
+
+## Prerequisites
+
+Before setting up the MCP server, make sure you have:
+
+- **Node.js** version 18 or higher
+- **npm** (comes with Node.js)
+- **Claude Code** or another MCP-compatible AI assistant
+
+To check your Node.js version:
+
+```bash
+node --version
+```
+
+---
+
+## Installation
+
+### Step 1: Install the package
+
+Open your terminal and run:
+
+```bash
+npm install ai-react-animations
+```
+
+This installs the animation components AND the MCP server.
+
+### Step 2: Install tsx (TypeScript executor)
+
+The MCP server is written in TypeScript. Install tsx to run it:
+
+```bash
+npm install -g tsx
+```
+
+Or install it locally in your project:
+
+```bash
+npm install tsx --save-dev
+```
+
+---
+
+## Configuration
+
+### Step 1: Find your MCP configuration file
+
+The MCP configuration file is named `.mcp.json` and is located in:
+
+- **macOS/Linux**: `~/.mcp.json` (your home directory)
+- **Windows**: `C:\Users\YourUsername\.mcp.json`
+
+If the file doesn't exist, create it.
+
+### Step 2: Add the MCP server configuration
+
+Open `.mcp.json` in a text editor and add:
+
+```json
+{
+  "mcpServers": {
+    "ai-react-animations": {
+      "command": "npx",
+      "args": ["tsx", "node_modules/ai-react-animations/mcp/server.ts"]
+    }
+  }
+}
+```
+
+### Step 3: If you already have other MCP servers
+
+Add the `ai-react-animations` entry to your existing `mcpServers` object:
+
+```json
+{
+  "mcpServers": {
+    "your-existing-server": {
+      "command": "...",
+      "args": ["..."]
+    },
+    "ai-react-animations": {
+      "command": "npx",
+      "args": ["tsx", "node_modules/ai-react-animations/mcp/server.ts"]
+    }
+  }
+}
+```
+
+### Step 4: Restart Claude Code
+
+After saving the configuration:
+
+1. Close Claude Code completely
+2. Reopen Claude Code
+3. The MCP server will now be available
+
+---
+
+## Available Tools
+
+The MCP server provides 4 tools:
+
+### 1. `list_components`
+
+Lists all available animation components.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `category` | string | No | Filter by category: `all`, `loading`, `processing`, `creative`, `auth` |
+
+**Example response:**
+```json
+{
+  "total": 7,
+  "categories": ["all", "loading", "processing", "creative", "auth"],
+  "components": [
+    {
+      "name": "LoadingDots",
+      "id": "loading-dots",
+      "category": "loading",
+      "description": "Simple, elegant bouncing dots animation."
+    }
+  ]
+}
+```
+
+---
+
+### 2. `get_component`
+
+Gets detailed information about a specific component, including source code.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Component name or ID (e.g., `LoadingDots`, `loading-dots`) |
+
+**Example response:**
+```json
+{
+  "name": "LoadingDots",
+  "id": "loading-dots",
+  "description": "Simple, elegant bouncing dots animation.",
+  "category": "loading",
+  "dependencies": ["framer-motion"],
+  "props": [...],
+  "usage": "...",
+  "source": "// Full component source code"
+}
+```
+
+---
+
+### 3. `add_component`
+
+Gets instructions and source code to add a component to your project.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Component name or ID |
+| `directory` | string | No | Target directory (default: `./components`) |
+
+**Example response:**
+```json
+{
+  "success": true,
+  "component": "LoadingDots",
+  "filePath": "./components/LoadingDots.tsx",
+  "source": "// Component source code",
+  "dependencies": ["framer-motion"],
+  "installCommand": "npm install framer-motion",
+  "instructions": "1. Create the file..."
+}
+```
+
+---
+
+### 4. `get_install_command`
+
+Gets the npm install command for a component's dependencies.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Component name or ID |
+
+**Example response:**
+```
+npm install framer-motion
+```
+
+---
+
+## Usage Examples
+
+Once the MCP server is configured, you can use natural language with Claude:
+
+### Example 1: List all components
+
+**You say:**
+> "What animation components are available?"
+
+**Claude will:**
+1. Call the `list_components` tool
+2. Show you a list of all 7 components with descriptions
+
+---
+
+### Example 2: Get component details
+
+**You say:**
+> "Show me details about the PulseCircle component"
+
+**Claude will:**
+1. Call `get_component` with `name: "PulseCircle"`
+2. Show you the props, usage example, and description
+
+---
+
+### Example 3: Add a component to your project
+
+**You say:**
+> "Add the LoadingDots component to my project in the components folder"
+
+**Claude will:**
+1. Call `add_component` with `name: "LoadingDots"` and `directory: "./components"`
+2. Create the file `./components/LoadingDots.tsx` with the full source code
+3. Tell you to run `npm install framer-motion`
+
+---
+
+### Example 4: Filter by category
+
+**You say:**
+> "Show me all loading animation components"
+
+**Claude will:**
+1. Call `list_components` with `category: "loading"`
+2. Show you only the loading-related components
+
+---
+
+### Example 5: Add multiple components
+
+**You say:**
+> "Add LoadingDots and PulseCircle to my components folder"
+
+**Claude will:**
+1. Call `add_component` twice
+2. Create both component files
+3. Give you the combined install command
+
+---
+
+## Troubleshooting
+
+### Problem: "MCP server not found"
+
+**Solution:**
+1. Make sure you installed the package: `npm install ai-react-animations`
+2. Check that `.mcp.json` is in the correct location
+3. Restart Claude Code
+
+---
+
+### Problem: "tsx: command not found"
+
+**Solution:**
+Install tsx globally:
+```bash
+npm install -g tsx
+```
+
+---
+
+### Problem: "Cannot find module"
+
+**Solution:**
+Make sure you're in a directory where `node_modules/ai-react-animations` exists:
+```bash
+ls node_modules/ai-react-animations
+```
+
+If not, install the package:
+```bash
+npm install ai-react-animations
+```
+
+---
+
+### Problem: "Permission denied"
+
+**Solution (macOS/Linux):**
+```bash
+chmod +x node_modules/ai-react-animations/mcp/server.ts
+```
+
+---
+
+### Problem: MCP server doesn't respond
+
+**Solution:**
+1. Test the server manually:
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx tsx node_modules/ai-react-animations/mcp/server.ts
+```
+
+2. You should see a JSON response with the tools list
+
+---
+
+## Component Categories
+
+| Category | Components | Use Case |
+|----------|-----------|----------|
+| **loading** | LoadingDots | Simple loading indicators |
+| **processing** | PulseCircle, DataProcessing | Progress and data flow |
+| **creative** | AiCreating, AiCreating2, CodeTyping | AI-themed animations |
+| **auth** | FloatingLogin | Authentication UI |
+
+---
+
+## Need Help?
+
+- **GitHub Issues**: [github.com/johnbekele/ai-react-animations/issues](https://github.com/johnbekele/ai-react-animations/issues)
+- **npm Package**: [npmjs.com/package/ai-react-animations](https://www.npmjs.com/package/ai-react-animations)
+
+---
+
+## Quick Reference Card
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  AI React Animations - MCP Quick Reference              │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  SETUP:                                                 │
+│  1. npm install ai-react-animations                     │
+│  2. Add to ~/.mcp.json                                  │
+│  3. Restart Claude Code                                 │
+│                                                         │
+│  ASK CLAUDE:                                            │
+│  • "List animation components"                          │
+│  • "Add LoadingDots to my project"                      │
+│  • "Show me PulseCircle details"                        │
+│  • "What dependencies does FloatingLogin need?"         │
+│                                                         │
+│  COMPONENTS:                                            │
+│  • LoadingDots     - Bouncing dots                      │
+│  • PulseCircle     - Progress circle                    │
+│  • CodeTyping      - Code typing effect                 │
+│  • DataProcessing  - Pipeline visualization             │
+│  • AiCreating      - Robot animation                    │
+│  • AiCreating2     - Brain animation                    │
+│  • FloatingLogin   - Auth form                          │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```

package/README.md

@@ -1,84 +1,188 @@
-# ai-react-animations
+# AI React Animations
 
-Beautiful AI loading animation components for React/Next.js. Shows AI processing states with a friendly robot character.
+Beautiful AI loading and animation components for React/Next.js. Production-ready components for AI interfaces with MCP (Model Context Protocol) server support.
+
+[![npm version](https://badge.fury.io/js/ai-react-animations.svg)](https://www.npmjs.com/package/ai-react-animations)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 7 production-ready animation components
+- TypeScript support
+- Framer Motion animations
+- MCP Server for AI assistants (Claude, etc.)
+- Customizable colors and sizes
+- Dark/Light mode support
+- Responsive design
 
 ## Installation
 
 ```bash
-npm install ai-react-animations
+npm install ai-react-animations framer-motion lucide-react
 ```
 
-## Usage
+## Available Components
+
+| Component | Category | Description |
+|-----------|----------|-------------|
+| `LoadingDots` | Loading | Simple bouncing dots animation |
+| `PulseCircle` | Processing | Circular progress with pulse rings |
+| `CodeTyping` | Creative | Code typing effect with syntax colors |
+| `DataProcessing` | Processing | Data pipeline visualization |
+| `AiCreating` | Creative | Multi-stage AI robot animation |
+| `AiCreating2` | Creative | AI brain with rotating rings |
+| `FloatingLogin` | Auth | Floating login form with OAuth |
+
+## Quick Start
 
 ```tsx
-import AiCreating from 'ai-react-animations';
-import 'ai-react-animations/styles.css';
+import { LoadingDots } from 'ai-react-animations';
 
 function MyComponent() {
-  const [isLoading, setIsLoading] = useState(false);
-
-  return (
-    <AiCreating
-      isLoading={isLoading}
-      size="md"
-      onComplete={() => console.log('Done!')}
-    />
-  );
+  return <LoadingDots size="md" color="#6366F1" />;
 }
 ```
 
-## Props
+## Component Examples
+
+### LoadingDots
 
+```tsx
+import { LoadingDots } from 'ai-react-animations';
+
+<LoadingDots size="md" color="#6366F1" />
+```
+
+**Props:**
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `isLoading` | `boolean` | required | Controls the animation state |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `'md'` | Size of the animation |
-| `onComplete` | `() => void` | - | Callback when animation completes |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the dots |
+| `color` | `string` | `'#6366F1'` | Color of the dots |
 
-## Sizes
+### PulseCircle
 
-- `xs` - 100px height (for buttons)
-- `sm` - 160px height (for small cards)
-- `md` - 240px height (default)
-- `lg` - 340px height (for large displays)
-- `full` - 100% height (fills container)
+```tsx
+import { PulseCircle } from 'ai-react-animations';
 
-## Animation Stages
+const [isActive, setIsActive] = useState(false);
 
-The component shows 4 stages when `isLoading={true}`:
+<PulseCircle
+  isActive={isActive}
+  onComplete={() => setIsActive(false)}
+/>
+```
 
-1. **Reading** - Robot reads the request
-2. **Processing** - Gears spin, sparkles appear
-3. **Delivering** - Result card slides in
-4. **Complete** - Success state with green checkmark
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isActive` | `boolean` | required | Activates the animation |
+| `progress` | `number` | - | External progress (0-100) |
+| `onComplete` | `() => void` | - | Callback at 100% |
 
-## Features
+### AiCreating2
 
-- Pure CSS animations (no external dependencies)
-- Responsive design
-- Accessibility support (prefers-reduced-motion)
-- TypeScript support
-- Works with React 17+
+```tsx
+import { AiCreating2 } from 'ai-react-animations';
+
+<AiCreating2
+  isLoading={isLoading}
+  message="Creating your plan..."
+  primaryColor="#6366F1"
+  backgroundColor="#0f172a"
+  contained={true}
+  onComplete={() => setIsLoading(false)}
+/>
+```
 
-## Example with API Call
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isLoading` | `boolean` | required | Controls visibility |
+| `message` | `string` | `'AI is creating...'` | Main message |
+| `subMessage` | `string` | - | Secondary text |
+| `primaryColor` | `string` | `'#6366F1'` | Accent color |
+| `backgroundColor` | `string` | `'#0f172a'` | Background color |
+| `textColor` | `string` | `'#ffffff'` | Text color |
+| `contained` | `boolean` | `false` | Render in container vs overlay |
+| `onComplete` | `() => void` | - | Completion callback |
+
+### FloatingLogin
 
 ```tsx
-const [loading, setLoading] = useState(false);
+import { FloatingLogin } from 'ai-react-animations';
+
+<FloatingLogin
+  mode="dark"
+  primaryColor="#6366F1"
+  floatIntensity={5}
+  onLogin={(data) => console.log(data)}
+  onGoogleLogin={() => signInWithGoogle()}
+  onAppleLogin={() => signInWithApple()}
+/>
+```
 
-async function handleSubmit() {
-  setLoading(true);
-  await fetch('/api/generate');
-  setLoading(false); // Triggers completion animation
-}
+**Props:**
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `mode` | `'light' \| 'dark'` | `'light'` | Theme mode |
+| `primaryColor` | `string` | `'#6366F1'` | Accent color |
+| `floatingEnabled` | `boolean` | `true` | Enable floating animation |
+| `floatIntensity` | `number` | `5` | Float intensity (1-10) |
+| `onLogin` | `(data) => void` | - | Login callback |
+| `onGoogleLogin` | `() => void` | - | Google OAuth callback |
+| `onAppleLogin` | `() => void` | - | Apple Sign-In callback |
+
+---
+
+## MCP Server (For AI Assistants)
+
+This package includes an MCP (Model Context Protocol) server that allows AI assistants like Claude to help users add animation components to their projects.
+
+### Quick Setup
+
+Add to your `.mcp.json` file:
 
-return (
-  <div>
-    <button onClick={handleSubmit}>Generate</button>
-    <AiCreating isLoading={loading} />
-  </div>
-);
+```json
+{
+  "mcpServers": {
+    "ai-react-animations": {
+      "command": "npx",
+      "args": ["tsx", "node_modules/ai-react-animations/mcp/server.ts"]
+    }
+  }
+}
 ```
 
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List all available components |
+| `get_component` | Get component details and source code |
+| `add_component` | Get instructions to add a component |
+| `get_install_command` | Get npm install command |
+
+### Usage with Claude
+
+Once configured, you can ask Claude:
+- "List all animation components"
+- "Add the LoadingDots component to my project"
+- "Show me the PulseCircle component details"
+- "What dependencies do I need for FloatingLogin?"
+
+For detailed MCP setup instructions, see [MCP-GUIDE.md](./MCP-GUIDE.md).
+
+---
+
 ## License
 
 MIT
+
+## Author
+
+johnbekele
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/ai-react-animations)
+- [GitHub repository](https://github.com/johnbekele/ai-react-animations)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-react-animations",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Beautiful AI loading animation components for React/Next.js with MCP server support.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -21,6 +21,7 @@
     "dist",
     "mcp",
     "mcp-config.json",
+    "MCP-GUIDE.md",
     "README.md",
     "LICENSE"
   ],