MINECRAFT JAVA / DISCOVERY & INDEXINGIndependent project · CLI first

Read the server.
Keep the signal.

Discover, scan, and search Minecraft Java servers.
Turn public Status responses into a structured index—
with the original evidence intact.

Read the docs GitHub (private)

Python / asyncio / PostgreSQLOptional Claude enrichment. The scanner runs independently.

STATUS / 0x00REPOSITORY FIXTURE

description.text

Private Survival

version.name: 1.21.8
version.protocol: 772
players.online / max: 7 / 20
software: Unknown not reported

Inspect the original packet

{
  "version": {
    "name": "1.21.8",
    "protocol": 772
  },
  "players": {
    "online": 7,
    "max": 20
  },
  "description": {
    "text": "Private Survival"
  },
  "enforcesSecureChat": true,
  "previewsChat": false
}

Server-reported values. No player login. No AI required.

01 / COLLECT02 / PRESERVE03 / QUERYInspect the tool ↓

01 / THE INSTRUMENT

A server list ping.
An index with memory.

Start with an endpoint. Keep the response. Query what the server actually reported.

Read the protocol.

Minecraft Java Status probing without player login. Parse text components, version strings, public player samples, favicons, and explicitly reported mod metadata.

TCP → Handshake → Status → Ping/Pong

Keep the evidence.

Preserve the raw response alongside normalized fields. PostgreSQL holds current state, change snapshots, public player observations, and scan runs. A failed check keeps the last successful state.

raw_status / server_state / snapshots

Find what matters.

Combine version, reported software, mod loader, player count, MOTD, and sourced country filters. Query your own index with readable CLI output or JSON.

breakbot search --version 1.21 --players-min 5

BREAKBOT / CLILOCAL FIXTURE CAPTURE

breakbot probe 127.0.0.1:37975 --layout classic --no-image

BreakBot

Endpoint
Address        127.0.0.1:37975
Status         ONLINE         
Protocol type  modern         

Minecraft
Version   1.21.8
Protocol  772   
Players   7 / 20

MOTD
Private Survival

Server software
Reported             Unknown
Hint (version.name)  Unknown

Mods
Loader  Unknown
Mods    Unknown

Chat flags (as reported)
Enforces secure chat  true 
Previews chat         false

Network
TCP     0.4 ms 
Status  0.25 ms
Ping    0.12 ms
Total   0.95 ms

Real CLI output from a local TCP fixture. Endpoint and timings belong to this capture; this is not a live public server.

BEYOND ONE ENDPOINT

Bound the work.
Keep failures visible.

$ breakbot scan targets.txt --concurrency 32

Bounded async workers, configurable timeouts, and recorded diagnostics.

$ breakbot rescan --older-than 3600

Recheck stored endpoints without erasing their last successful state.

02 / OPTIONAL ENRICHMENT

IN DEVELOPMENT Implemented locally · live API verification pending

AI-assisted
Server Classification.

Collect the metadata first. Optionally ask Claude to interpret it.
Reported fields, advertised claims, and AI interpretations stay distinct.

STATUS METADATA → CLAUDE ANALYSIS → STRUCTURED CLASSIFICATIONILLUSTRATIVE · NO CLAUDE API RESPONSE

A / SOURCE

The server says

RAW STATUS / description.text

“Private Survival”

{
  "motd": "Private Survival",
  "version": "1.21.8",
  "reported_software": null,
  "reported_proxy": null,
  "reported_mod_loader": null,
  "reported_mods": null
}

Real input derived from normal.json through BreakBot’s parser and AI input builder. Players and arbitrary raw fields are omitted.

B / INTERPRET

Claude

Explicit request
Bounded input
Schema validation
Evidence validation

OPTIONAL BRANCH

The example on this page is illustrative.
No request is made.

C / STRUCTURE

Keep the basis

Game mode: survival advertised
Language: Unknown
Region: Unknown
Tags: None in this example
Claims: None identified

SUPPORTING EXCERPT / motd

“Survival”

Confirms the quoted text exists. Does not verify gameplay.

SUMMARY / AI INTERPRETATIONAdvertises survival gameplay.

Keep unknowns unknown

“Private” does not establish a whitelist or authentication mode. Language and region are not advertised.

The schema supports game modes, language, advertised region, gameplay tags, short summaries, and evidence-backed advertised claims. Tags are stored today; AI-tag search is planned. Interpretations may be inaccurate.

