Server Doctor

ChatGPT Image 15. Juni 2026, 10_12_10.png

# ServerDoctor

Read-only analysis, diagnostics and monitoring platform for Minecraft servers.
Analyzes, evaluates, recommends, warns — never changes anything on the server.

This is the runnable foundation (the "Plugin v0.1" phase) from the architecture document:
four modules, one buildable Paper plugin with real scanners, a public API, an event system
and an in-game command.

## Modules in this build

| Module | Contents | Status |
|---|---|---|
| serverdoctor-common | Domain models, utilities |

compiles (verified) |
| serverdoctor-api | Public contract, events, module SPI |

compiles (verified) |
| serverdoctor-core | Engine, 5 scanners, recommendations, conflict DB |

compiles (verified) |
| serverdoctor-storage | StorageProvider, 5 repositories, SQLite + in-memory |

verified (Memory live, SQLite schema against the real engine) |
| serverdoctor-testing | Fake-platform fixtures, JUnit 5 suite, ArchUnit rules |

verified (40 assertions proven framework-free) |
| serverdoctor-paper | Bukkit/Paper adapter, plugin main, command, storage wiring |

buildable (requires the Paper API) |

Included scanners: Plugin, Dependency, Conflict, Performance, Security.

## Building

Requirements: JDK 21, Gradle 8.8+ (or run gradle wrapper once).

Bash:

gradle :serverdoctor-paper:shadowJar

Output: serverdoctor-paper/build/libs/ServerDoctor-0.1.0-SNAPSHOT.jar
(bundles common/api/core). Drop it into the plugins/ folder of a Paper 1.21.x server.

## Commands

Code:

/serverdoctor scan            # run a full analysis
/serverdoctor report          # show the latest report
/serverdoctor tps             # live performance (TPS/MSPT/RAM)
/serverdoctor conflicts       # detected plugin conflicts
/serverdoctor security        # security and maintenance risks
/serverdoctor recs            # generated recommendations
/serverdoctor history         # stored performance history

Aliases: /sd, /doctor · Permission: serverdoctor.admin (default: op).
An asynchronous background scan also runs every 5 minutes.

## Tests

Unit tests (JUnit 5) live in src/test of the respective modules; fixtures and the
ArchUnit architecture tests are in the serverdoctor-testing module.

Bash:

gradle test

Covered: version/severity logic, the AnalysisResult builder, ScannerRegistry capability
gating, the EventBus (including error isolation), all scanner thresholds, the
RecommendationEngine, the analysis engine end-to-end, and storage (Memory + SQLite
round-trip via jdbc:sqlite::memory:). The ArchUnit rules enforce, as build breakers:
no platform SDK in Core/Common/API/Storage, the Clean Architecture dependency rule,
and the read-only invariant of the platform adapters.

## Integration for third-party plugins (≤ 5 lines)

Java:

import com.serverdoctor.api.ServerDoctorProvider;
import com.serverdoctor.api.event.PluginConflictDetectedEvent;

var api = ServerDoctorProvider.get();
double tps = api.getPerformanceSnapshot().tps1m();
api.events().subscribe(PluginConflictDetectedEvent.class,
        e -> getLogger().warning("Conflict: " + e.conflict().description()));

Java:

api.registerModule(new AnalysisModule() {
    public String id() { return "my-scanner"; }
    public AnalysisResult analyze(ServerContext ctx) {
        return AnalysisResult.builder(id())
                .finding(new Finding(id(), Severity.INFO,
                        ctx.plugins().size() + " plugins seen"))
                .build();
    }
});

## Deliberately NOT included yet (upcoming iterations)

bungeecord modules (platform adapters)
serverdoctor-storage: PostgreSQL and MariaDB backends (SQLite + in-memory are done)
serverdoctor-rest-api (HTTP/JSON) and serverdoctor-webhook (Discord/Slack/Teams)
Update checker (Modrinth/Hangar/SpigotMC/GitHub), PlaceholderAPI bridge
serverdoctor-example-plugin (reference integration)
A real security advisory source (currently only a metadata heuristic, no invented CVE database)

Server Doctor v0.9.2

Overview Dependencies Updates (3) History Discord Issues Wiki