Describe your dream Minecraft server in plain English. AI builds it, configures it, and launches it.

SMP-GPT replaces the Minecraft Realms button on the title screen with an AI-powered server generator. Type a prompt like "survival server with RPG skills and a web map", and an AI Architect selects plugins from Modrinth, resolves dependencies, provisions the server, and hands you a one-click dashboard — without ever leaving the game. The companion Electron desktop app lets you generate, manage, and share local Minecraft Paper servers with friends — powered by AI. Built at DDCx hackathon.

Minecraft Title Screen
        |
   [SMP-GPT] button
        |
   Landing Screen --> type a prompt
        |
   Loading Screen --> AI "Architect" reasons in real-time
        |
   Blueprint Screen --> review server name, plugins, AI explanation
        |                toggle plugins on/off, then "Launch Server"
        |
   Handoff Screen --> "Open Dashboard" deep-links to desktop app
        |
   Electron Dashboard --> terminal, AI assistant, plugin viewer

git clone https://github.com/smhussa22/ddcxignition-26.git
cd ddcxignition-26
npm install

A pre-built smpgpt-mods.zip is included at the repo root. Extract it into your PrismLauncher instance's mods/ folder:

unzip smpgpt-mods.zip -d /path/to/PrismLauncher/instances/<instance>/minecraft/mods/

The zip contains:

• realmsgpt-0.1.0.jar -- the SMP-GPT Fabric mod
• owo-lib-0.13.0+26.1.jar -- required UI library

You also need fabric-api-0.144.3+26.1.jar in the same mods folder.

cd javaMod/backend
bun install
bun run dev

The API starts on http://localhost:3000. If OPENAI_API_KEY is not set, the backend automatically falls back to mock agents (keyword-driven, no API key needed for demo).

# From repo root
npm run dev

The Electron app opens. This is the dashboard that the Minecraft mod deep-links into.

launch the Fabric 26.1.1 instance with the mod installed.

1. Title screen: You should see a gold "SMP-GPT" button below the Minecraft Realms button (which has a strikethrough overlay).

2. Click SMP-GPT: The landing screen opens. Type a server description, e.g.:

   • "Hardcore survival with RPG skills and dungeons"
   • "Vanilla+ with a web map and economy"
   • Or click a quick-start preset.

3. AI Generation: Watch the loading screen. The AI Architect shows real-time reasoning messages as it progresses through 4 stages (loader selection, intent parsing, mod search, curation).

4. Blueprint Review: A split-pane screen appears:

   • Left: Server name, summary, and a chat log of the Architect's reasoning
   • Right: Recommended plugins with checkboxes (toggle any on/off; some are locked)
   • Click "Launch Server"

5. Handoff: The confirmation screen shows your server name. Click "Open Dashboard".

6. Desktop App: The Electron app should come to focus, navigated to that server's management page. From here you can:

   • Start/Stop the Minecraft server process
   • Watch the terminal with live server logs
   • Send commands directly (e.g., time set day, difficulty hard)
   • View plugins installed for this specific server
   • Ask the AI assistant questions like "tp all players to spawn" -- it parses your intent and executes the corresponding server commands automatically

cd javaMod/backend
bun test

151 tests, 0 failures across 9 test files covering:

• API routes (generate, refine, launch, admin commands)
• AI agent pipeline (loader selection, intent parsing, mod curation)
• Modrinth integration (search, dependency resolution, rate limiting)
• Database CRUD (generations, servers)
• Server provisioning lifecycle
• Zod schema validation (30+ boundary/edge cases)

When a user submits a prompt, a 4-stage pipeline runs:

Stage 0: LoaderSelector    --> choose between Paper (plugins only) & Fabric (mods only)
Stage 1: IntentParser      --> extracts themes, mechanics, constraints, server name
Stage 2: ModSearch         --> queries Modrinth API for matching plugins/mods
Stage 3: ModCurator        --> AI selects best plugins, generates BlueprintProposal

Each stage emits a progress update stored in SQLite, polled by the mod every 2-3 seconds. Agents use OpenAI gpt-5-mini with structured output. Without an API key, mock agents provide a fully functional demo using keyword matching.

The mod opens smpgpt://server?serverId=<id> via the OS:

• macOS: open smpgpt://...
• Windows: cmd /c start "" smpgpt://...
• Linux: xdg-open smpgpt://...

The Electron app registers as the handler via app.setAsDefaultProtocolClient('smpgpt'). On cold launch, the URL is queued and replayed after the window loads. On warm launch, the existing window focuses and navigates immediately. If no handler is installed, the mod shows an in-game error message.

ddcxignition-26/
├── javaMod/                        # Fabric mod + backend
│   ├── src/client/java/...         #   In-game screens (owo-lib UI)
│   ├── src/main/java/...           #   Services, HTTP client, models
│   ├── src/main/resources/         #   fabric.mod.json, lang, textures
│   └── backend/                    #   Bun/Hono API server
│       ├── src/routes/             #     API endpoints
│       ├── src/agents/             #     AI pipeline (4 stages + admin)
│       ├── src/modrinth/           #     Modrinth client + dep resolver
│       ├── src/db/                 #     SQLite repositories
│       ├── src/provisioner/        #     Server provisioning
│       └── tests/                  #     151 tests
├── main/                           # Electron main process
│   ├── main.ts                     #   IPC handlers, deep-link, process mgmt
│   └── preload.cjs                 #   Context bridge (electronAPI)
├── renderer/                       # Next.js frontend
│   └── pages/
│       ├── index.jsx               #   Home / server list
│       └── server.jsx              #   Server dashboard (terminal + AI chat)
├── src/runtime/                    # Server lifecycle manager
│   ├── serverBuilder.ts            #   Generate server dirs + configs
│   ├── serverManager.ts            #   Start/stop Java processes
│   ├── tunnelManager.ts            #   ngrok tunnel management
│   └── pluginCatalog.ts            #   Plugin dependency resolution
├── app-data/
│   ├── paper/paper-26.1.1-15.jar   # Bundled Paper server
│   └── plugins/                    # 8 bundled plugin jars
├── smpgpt-mods.zip                 # Pre-built mod + owo-lib for download
└── package.json                    # Electron/Nextron config