MC-Vector

Minecraft - Multi-Function Server Management Software

MC-Vector is a powerful cross-platform desktop application for managing Minecraft servers with ease. Built with Tauri and React, it provides a modern, fast, and intuitive interface for server administration.

Contributions are welcome — see CONTRIBUTING.md for setup, conventions, and the pull request process.

Features

• 🗣 Multi-Language Support - Select either English or Japanese as the language to use within the app
• 🖥️ Multi-Platform Support - Works on macOS, Windows, and Linux
• 🎮 Multiple Server Management - Create and manage multiple Minecraft servers
• 🔌 Plugin/Mod Browser - Install plugins and mods directly from Modrinth, Hangar, and SpigotMC with one click
• 📊 Real-Time Monitoring - Dashboard with CPU usage, memory usage, and server status
• 💾 Backup & Restore - Create and restore server backups with ease
• 📁 Built-in File Manager - Edit server files directly in the app
• 👥 User Management - Manage whitelist, operators, bans, and IP bans
• 🌐 Proxy Network Setup - Easy proxy server configuration (BungeeCord, Velocity)
• 🔗 Port Forwarding Elimination - Ngrok integration for public access without port forwarding
• ☕ Java Version Management - Download, detect, select, and remove Java runtime versions
• 🔄 Auto-Updater - Keep MC-Vector up to date automatically

---

One-liner install(recommended)

macOS

brew tap tukuyomil032/tap
brew install --cask mc-vector

#　Remove quarantine flag to allow the app to run.
xattr -cr /Applications/MC-Vector.app

Windows

scoop bucket add tukuyomil032 https://github.com/tukuyomil032/homebrew-tap
scoop install mc-vector

Uninstall

macOS

brew uninstall mc-vector
brew untap tukuyomil032/mcvector

Windows

scoop uninstall mc-vector
scoop bucket rm tukuyomil032

Manual Installation

macOS

1. Download MC-Vector.dmg from Releases
2. Open the .dmg file
3. Drag MC-Vector to Applications
4. Launch MC-Vector from Applications

Windows

1. Download MC-Vector-Setup.exe from Releases
2. Run the installer
3. Follow the installation wizard
4. Launch MC-Vector from the Start menu

---

Table of Contents

• Features
• Installation
• Requirements
• Quick Start
• Development
• Building
• Project Structure
• Commands Reference
• Documentation
• Contributing
• License

---

Requirements

For Users

• macOS 10.15+ / Windows 10+
• 4GB+ RAM recommended
• Java 17+ - 21 or 25 recommended (for running Minecraft servers)

For Developers

• Node.js v20.19+ or v22.12+ (v22 recommended)
• Bun v1.4.2
• Rust v1.77.2 or later

Optional:

• just - Modern task runner

---

Quick Start

For Users

1. Download the latest release from Releases
2. Install the application
3. Launch MC-Vector
4. Create a server:
   • Click "+ Add Server"
   • Set server name, software, version, port, and memory
   • Click "Create"
5. Start your server and enjoy!

For detailed usage instructions, see the User Guide.

For Developers

Quick Setup:

git clone https://github.com/tukuyomil032/MC-Vector.git
cd MC-Vector
just setup
just dev-app  # Start Tauri app with dev server

Manual Setup:

git clone https://github.com/tukuyomil032/MC-Vector.git
cd MC-Vector

# Install dependencies (Bun 1.4.2; Node.js 20.19+ or 22.12+ and Rust required)
bun install

# Optional but recommended: Run full setup with portless
just setup

# Start development
just dev-app
# or
bun run tauri:dev

What does just setup do?

just setup automates your development environment setup:

1. 📦 Installs all project dependencies via bun install
2. ✅ Runs all quality checks (lint, format, rustfmt)
3. 🔒 Configures portless CA certificate for HTTPS development (may require system password)
4. 🌐 Adds mc-vector.localhost to your hosts file for local HTTPS access
   • Windows: C:\Windows\System32\drivers\etc\hosts (requires Administrator)
   • macOS/Linux: /etc/hosts (requires sudo password)

Note: Steps 3-4 are for portless HTTPS development and are optional. If you skip these steps, you can still develop using bun run tauri:dev with standard http://localhost:5173.

Development server options:

