McPinger 🎮

McPinger is a high-performance, lightweight Minecraft Server Status API built with Go and the Fiber web framework. It allows you to query the status of both Java and Bedrock editions of Minecraft servers, featuring built-in Redis caching for extreme performance and scalability.

🚀 Features

• ✅ Multi-edition Support: Fetch status for both Minecraft Java and Bedrock (Pocket Edition) servers.
• ⚡ High Performance: Built with Go and Fiber for ultra-low latency.
• 🧠 Redis Caching: Automatically caches server status to minimize external API calls and improve response times.
• 🔌 Multiple Providers: Seamlessly integrates with various Minecraft status providers (e.g., mcsrvstat, minetools).
• 🐳 Docker Ready: Includes Dockerfile and docker-compose.yml for instant deployment.
• 🛠️ Clean Architecture: Well-structured code for easy maintenance and extension.

🛠️ Tech Stack

• Language: Go (1.22+)
• Web Framework: Fiber v2
• Cache: Redis
• Infrastructure: Docker & Docker Compose

🏁 Getting Started

Prerequisites

• Go 1.22 or higher
• Redis (Local or Docker)
• Docker (Optional, for containerized setup)

Installation

1. Clone the repository:

   git clone https://github.com/corenzy/mcpinger.git
   cd mcpinger
   

2. Environment Configuration: Create a .env file based on the .env.example:

   cp .env.example .env
   

   Edit .env with your settings:

   REDIS_ADDR=localhost:6379
   REDIS_PASSWORD=
   REDIS_DB=0
   PORT=3000
   

3. Run the application:

   go run main.go
   

🐳 Docker Deployment

To run the entire stack (API + Redis) using Docker Compose:

docker-compose up -d

The API will be available at http://localhost:3000.

📡 API Usage

Lookup Server Status

Check the status of a Minecraft server.

• Endpoint: POST /server
• Content-Type: application/json

Request Body

| Field | Type | Description | Default | | :----------- | :------- | :----------------------------------------- | :------ | | ip | string | Required. The IP/Domain of the server. | - | | serverType | string | Either java or bedrock. | java |

Example Request

{
  "ip": "play.hypixel.net",
  "serverType": "java"
}

Example Response

{
    "success": true,
    "message": "Server lookup successful",
    "result": {
        "online": true,
        "ip": "play.hypixel.net",
        "port": 25565,
        "version": "1.8-1.20",
        "players": {
            "online": 45678,
            "max": 100000
        },
        "motd": "Hypixel Network",
        "provider": "minetools",
        "source": "cache"
    }
}

📂 Project Structure

.
├── apps/               # Core application logic
│   ├── cache/          # Redis caching implementation
│   ├── models/         # Data structures and models
│   ├── providers/      # Minecraft API provider integrations
│   ├── services/       # Business logic (Lookup service)
│   ├── utils/          # Helper functions
│   └── server.go       # Fiber server initialization
├── main.go             # Entry point
├── Dockerfile          # Docker image configuration
└── docker-compose.yml  # Docker Compose orchestration

📄 License

Distributed under the MIT License. See LICENSE for more information.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request