# Minecraft.How - Minecraft Server & Skin Platform

> A modern Laravel-powered platform for Minecraft server listings and skin management
> Last updated: 2025-11-18 10:04:28 UTC

## Platform Overview

Minecraft.How is a comprehensive platform providing:
- **Server Directory**: Real-time Minecraft server listings with live ping/query
- **Skin Library**: Extensive collection of Minecraft player skins with AI categorization
- **Multi-category System**: Advanced classification for both servers and skins
- **Real-time Data**: Live server status, player counts, and MOTD display
- **Community Features**: Server voting, skin downloads, user profiles

## Platform Statistics

- Total Skins: 106193
- Total Servers: 1303
- Total Users: 50
- Skin Categories: 26
- Server Categories: 18
- Online Servers: 859

## Technology Stack

### Backend
- **Framework**: Laravel 12 (PHP 8.2+)
- **Database**: MySQL with optimized indexing
- **Queue System**: Redis-backed job processing
- **Caching**: Redis for high-performance caching
- **Real-time**: Laravel Echo + Pusher for live updates

### Frontend
- **Framework**: React 19 + TypeScript
- **Build Tool**: Vite 7
- **Styling**: Tailwind CSS 4
- **SPA Architecture**: Inertia.js 2.0
- **UI Components**: shadcn/ui (Radix UI primitives)
- **3D Rendering**: Three.js + skinview3d for skin visualization

### Minecraft Integration
- **Server Ping**: Modern Minecraft protocol (1.7+) with SRV resolution
- **Server Query**: Extended server information and player lists
- **Skin Management**: Integration with mc-heads.net API
- **Version Support**: Tracks all Minecraft versions from official sources

## API Endpoints

### Servers
- `GET /api/servers` - List servers with pagination and filters
- `GET /api/servers/{id}` - Get server details
- `GET /api/servers/{id}/ping` - Real-time server ping
- `POST /api/servers/{id}/vote` - Vote for a server
- `GET /api/servers/stats` - Server statistics

### Skins
- `GET /api/skins` - List skins with pagination and filters
- `GET /api/skins/{id}` - Get skin details
- `GET /api/skins/{id}/download` - Download skin file
- `POST /api/skins/scrape` - Scrape skin by username
- `GET /api/skins/stats` - Skin statistics

### Search
- `GET /api/search` - Combined search across servers and skins
- `GET /api/search/suggestions` - Search auto-complete
- `GET /api/search/trending` - Trending searches

## Skin Categories
- **Angel** (`angel`) - Skins in the angel category
- **Animals** (`animals`) - Animal and creature inspired skins
- **Anime Skins** (`anime`) - Anime and manga inspired Minecraft skins
- **Armor** (`armor`) - Skins in the armor category
- **Boys Skins** (`boys`) - Minecraft skins designed for male characters and boys
- **Celebrities** (`celebrities`) - Celebrity and famous person skins
- **Classic** (`classic`) - Skins in the classic category
- **Fantasy/Medieval** (`fantasy`) - Fantasy, medieval, and magical character skins
- **Gaming Characters** (`gaming`) - Popular video game character skins
- **Girls Skins** (`girls`) - Minecraft skins designed for female characters and girls
- **Historical** (`historical`) - Historical figures and period clothing
- **Hoodie** (`hoodie`) - Skins in the hoodie category
- **Memes/Funny** (`memes`) - Meme and funny character skins
- **Mob** (`mob`) - Skins in the mob category
- **Modern/Casual** (`modern`) - Modern day and casual clothing skins
- **Monsters/Creepy** (`monsters`) - Monster, zombie, and creepy character skins
- **Pirate** (`pirate`) - Skins in the pirate category
- **Professions** (`professions`) - Professional and job-related skins
- **Robot** (`robot`) - Skins in the robot category
- **Royal** (`royal`) - Skins in the royal category
- **Seasonal/Holiday** (`seasonal`) - Holiday and seasonal themed skins
- **Sports** (`sports`) - Sports themed and athlete skins
- **Superhero Skins** (`superhero`) - Superhero and comic book character skins
- **Warrior** (`warrior`) - Skins in the warrior category
- **Worker** (`worker`) - Skins in the worker category
- **Zombie** (`zombie`) - Skins in the zombie category

## Server Categories

- **Adventure** (`adventure`) - Custom adventure maps and quest-based gameplay servers
- **Anarchy** (`anarchy`) - No rules servers where anything goes - pure chaos and freedom
- **Bedwars** (`bedwars`) - Team-based minigame where players protect their bed and eliminate others
- **Creative** (`creative`) - Creative building servers with unlimited resources and no survival mechanics
- **Economy** (`economy`) - Servers focused on trading, shops, and economic gameplay
- **Factions** (`factions`) - Team-based PvP servers with faction warfare and base building
- **Hardcore** (`hardcore`) - Extreme difficulty servers with permanent death or harsh penalties
- **MCMMO** (`mcmmo`) - Servers with MCMMO plugin adding RPG-style skills and leveling
- **Minigames** (`minigames`) - Servers featuring various mini-games and arcade-style gameplay
- **Modded** (`modded`) - Servers running with mods that enhance or change gameplay
- **Network** (`network`) - Large server networks with multiple game modes and lobbies
- **Pixelmon** (`pixelmon`) - Pokémon-themed modded servers with creature catching and battles
- **Prison** (`prison`) - Prison-themed servers where players mine and rank up through prison tiers
- **PvP** (`pvp`) - Player vs Player combat-focused servers
- **Roleplay** (`roleplay`) - Immersive roleplay servers with storytelling and character development
- **Skyblock** (`skyblock`) - Challenging island-based servers where players start with minimal resources
- **Survival** (`survival`) - Classic Minecraft survival servers where players gather resources, build, and survive
- **Towny** (`towny`) - Community building servers where players create towns and nations