• just dev-web - Browser-only dev server via portless HTTPS (https://mc-vector.localhost)
• just dev-app - Full Tauri app with dev server (recommended for app development)

For detailed development instructions, see the Development Guide.

---

Development

Setup Development Environment

Install dependencies manually:

# Install Node.js, Bun, and Rust
# (See Development Guide for detailed instructions)

# Install project dependencies and configure environment
bun install
just setup

# Alternative: Skip portless setup and use standard localhost
bun install
bun run check

Development Workflow

For Tauri app development (recommended):

just dev-app

This starts both the Vite dev server and the Tauri application window.

For browser-only development:

just dev-web
# or
bun run dev

This starts the Vite dev server via portless at https://mc-vector.localhost (requires just setup first).

Run quality checks before committing:

just check-all

For more details, see the Development Guide.

---

Building

Build for Production

just tauri-build

Build artifacts will be in src-tauri/target/release/bundle/:

• macOS: .dmg and .app
• Windows: .exe

Debug Build

just tauri-build --debug --no-bundle

---

Project Structure

MC-Vector/
├── src/                              # Frontend source code
│   ├── App.tsx                       # Main application component
│   ├── main.tsx                      # React entry point
│   ├── assets/                       # Static assets (icons, images)
│   ├── styles/                       # Plain CSS tokens/components plus Tailwind utilities
│   │   ├── base/                     # Base styles and resets
│   │   ├── components/               # Reusable UI component styles
│   │   ├── layout/                   # App shell and navigation layout
│   │   ├── modals/                   # Modal-specific styles
│   │   └── views/                    # View-specific styles
│   ├── lib/                          # Frontend API layer (Tauri wrappers)
│   │   ├── server-commands.ts        # Server lifecycle operations
│   │   ├── file-commands.ts          # File system operations
│   │   ├── plugin-commands.ts        # Plugin/mod management
│   │   └── ...
│   └── renderer/                     # React components
│       ├── components/               # UI components
│       │   ├── AddServerModal.tsx
│       │   ├── DashboardView.tsx
│       │   ├── ConsoleView.tsx
│       │   ├── FilesView.tsx
│       │   ├── PluginBrowser.tsx
│       │   └── ...
│       └── shared/                   # Shared utilities and types
│
├── src-tauri/                        # Rust backend (Tauri core)
│   ├── Cargo.toml                    # Rust dependencies
│   ├── tauri.conf.json               # Tauri configuration
│   ├── build.rs                      # Build script
│   ├── capabilities/                 # Tauri capability definitions
│   └── src/
│       ├── main.rs                   # Rust entry point
│       ├── lib.rs                    # Library exports
│       └── commands/                 # Tauri command handlers
│           ├── server.rs             # Server process management
│           ├── file_utils.rs         # File system utilities
│           ├── download.rs           # HTTP downloads
│           ├── health_check.rs       # Dashboard health checks
│           ├── updater_utils.rs.     # Update functionals
│           ├── perf.rs               # Console ANSI colors
│           ├── security.rs           # Security check
│           ├── process_stats.rs      # System monitoring
│           ├── backup.rs             # Backup/restore operations
│           ├── java.rs               # Java runtime detection
│           └── ngrok.rs              # Ngrok integration
│
├── docs/                             # Astro/Starlight documentation site
│   └── src/content/docs/             # User guide, dev setup, architecture docs
│
├── .github/                          # GitHub configurations
│   ├── workflows/                    # CI/CD workflows
│   └── pull_request_template.md      # PR description template
│
├── scripts/
│   ├── cargo-optional.mjs            # check Cargo dependencies
│   ├── install-extensions.mjs.       # Install VS Code extensions
│   ├── prepare-release.mjs           # prepare a release
│   └── update-minecraft-versions.js  # Update supported Minecraft versions
│
├── justfile                          # Modern task runner
├── package.json                      # Node.js project manifest
├── bun.lock                          # Bun text lock file
├── vite.config.ts                    # Vite build configuration
├── tailwind.config.js                # Tailwind CSS configuration
├── postcss.config.js                 # postcss configuration
├── tsconfig.json                     # TypeScript configuration
├── AGENTS.md                         # AI Agent rule file
├── CLAUDE.md                         # CLAUDE rule files
├── CONTRIBUTING.md                   # Contribution guidelines
└── README.md                         # This file

For a detailed architecture overview, see Architecture Documentation.

---

Commands Reference

Development Tasks

Task	justfile	Description
Install dependencies	just install	Install all dependencies
Full setup	just setup	Install deps + portless setup + quality checks
Start frontend dev	just dev-web	Start Vite dev server via portless (https://mc-vector.localhost)
Start Tauri dev	just dev-app	Start Tauri app in dev mode

Build Tasks

Task	justfile	Description
Build frontend	just build	Build frontend for production
Build Tauri app	just tauri-build	Build Tauri application

Quality Checks

Task	justfile	Description
Lint code	just lint	Run Oxlint
Format code	just format	Format code with Oxfmt
Check all	just check	Run lint & format checks
Format Rust	just rustfmt	Format Rust code
Rust check	just rustfmt-check	Check Rust formatting without changes
All checks	just check-all	Run all quality checks

Utilities

Task	justfile	Description
Full setup	just setup	Install deps + portless + all checks
Clean builds	just clean	Clean build artifacts
Install extensions	just install-extensions	Install VS Code extensions
Prepare release	just release	Prepare a release
Update Minecraft versions	just update-minecraft-versions	Update supported Minecraft versions

To prepare a release, run just release and enter X.Y.Z or vX.Y.Z when prompted. Copy or run the printed commit command, push main, and GitHub Actions creates the tag and release.

For detailed command usage, see the Development Guide.

---

Documentation

• User Guide - Complete guide to using MC-Vector
• Development Guide - Developer setup and workflow
• Architecture - Technical architecture overview
• Contributing Guide - Conventions, validation, and pull request expectations

---

Quick Contribution Guide

See CONTRIBUTING.md for the full guidelines. In short:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Run quality checks: just check-all
5. Commit your changes: git commit -m "feat: your feature description"
6. Push to your fork: git push origin feature/your-feature
7. Open a Pull Request

---

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Technology Stack

• Frontend: React 19, TypeScript, Vite, CSS, TailwindCSS
• Desktop: Tauri v2 (Rust backend)
• State Management: Zustand
• UI Components: Lucide React, Framer Motion
• Code Editor: Monaco Editor
• Charts: Recharts
• Terminal: xterm.js
• Package Manager: Bun 1.4.2
• Build Tool: Vite
• Task Runner: just
• Linter: Oxlint
• Formatter: Oxfmt
• Git Hooks: Lefthook
• Rust Formatter: rustfmt

For more details, see the Architecture Documentation and Development Guide.

---

Acknowledgments

• Built with Tauri
• UI powered by React
• Icons from Lucide

---

Made with ❤️ by tukuyomi032