# Anime.js MCP Server

A Model Context Protocol (MCP) server providing AI assistants with comprehensive access to [Anime.js](https://animejs.com/) animation library components, APIs, examples, and documentation.

## Features

- 🎬 **Complete Anime.js API Coverage**: Access to all major Anime.js functions and properties
- 📚 **Rich Documentation**: Built-in guides for getting started, easing functions, performance optimization
- 🎯 **Interactive Examples**: Ready-to-use code examples for common animation patterns
- 🔍 **Smart Search**: Find relevant examples and documentation quickly
- ⚡ **Performance Tips**: Best practices for smooth animations
- 🎨 **Animation Patterns**: Transform, timeline, stagger, SVG, morphing, and more

## Installation

### Via npm
```bash
npm install -g @animejs/anime-js-mcp-server
```

### Via npx (recommended)
```bash
npx @animejs/anime-js-mcp-server
```

## Usage

### Basic Usage
```bash
# Start the server
npx @animejs/anime-js-mcp-server

# With GitHub API token for enhanced features
npx @animejs/anime-js-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_anime_component**: Get detailed info about specific Anime.js APIs
- **list_anime_components**: Browse all available components by category

### Examples and Tutorials  
- **get_anime_example**: Get complete code examples for animation patterns
- **search_anime_examples**: Search through examples by keywords
- **get_anime_docs**: Access comprehensive documentation topics

## Supported Animation Types

### Core Animations
- **Basic Transforms**: translate, rotate, scale, skew
- **CSS Properties**: opacity, colors, dimensions, positioning
- **Timeline Sequences**: Complex multi-step animations
- **Stagger Effects**: Grid-based and directional delays

### Advanced Features
- **SVG Path Animations**: Path following and morphing
- **Text Animations**: Letter-by-letter effects
- **Elastic & Physics**: Spring and bounce effects
- **Performance Optimization**: Hardware acceleration tips

## Example Usage with Claude

```
# Get started with Anime.js
"How do I create a basic slide-in animation?"

# Explore specific features
"Show me timeline examples for sequential animations"

# Search for patterns
"Find examples with stagger effects"

# Get performance tips
"How do I optimize animations for mobile?"
```

## API Reference

### Tools Available

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_anime_component` | Get component documentation | `componentName` (required) |
| `list_anime_components` | List all components | `category` (optional) |
| `get_anime_example` | Get code example | `exampleType` (required) |
| `search_anime_examples` | Search examples | `query` (required) |
| `get_anime_docs` | Get documentation | `topic` (required) |

### Categories

- **core**: Main animation functions (`anime`, `timeline`)
- **utilities**: Helper functions (`stagger`, `random`, `set`)
- **svg**: SVG-specific animations (`path`, morphing)

### Example Types

- `basic-transform` - Simple transform animations
- `timeline-sequence` - Sequential timeline animations
- `stagger-grid` - Grid-based stagger effects
- `svg-path` - SVG path animations
- `text-animation` - Text effects
- `elastic-bounce` - Physics-based easing
- `morphing` - CSS property morphing
- `keyframes` - Complex keyframe animations

### Documentation Topics

- `getting-started` - Installation and basic usage
- `animation-controls` - Play, pause, seek controls
- `easing` - All easing functions and custom curves
- `performance` - Optimization best practices
- `timeline` - Timeline and sequencing
- `stagger` - Stagger effects and patterns

## Configuration

### Claude Desktop Integration

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "anime-js": {
      "command": "npx",
      "args": ["@animejs/anime-js-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Development Setup

```bash
# Clone and install
git clone https://github.com/juliangarnier/anime-js-mcp-server.git
cd anime-js-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

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

## Related Projects

- [Anime.js](https://animejs.com/) - The animation library this server supports
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol standard
- [Claude Desktop](https://claude.ai/) - AI assistant that can use this server

## Support

- 📖 [Documentation](https://animejs.com/documentation/)
- 🐛 [Issue Tracker](https://github.com/juliangarnier/anime-js-mcp-server/issues)
- 💬 [Discussions](https://github.com/juliangarnier/anime-js-mcp-server/discussions)

---

Built with ❤️ for the animation community