## Key Features

### Server Listings
- **Real-time Status**: Live ping updates showing online/offline status
- **Player Tracking**: Current and maximum player counts
- **Version Compatibility**: Filter servers by Minecraft version
- **Server Query**: Extended information including player lists and plugins
- **Vote System**: Community voting with IP-based rate limiting
- **Categories**: Multi-category classification (Survival, PvP, Creative, etc.)

### Skin Management
- **AI Categorization**: Automatic skin classification by gender, style, and type
- **3D Preview**: Interactive 3D skin viewer using skinview3d
- **Batch Import**: Scrape and import skins from Minecraft usernames
- **Analytics**: Track views and downloads per skin
- **WebP Thumbnails**: Optimized thumbnail generation for fast loading
- **Search & Filter**: Advanced filtering by multiple categories

### Technical Features
- **Async Processing**: Queue-based jobs for ping, scrape, and categorization
- **Caching Strategy**: Multi-layer caching for optimal performance
- **SEO Optimized**: Server-side rendering with Inertia.js
- **CDN Ready**: Bunny.net integration for global content delivery
- **MCP Integration**: Model Context Protocol for AI agent access
- **OAuth Authentication**: Support for Discord, Twitch, Microsoft, Steam, and more

## MCP (Model Context Protocol) Integration

The platform provides AI agents with programmatic access via Laravel's native MCP implementation.

### Available MCP Tools
- `search_servers` - Search and filter Minecraft servers
- `get_server_status` - Real-time server ping and status
- `search_skins` - Search skin library with filters
- `get_user_profile` - User information lookup
- `get_trending` - Trending content across the platform

### MCP Endpoints
- `/mcp` - MCP landing page and documentation
- `/mcp/minecraft` - Main Minecraft data server

## Data Schema

### Servers Table
- ID, name, description, IP address, port
- Online status, player counts, version, MOTD
- Vote count, ranking, categories (many-to-many)
- Ping data (latency, favicon, last check)
- Timestamps and soft deletes

### Skins Table
- ID, UUID, username, title, description
- File paths (PNG original, WebP thumbnail)
- View count, download count
- Categories (many-to-many)
- AI categorization metadata
- Timestamps and soft deletes

### Categories
- Skin categories: Gender-based, style-based, character-based
- Server categories: Gameplay modes, themes, features
- Many-to-many relationships via pivot tables

## Performance Characteristics

- **Average Response Time**: < 100ms for cached queries
- **Search Performance**: 10-minute cache with Redis
- **Server Ping**: 5-second timeout with async job processing
- **Image Serving**: CDN-accelerated with WebP compression
- **Database**: Optimized indexes on frequently queried fields
- **Caching**: Multi-layer strategy (Redis, CDN, edge)

## Development & Deployment

### Development Commands
- `composer dev` - Start full development stack
- `npm run dev` - Frontend dev server with HMR
- `php artisan test` - Run test suite
- `php artisan queue:listen` - Process async jobs

### Key Artisan Commands
- `php artisan import:complete-database` - Full legacy migration
- `php artisan query:servers` - Batch ping all servers
- `php artisan import:all-legacy-skins` - Import legacy skins
- `php artisan update:minecraft-versions` - Update version catalog

## Documentation

For detailed documentation, see:
- `/CLAUDE.md` - Full project documentation
- `/TODO.md` - Comprehensive roadmap
- `/MIGRATION_AND_ENHANCEMENT_PLAN.md` - Migration strategy
- `/OLD_PROJECT_SCAN.md` - Legacy platform analysis

## Contact & Links

- **Website**: https://minecraft.how
- **MCP Documentation**: https://minecraft.how/mcp
- **API Base**: https://minecraft.how/api
- **Documentation**: https://minecraft.how/llms.txt (this file)

## How AI Can Use This Data

This platform is optimized for AI access:

1. **Direct Queries**: Ask about Minecraft servers by criteria (game mode, version, player count)
2. **Skin Discovery**: Search for skins by category, style, or description
3. **Real-time Data**: Get current server status and player counts
4. **MCP Integration**: Connect via Model Context Protocol for programmatic access
5. **API Access**: RESTful API endpoints for all public data

## Example AI Queries

- "Find popular Minecraft survival servers with over 100 players"
- "Show me anime-themed Minecraft skins"
- "What are the top-voted PvP servers running version 1.20?"
- "Get server status for play.hypixel.net"
- "Find creative servers that support bedrock edition"

---

*This file is dynamically generated from live platform data and cached for 6 hours.*
*For the most current statistics and real-time data, visit https://minecraft.how*