Inspect the contract ↗

IMPLEMENTED COMMAND$ breakbot analyze <server>CLI example +

The command analyzes an existing saved successful Status result. Install the AI extra, migrate PostgreSQL, and provide an API key for new analysis. This is output from the actual renderer using schema-validated illustrative data, not a live Claude result.

$uv run --extra ai breakbot analyze 127.0.0.1:37975

BreakBot / AI Analysis                
┌─────────────────┬─────────────────────────────────┐
│ Server          │ 127.0.0.1:37975                 │
│ Model           │ illustrative (no API call)      │
│ Requested model │ illustrative (no API call)      │
│ Source          │ saved Minecraft Status metadata │
│ Status          │ Completed                       │
│ Cached          │ No                              │
│ State observed  │ fixture capture                 │
│ Analyzed        │ illustrative                    │
└─────────────────┴─────────────────────────────────┘
AI-generated interpretations; advertisements are not verified.
Classification
  Game mode: survival (advertised)
  Language: Unknown
  Region: Unknown
Summary (AI interpretation)
Advertises survival gameplay.
Advertised claims (unverified)
  None identified
Supporting excerpts (server-provided text)
  motd: Survival
Uncertain
  Language and region are not advertised.
  The word Private does not establish whitelist or authentication status.

The endpoint is a capture fixture and must be saved in your own index before analysis. This sample shows the output format only.

03 / UNDER THE HOOD

The pipeline is the product.

One path from candidates to a searchable index.
AI enrichment branches from stored metadata, only when requested.

01
Discovery
scan / import
Inspect stage
Endpoint lists, bounded CIDR scans, and external masscan JSON. An open port is a candidate.
02
Status probe
TCP → Status
Inspect stage
Handshake in Status mode, receive JSON, measure Ping/Pong. Modern Status with a legacy fallback.
03
Parsing
raw + normalized
Inspect stage
Parse the fields the server provides. Keep raw JSON and preserve missing values as unknown.
04
PostgreSQL
state + history
Inspect stage
Store latest successful state, changed snapshots, player observations, and scan run diagnostics.
05
Search
CLI / JSON
Inspect stage
Combine filters over reported metadata. This is a local index, not a hosted public search service.

FROM POSTGRESQL STATE / EXPLICIT INVOCATION

Claude analysisai_enrichmentsSeparate interpretations + evidence

In development. Scanning, rescanning, search, and server inspection require no Claude request.

[01]

Protocol-reported

Values returned in Status fields. A protocol response records what the server reports.

[02]

Server-advertised

Statements in the MOTD or public metadata. Advertising is evidence of a claim, not its truth.

[03]

AI-interpreted

Structured readings of that text, with their basis and excerpts. Never promoted into scanner facts.

04 / DEVELOPMENT LOG

Built in stages.
Stated as it stands.

Implementation state from the current repository.
A plan is not a shipped feature.

IMPLEMENTED / V1

The core index

Single-endpoint probing, full Status parsing, PostgreSQL persistence, bounded bulk scans, masscan import, combined search filters, and explicit rescans.

CLI · STATUS ONLY · LOCAL INDEX

IN DEVELOPMENT

Optional classification

Claude client, analyze, validated evidence, versioned caching, and separate storage are implemented locally. Live Claude and end-to-end database verification remain pending for this website audit.

AI-TAG SEARCH & BACKGROUND ENRICHMENT: PLANNED

PLANNED / V2

A continuously updated index

Continuous discovery and scheduling, reverse player lookup, separate Login checks, throughput work, retention rules, and server-owner opt-out operations.

NO DELIVERY DATES CLAIMED

Read the development notes ↗

05 / PROJECT NOTES

No direct data?
Leave it unknown.

BreakBot is an independent, early-stage engineering project focused on discovering Minecraft Java servers and building a reliable, inspectable index of what they report.

The source response matters as much as the parsed result. Public player samples are incomplete observations. A version string is not proof of the software behind it. Optional AI adds interpretations without rewriting that foundation.

Project documentation ↗Collection & responsible use ↗

Read the server.Keep the signal.

A server list ping.An index with memory.

Read the protocol.

Keep the evidence.

Find what matters.

AI-assistedServer Classification.

Claude

The pipeline is the product.

Discovery

Status probe

Parsing

PostgreSQL

Search