Visual Minecraft inventory GUI editor for custom Paper, Spigot, or Bukkit plugins.

Design slots visually, save validated JSON, export a stable GUI contract, or let an AI update layouts through MCP. JsonGui owns layout; plugin code owns permissions, commands, events, and game logic.

Early beta. Treat exported files as versioned application data.

• Drag-and-drop Minecraft inventory layouts.
• Catalog search, item metadata, actions, container selection, undo/redo, templates, and JSON export.
• Minecraft text preview for legacy and hex colors: &a, &l, &#rrggbb, and &x&r&r&g&g&b&b.
• Per-item lock controls and a GUI reset action.
• Local project persistence with ETags and conflict protection.
• Plugin Workspace scanner for Paper, Spigot, Bukkit, Gradle, Maven, Java, and Kotlin projects.
• JsonSkill rules for AI-generated layouts.
• Local MCP server for AI-assisted reads, patches, validated updates, exports, and catalog access.

• Node.js current LTS
• npm

npm install
npm run dev

Open the Vite URL printed in terminal. Default: http://127.0.0.1:5173.

npm run dev starts both local API and web editor.

JsonGui MCP uses stdio. OpenCode starts it automatically; do not run it manually during normal use.

Create opencode.json in repository root:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "jsongui": {
      "type": "local",
      "command": ["node", "server/mcp.mjs"],
      "cwd": ".",
      "enabled": true,
      "env": {
        "GUI_FORGE_DATA_ROOT": "./data"
      }
    }
  }
}

Restart OpenCode, then verify:

opencode mcp list

Example prompt:

Use jsongui tools. Read main-menu, follow selected JsonSkill, then create a balanced 6-row shop GUI.

MCP tools:

• projects_list, projects_get, projects_create
• projects_update for complete replacement
• projects_patch for title, slot, or item changes
• projects_export
• catalog_get

Run MCP directly only for troubleshooting:

npm run mcp

Place skills in:

JsonSkill/<skill-id>/*.md

Choose a skill in app Settings. Choice is stored per GUI project. MCP returns selected skill instructions with project reads, updates, and exports.

Included skills:

• minecraft-standard
• fill-gradient-colors

1. Start JsonGui.
2. Choose container and place items.
3. Set item names, lore, actions, and locks.
4. Preview Minecraft colors and tooltip text.
5. Optionally select a JsonSkill and use MCP with an AI client.
6. Export JSON or load it from plugin code.
7. Test behavior on server.

Canonical export contains container, title, and item data. Example:

{
  "format": "gui-forge/minecraft-java-gui",
  "formatVersion": 1,
  "container": {
    "id": "single-chest",
    "bukkitType": "CHEST",
    "rows": 3,
    "slots": 27
  },
  "title": "&bMain Menu",
  "items": [
    {
      "slot": 11,
      "itemId": "minecraft:compass",
      "material": "COMPASS",
      "amount": 1,
      "displayName": "&l&bOpen Menu",
      "lore": ["&7Open the main menu."],
      "locked": true,
      "action": { "type": "open_gui", "guiId": "other-menu" }
    }
  ]
}

Actions are data only. Consuming plugin must decide how to validate permissions and execute behavior.

Open Workspace in app, then select plugin root. JsonGui scans build files and metadata without running Gradle or Maven, then writes workspace files only inside:

<plugin-root>/.jsongui/

Current scanner selects root module only.

npm run desktop:dev
npm run desktop:build

Desktop build stages Node sidecar automatically. Release signing notes: docs/releasing.md.

src/        React editor
server/     Local API, storage, validation, MCP
shared/     Shared export utilities and seed data
JsonSkill/  AI layout rules
src-tauri/  Desktop shell

Before a pull request:

npm run lint
npm test
npm run test:server
npm run build

JsonGui is independent and not affiliated with Mojang Studios or Microsoft. Minecraft names and assets belong to their owners.