# Rive Docs MCP - Rive Documentation Model Context Protocol Server

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Rive Documentation MCP Server - Access Rive's animation documentation, runtime guides, editor features, and tutorials through Model Context Protocol. Search animations, state machines, runtime implementations, and editor capabilities across web, mobile, and game platforms. Get instant access to React, Flutter, Unity integration guides, and complete API references directly in Claude, Cursor, or any MCP-compatible AI assistant.

## ✨ Features

- 🔍 **Smart Search**: Intelligent search across Rive documentation for animations, runtimes, editor features, and guides
- 📚 **Complete Documentation Access**: Full access to Rive's documentation for all runtime platforms
- 🎮 **Multi-Platform Support**: Web, React, Flutter, iOS, Android, Unity, Unreal Engine, and more
- 🎨 **Editor Features**: Browse animation tools, constraints, state machines, bones, and timeline features
- 📋 **Runtime Guides**: Comprehensive implementation guides for all supported platforms
- 🎯 **Tutorial Access**: Find and access tutorials by topic, difficulty, or runtime platform
- 🔧 **API References**: Complete API documentation for runtime-specific implementations
- ⚡ **High Performance**: Optimized with caching and concurrent request handling
- 🌐 **Feature Support Matrix**: Check feature compatibility across different runtime platforms
- 🚀 **Developer Friendly**: Built for AI-powered development workflows

## 🚀 Quick Start

### Claude Desktop (Recommended)

Add this to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "rive-docs": {
      "command": "node",
      "args": ["path/to/rive-docs-mcp/dist/index.js"]
    }
  }
}
```

### Local Development

1. Clone and build the project:
```bash
git clone <repository-url>
cd rive-docs-mcp
npm install
npm run build
```

2. Test the server:
```bash
npm start
```

## 📦 Installation

### Claude Code

```bash
# Add as MCP server
claude mcp add rive-docs -- node path/to/rive-docs-mcp/dist/index.js
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "rive-docs": {
      "command": "node",
      "args": ["path/to/rive-docs-mcp/dist/index.js"]
    }
  }
}
```

### Other MCP Clients

The server works with any MCP-compatible client. Use the command:
```bash
node path/to/rive-docs-mcp/dist/index.js
```

## 🛠️ Available Tools

### 🔍 `search_rive_docs`
Search Rive documentation across all categories.

**Parameters:**
- `query` (required): Search terms (e.g., "React runtime", "state machine events")
- `category`: Filter by category (`all`, `runtimes`, `editor`, `game-runtimes`, `tutorials`)
- `runtime`: Filter by specific runtime platform
- `limit`: Max results (default: 10, max: 50)

**Example:**
```
search_rive_docs query="React animation setup" category="runtimes" limit=5
```

### 📖 `get_rive_doc_content`
Get detailed content from a specific Rive documentation page.

**Parameters:**
- `url` (required): Full Rive documentation URL
- `includeCode`: Include code examples (default: true)
- `includeLinks`: Include related links (default: false)
- `maxLength`: Max content length (default: 10000)

**Example:**
```
get_rive_doc_content url="https://rive.app/docs/runtimes/react/getting-started"
```

### 🏃 `list_runtimes`
List all available Rive runtime platforms.

**Parameters:**
- `platform`: Filter by platform type (`all`, `web`, `mobile`, `game`)
- `status`: Filter by status (`all`, `stable`, `beta`, `community`)
- `includeDetails`: Include detailed information (default: true)

### 📋 `get_runtime_guide`
Get comprehensive implementation guide for a specific runtime.

**Parameters:**
- `runtime` (required): Runtime platform (`web`, `react`, `flutter`, `unity`, etc.)
- `section`: Specific section (`getting-started`, `setup`, `api-reference`)
- `includeExamples`: Include code examples (default: true)

### 🎨 `list_editor_features`
Browse Rive editor features and capabilities.

**Parameters:**
- `category`: Feature category (`all`, `animation`, `constraints`, `state-machines`)
- `includeDetails`: Include detailed descriptions (default: true)

### 🎓 `get_tutorials`
Find tutorials by topic, difficulty, or runtime.

**Parameters:**
- `topic`: Tutorial topic or search term
- `difficulty`: Filter by difficulty (`all`, `beginner`, `intermediate`, `advanced`)
- `runtime`: Filter by runtime platform
- `limit`: Max tutorials to return (default: 10)

### ✅ `check_feature_support`
Check feature support across runtime platforms.

**Parameters:**
- `feature` (required): Feature to check (e.g., "state machines", "bones")
- `runtime`: Specific runtime to check (optional)

### 📚 `get_api_reference`
Get API reference for a specific runtime.

**Parameters:**
- `runtime` (required): Runtime platform
- `className`: Specific class/component name (optional)
- `includeExamples`: Include usage examples (default: true)

## 💡 Usage Examples

### Search for React Integration
```
search_rive_docs query="React component setup" category="runtimes" runtime="react"
```

### Get Flutter Getting Started Guide
```
get_runtime_guide runtime="flutter" section="getting-started"
```

### Find State Machine Tutorials
```
get_tutorials topic="state machine" difficulty="beginner"
```

### Check Unity Feature Support
```
check_feature_support feature="timeline events" runtime="unity"
```

### Browse Animation Features
```
list_editor_features category="animation"
```

## 🎯 Supported Runtimes

### App Runtimes
- **Web (JavaScript)** - Browser-based animations
- **React** - React component integration
- **React Native** - Mobile React applications
- **Flutter** - Cross-platform mobile apps
- **iOS** - Native iOS applications (Swift)
- **Android** - Native Android applications (Kotlin/Java)

### Game Runtimes
- **Unity** - Unity game engine (C#)
- **Unreal Engine** - Unreal Engine (C++)
- **Defold** - Defold game engine (Lua)

### Community Runtimes
- **C#** - .NET applications
- **Qt/QtQuick** - Qt applications

## 🔧 Development

### Build Commands

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode (watch)
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Clean build
npm run clean
```

### Project Structure

```
src/
├── index.ts              # Main MCP server
├── tools/                # Tool implementations
│   ├── definitions.ts    # Tool definitions
│   ├── handlers.ts       # Tool handlers
│   ├── search.ts         # Search functionality
│   └── doc-fetcher.ts    # Document fetching
├── utils/                # Utilities
│   ├── constants.ts      # Configuration constants
│   ├── http-client.ts    # HTTP client
│   ├── cache.ts          # Caching system
│   ├── logger.ts         # Logging utility
│   ├── error-handler.ts  # Error handling
│   ├── content-extractor.ts  # Content extraction
│   └── navigation-crawler.ts # Navigation discovery
└── types/                # TypeScript types
    └── index.ts          # Type definitions
```

## 📈 Performance

- **Caching**: TTL-based caching for documentation content, search results, and navigation
- **Rate Limiting**: Built-in rate limiting to respect Rive's servers
- **Concurrent Requests**: Limited concurrent requests for optimal performance
- **Error Handling**: Comprehensive error handling with retry logic
- **Memory Management**: Efficient memory usage with cache size limits

## 🤝 Contributing

1. Fork the repository
2. Create a 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

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Rive](https://rive.app/) for creating an amazing animation platform
- [Anthropic](https://anthropic.com/) for the Model Context Protocol
- The Rive community for excellent documentation and resources

## 🔗 Links

- [Rive Documentation](https://rive.app/docs)
- [Rive Community](https://community.rive.app)
- [Model Context Protocol](https://github.com/anthropics/mcp)
- [Issue Tracker](https://github.com/your-username/rive-docs-mcp/issues)

---

Made with ❤️ for the Rive animation community