JsonGui

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.

Features

• 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.

Requirements

• Node.js current LTS
• npm

Quick start

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.

MCP with OpenCode

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

JsonSkill

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

Typical workflow

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.

Export format

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.

Plugin Workspace

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.

Desktop

npm run desktop:dev
npm run desktop:build

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

Scripts

Command	Purpose
npm run dev	Start API and Vite editor
npm run dev:web	Start Vite editor only
npm run dev:api	Start API with watch mode
npm run mcp	Start JsonGui MCP over stdio
npm start	Start API normally
npm run build	Type-check and build web app
npm run lint	Run ESLint
npm test	Run frontend/domain tests
npm run test:server	Run server tests
npm run catalog:refresh	Refresh catalog data

Project layout

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

Contributing

Before a pull request:

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

Disclaimer

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