Epic: Connect Discover — the open directory for Minecraft servers

[robinbraemer]

Human goal

Players should be able to answer “What can I play right now?” without searching social media, copying unexplained addresses, or trusting an unverified server-list entry.

Server owners should be able to publish a Connect endpoint once and have the same trusted listing appear in the Connect mod, on the Connect website, in Browser Hub, and in third-party tools.

Product promise

Publish once. Be discoverable everywhere Connect is available.

Connect Discover is an open directory for owner-verified, explicitly public Connect endpoints. It is not an enumeration API for every endpoint connected to the network.

First-principles boundary

An endpoint address being routable does not mean its owner intended to advertise it.

• Every Connect endpoint is technically eligible for discovery.
• Only an endpoint imported into a Minekube organization and explicitly published by an authorized owner is indexed.
• Random, unclaimed, private, friend-only, development, and Connect Share endpoints remain unsearchable by default.
• Unpublishing removes the listing and its search documents promptly while preserving only the private audit data required for safety and support.
• Joining still follows the endpoint's own authentication, allowlist, version, modpack, and admission rules. A public listing is not an access-control bypass.

This replaces the legacy negative model of “listed unless prevented” with a positive, auditable publication decision.

One canonical directory

The Minekube control plane owns one canonical public listing record. Every first-party surface consumes the same versioned read API:

1. Connect Share mod — searchable, compatible, one-click discovery and join.
2. Connect website — public, shareable, search-engine-friendly directory and endpoint pages.
3. Browser Hub — in-game discovery backed by the same records and status.
4. Third-party ecosystem — launchers, community sites, bots, agents, and alternative clients use the same unauthenticated API rather than scraping first-party pages.

The dashboard remains the authenticated management surface. Listing metadata and publication state live in the product database; reachability comes from one timestamped Connect status source rather than page-specific ping heuristics.

Open public API

The first stable API should be ordinary HTTPS JSON with a published OpenAPI contract so it is accessible from any language and browser. Generated Connect/gRPC clients may be added without making them a requirement.

Minimum public operations:

• list/search published endpoints using cursor pagination;
• fetch one listing by stable public ID or slug;
• enumerate the supported fixed taxonomy and compatibility facets;
• filter by online state, Java/Bedrock, Minecraft version, modded/vanilla, language, category, and compatible client capabilities;
• sort by relevance, currently joinable, recently active, trending, and verified vote/ranking aggregates;
• support ETag, Cache-Control, conditional requests, CORS, bounded anonymous rate limits, and explicit schema versioning.

Public fields may include display name, description, media, fixed tags, languages, supported editions/versions, modpack requirements, verified join addresses, coarse timestamped availability, owner-opted player-count aggregates, and public vote/rank aggregates.

The API must never expose endpoint tokens, organization-private data, internal addresses, connector topology, libp2p peer IDs, session IDs, friend presence, player identities, raw voter data, precise historical presence, or private diagnostics.

Discovery quality and trust

• Search starts with a maintainable transactional source of truth and deterministic filters; a separate search service is introduced only when measured scale requires it.
• The default Minekube play address remains a verified fallback even when a custom domain is displayed first.
• Status always includes freshness and distinguishes online, offline, degraded, and unknown instead of presenting stale data as live.
• Compatibility is explicit before join: edition, supported Minecraft versions, required loader/modpack, authentication expectations, and resource-pack requirements where known.
• Moderation supports reports, delisting, ownership disputes, impersonation checks, malware/phishing media review, age-appropriate policy, appeals, and a public reason when a listing is unavailable.
• Ranking cannot be bought invisibly. Sponsored placement, if ever introduced, is clearly labeled and never changes organic API results without an explicit query mode.

Player experience

The mod and website optimize for choosing confidently, not maximizing time spent browsing:

• immediate search with typo tolerance and useful filters;
• clear online/freshness and compatibility indicators;
• save/favorite and recently joined lists stored with understandable privacy;
• one primary Join action, with copy/share as secondary actions;
• actionable mismatch or admission explanations before a doomed connection attempt;
• keyboard, screen-reader, controller, localization, reduced-motion, and low-bandwidth support;
• deep links that open the installed mod when possible and otherwise copy the verified address or explain installation.

Existing foundations

• Connect Share universal party system: Epic: Connect Share — Minecraft's universal party system #93
• Adoption and creator growth: Connect Share: launch, measure, and grow through modpacks and creators #118
• Connect fallback operations: Connect Share: operate Connect fallback safely at global scale #119
• Browser voting/listing design: https://github.com/minekube/website/issues/94
• Product API foundation: https://github.com/minekube/website/issues/89
• Scoped endpoint/domain management API decision: https://github.com/minekube/website/issues/107
• Endpoint state consistency: https://github.com/minekube/website/issues/92
• Endpoint app-message transport: https://github.com/minekube/moxy/issues/365

Connect Discover is adjacent to Connect Share but deliberately separate: Share exposes consented friend presence; Discover exposes only owner-published server listings.

Delivery slices

1. Contract, threat model, and read-only API fixture.
2. Verified opt-in publication and owner preview.
3. Search/status/moderation service with a small curated launch catalog.
4. Public website directory and endpoint detail pages.
5. Connect Share mod discovery experience.
6. Browser Hub migration to the canonical API.
7. Public documentation, integration examples, observability, and cross-surface E2E proof.

Each slice must be independently releasable. The API contract and privacy invariants land before a public catalog is populated.

Epic acceptance criteria

• An authorized organization member can preview and explicitly publish an owned Connect endpoint.
• An active but unpublished, random, friend-only, or Connect Share endpoint cannot be found by public ID guessing, search, filters, feeds, or first-party UIs.
• A published endpoint appears consistently in the public API, website, mod, and Browser Hub from the same listing record.
• Public unauthenticated clients can search and paginate without a Minekube account or proprietary SDK.
• The API contract, examples, compatibility policy, caching behavior, rate limits, deprecation policy, and acceptable-use rules are publicly documented.
• Listing status has a timestamp/freshness contract and agrees with the dashboard's authoritative endpoint state.
• Java and Bedrock join addresses, compatibility, and required client setup are understandable before join.
• Owners can unpublish, update, and audit a listing; unauthorized users cannot mutate it.
• Search and ranking resist obvious spam, duplicate publication, impersonation, and vote manipulation.
• No token, private endpoint, player identity, friend presence, internal route, or high-resolution behavioral history is exposed in responses, caches, logs, analytics, or generated pages.
• Contract tests prove all first-party consumers handle pagination, stale/offline state, unpublished removal, compatibility mismatch, moderation removal, and API-version evolution.
• A real production smoke test publishes a dedicated test endpoint, discovers and joins it from the website, mod, and Browser Hub, then unpublishes it and proves removal within the documented bound.
• Public status and adoption dashboards measure API health, search-to-join conversion, failed joins, stale listings, abuse reports, and privacy-safe delisting latency.

Non-goals

• Enumerating every connector or endpoint registered with Connect.
• Publishing single-player worlds or friend presence without a separate explicit host action.
• Replacing endpoint admission, authentication, allowlists, or moderation.
• Requiring a Minekube account or API key for public reads.
• Requiring owners to expose another public status or query port.
• Building a generic marketplace before the trusted endpoint directory works reliably.
• Coupling third-party consumers to dashboard HTML, private database IDs, or internal Moxy protocols.