Engine internals

The Minecraft Server Finder pipeline from input to export.

This is a guided tour of the orchestration logic inside app.py and the mcsmartscan package, so you can reason about performance, safety, and extension points.

Runtime flow

Five pillars coordinate every sweep.

GUI and console launches call the same functions; only the presentation layer changes.

1. Configuration ingestion

ScannerAppGUI (Tkinter) or the console shim collects ranges, port lists, workers, proxies, and Mullvad toggles. Defaults come from mcsmartscan.constants.

2. Work distribution

ip_range_generator expands CIDRs/start-end pairs. permuted_index_generator shuffles work deterministically before pushing addresses into a bounded queue.

3. Connection attempts

ThreadPoolExecutor workers pop targets, dial sockets directly or through ProxyPool, and record latency/failure metrics for adaptive throttling.

4. Validation & enrichment

Minecraft-specific handshakes confirm services. Optional libraries (mcstatus, python-nmap) enrich MOTDs, banners, and protocol hints.

5. Persistence & UI updates

StorageManager writes artefacts immediately while the GUI table and console logger surface status updates in real time.

Refer to app.py for the complete orchestration logic and inline comments describing each subsystem hand-off.

Module map

Understand what each package is responsible for.

Everything sits inside the repository, so you can audit or extend without hunting external dependencies.

mcsmartscan.utils

Pure functions that normalise inputs and feed work into the scanner.

  • ip_range_generator expands IPv4 ranges and CIDR blocks safely.
  • permuted_index_generator provides deterministic, collision-free shuffling.
  • Helpers like ip_range_size support progress calculations.

mcsmartscan.proxy

Home of ProxyPool plus custom exceptions for proxy health.

  • Tracks success, failure, and cooldown windows per endpoint.
  • Raises ProxyAcquireTimeout or ProxyTargetError when providers misbehave.
  • Integrates with Mullvad or custom VPN managers via callbacks.

mcsmartscan.vpn

Optional layer that automates Mullvad exit rotation.

  • Validates the Mullvad CLI/API is available before scheduling rotations.
  • Coordinates timing so proxy health checks and VPN swaps do not collide.
  • Safe to ignore—if not configured, the scanner defaults to static egress.

mcsmartscan.storage

StorageManager centralises persistence logic and path handling.

  • Auto-detects the Desktop path across Windows, macOS, and Linux.
  • Writes plain-text leads plus structured JSON for GUI state restoration.
  • Ensures directories exist before writing, reducing runtime surprises.

app.py

The orchestration hub that wires it all together.

  • Initialises GUI widgets, binds event handlers, and schedules periodic tasks.
  • Bootstraps console execution when --nogui is set or Tkinter is unavailable.
  • Exposes extension hooks such as run_console_scan(app) so advanced users can plug in custom loops.
Observability & safety

Instrumentation is built in to keep scans predictable.

Metrics inform decisions about throttling, proxy rotation, and resumability.

Adaptive throttling

Workers monitor failure ratios and timeouts, enabling back-off without manual intervention.

  • Progress counters track processed hosts, latency averages, and ping failures.
  • GUI widgets surface bars and status colours for at-a-glance triage.
  • Console mode logs the same metrics for long-running headless jobs.

Persistence guarantees

Critical writes occur synchronously so crashes or restarts do not lose confirmed hits.

  • Artefacts flush after each discovery to avoid large, fragile buffers.
  • Saved GUI state enables pause/resume workflows across sessions.
  • Storage paths are customisable if you prefer shared volumes or versioned artefacts.

Responsible defaults

The project ships with conservative settings you can adjust once you understand the impact.

  • DEFAULT_TIMEOUT = 4.0 seconds balances reachability with empathy for remote hosts.
  • DEFAULT_WORKERS = 150 keeps bandwidth requirements reasonable for most connections.
  • Mullvad cycling and proxy usage are opt-in, avoiding accidental policy breaches.

When extending the scanner, keep the legal and ethical guidelines in mind—see the Ethics & FAQ page for recommendations.