itemscore-helper 1.0.0

package/lib/manifest.js

@@ -0,0 +1,234 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const BUNDLED = path.join(__dirname, "..", "data", "itemscore-api.json")
+const NEED_BLOCK_VALUES = ["BOTH", "AIR", "BLOCK"]
+
+function resolveManifestPath(explicit) {
+  const candidates = [
+    explicit,
+    process.env.ITEMSCORE_API,
+    path.resolve(process.cwd(), "plugins", "ItemsCore", "itemscore-api.json"),
+  ]
+  for (const c of candidates) {
+    if (c && fs.existsSync(c)) return c
+  }
+  return BUNDLED
+}
+
+function loadManifest(explicit) {
+  const file = resolveManifestPath(explicit)
+  const data = JSON.parse(fs.readFileSync(file, "utf8"))
+  return { manifest: data, source: file, isBundled: file === BUNDLED }
+}
+
+function buildIndex(loaded) {
+  const manifest = loaded.manifest
+  const bindings = manifest.bindings || []
+  const triggers = manifest.triggers || []
+  const events = manifest.events || []
+  const variables = manifest.variables || []
+
+  const BINDING_NAMES = bindings.map((b) => b.name)
+  const TRIGGER_NAMES = triggers.map((t) => t.name)
+
+  const KNOWN_RECEIVERS = new Set()
+  for (const b of bindings) KNOWN_RECEIVERS.add(b.name)
+  for (const v of variables) KNOWN_RECEIVERS.add(v.name)
+  for (const t of triggers) for (const v of t.variables || []) KNOWN_RECEIVERS.add(v)
+  for (const e of events) for (const v of e.variables || []) KNOWN_RECEIVERS.add(v)
+
+  return { manifest, source: loaded.source, isBundled: loaded.isBundled, bindings, triggers, events, variables, BINDING_NAMES, TRIGGER_NAMES, KNOWN_RECEIVERS }
+}
+
+function searchMethods(idx, opts) {
+  opts = opts || {}
+  const q = (opts.query || "").trim().toLowerCase()
+  const limit = opts.limit && opts.limit > 0 ? opts.limit : 40
+  const hits = []
+  for (const b of idx.bindings) {
+    if (opts.binding && b.name !== opts.binding) continue
+    for (const m of b.methods || []) {
+      if (m.useless && !opts.includeUseless) continue
+      if (q) {
+        const hay = (m.name + " " + m.signature + " " + m.category + " " + m.description).toLowerCase()
+        if (!hay.includes(q)) continue
+      }
+      hits.push(Object.assign({ binding: b.name }, m))
+    }
+  }
+  hits.sort((a, b) => {
+    if (q) {
+      const an = a.name.toLowerCase() === q ? 0 : a.name.toLowerCase().startsWith(q) ? 1 : 2
+      const bn = b.name.toLowerCase() === q ? 0 : b.name.toLowerCase().startsWith(q) ? 1 : 2
+      if (an !== bn) return an - bn
+    }
+    return a.name.localeCompare(b.name)
+  })
+  return hits.slice(0, limit)
+}
+
+function getMethod(idx, name, binding) {
+  let wantBinding = binding
+  let wantName = name
+  if (name.includes(".")) {
+    const i = name.indexOf(".")
+    wantBinding = name.slice(0, i)
+    wantName = name.slice(i + 1)
+  }
+  const out = []
+  for (const b of idx.bindings) {
+    if (wantBinding && b.name !== wantBinding) continue
+    for (const m of b.methods || []) {
+      if (m.name === wantName) out.push(Object.assign({ binding: b.name }, m))
+    }
+  }
+  return out
+}
+
+function validateStep(idx, step, p, errors, warnings) {
+  if (typeof step !== "object" || step === null) {
+    errors.push(p + " must be an object")
+    return
+  }
+  const call = step.call
+  if (typeof call !== "string" || call.length === 0) {
+    errors.push(p + ".call is required and must be a string")
+    return
+  }
+  if (call.includes(".")) {
+    const receiver = call.slice(0, call.indexOf("."))
+    const method = call.slice(call.indexOf(".") + 1)
+    if (idx.BINDING_NAMES.includes(receiver)) {
+      const found = getMethod(idx, method, receiver)
+      if (found.length === 0) {
+        errors.push(p + '.call "' + call + '" references unknown method "' + method + '" on binding "' + receiver + '"')
+      } else if (found[0].useless) {
+        warnings.push(p + '.call "' + call + '" is flagged useless (no real effect)')
+      }
+    } else if (!idx.KNOWN_RECEIVERS.has(receiver)) {
+      warnings.push(p + '.call receiver "' + receiver + '" is not a known variable; make sure it is defined earlier or exists at runtime')
+    }
+  } else if (!idx.KNOWN_RECEIVERS.has(call)) {
+    warnings.push(p + '.call "' + call + '" is treated as a bare variable read but is not a known variable')
+  }
+  if (step.args !== undefined && !Array.isArray(step.args)) errors.push(p + ".args must be an array when present")
+  if (step.operatorToNext !== undefined && typeof step.operatorToNext !== "string") errors.push(p + ".operatorToNext must be a string when present")
+}
+
+function validateItem(idx, item) {
+  const errors = []
+  const warnings = []
+  if (typeof item !== "object" || item === null) return { valid: false, errors: ["item must be a JSON object"], warnings }
+
+  if (typeof item.name !== "string" || item.name.length === 0) errors.push("name is required and must be a non-empty string")
+  if (typeof item.material !== "string" || item.material.length === 0) errors.push("material is required and must be a non-empty string (e.g. DIAMOND_SWORD)")
+  if (item.needBlock !== undefined && (typeof item.needBlock !== "string" || !NEED_BLOCK_VALUES.includes(item.needBlock))) {
+    errors.push("needBlock must be one of " + NEED_BLOCK_VALUES.join(", "))
+  }
+
+  if (item.actions !== undefined) {
+    if (!Array.isArray(item.actions)) errors.push("actions must be an array")
+    else {
+      item.actions.forEach((action, ai) => {
+        const ap = "actions[" + ai + "]"
+        if (typeof action !== "object" || action === null) {
+          errors.push(ap + " must be an object")
+          return
+        }
+        if (typeof action.trigger !== "string" || !idx.TRIGGER_NAMES.includes(action.trigger)) {
+          errors.push(ap + '.trigger "' + String(action.trigger) + '" is not a valid trigger. Valid: ' + idx.TRIGGER_NAMES.join(", "))
+        }
+        if (action.needBlock !== undefined && (typeof action.needBlock !== "string" || !NEED_BLOCK_VALUES.includes(action.needBlock))) {
+          errors.push(ap + ".needBlock must be one of " + NEED_BLOCK_VALUES.join(", "))
+        }
+        if (!Array.isArray(action.steps)) errors.push(ap + ".steps must be an array")
+        else action.steps.forEach((s, si) => validateStep(idx, s, ap + ".steps[" + si + "]", errors, warnings))
+      })
+    }
+  }
+
+  if (item.stats !== undefined && !Array.isArray(item.stats)) errors.push("stats must be an array when present")
+  if (item.lore !== undefined && !Array.isArray(item.lore)) errors.push("lore must be an array of strings when present")
+  if (item.enchantments !== undefined && !Array.isArray(item.enchantments)) errors.push("enchantments must be an array when present")
+
+  return { valid: errors.length === 0, errors, warnings }
+}
+
+function itemSchema(idx) {
+  return {
+    description:
+      "Clean item JSON consumed by the ItemsCore plugin via /ic import. The plugin converts this into both runnable code and a GUI-editable action graph, so items authored this way stay editable in-game.",
+    needBlockValues: NEED_BLOCK_VALUES,
+    fields: {
+      name: "string (required) - internal item id, no spaces",
+      fancyName: "string - display name, supports & color codes",
+      id: "string - optional explicit id, defaults to name",
+      material: "string (required) - Bukkit material, e.g. DIAMOND_SWORD",
+      needBlock: "BOTH | AIR | BLOCK - default interaction context for the whole item",
+      lore: "string[] - lore lines, support & color codes",
+      enchantments: "{ name: string, level: number }[]",
+      flags: "string[] - Bukkit ItemFlag names",
+      talisman: "boolean - whether the item works from the inventory (talisman)",
+      customModelData: "number",
+      skullOwner: "string - player name for PLAYER_HEAD skins",
+      stats: "object[] - stat modifiers (see editor)",
+      actions: "Action[] - the behavior graph",
+      events: "object[] - custom event definitions",
+    },
+    action: {
+      trigger: "string (required) - one of: " + idx.TRIGGER_NAMES.join(", "),
+      needBlock: "BOTH | AIR | BLOCK - optional per-action override",
+      steps: "Step[] - executed in order, combined by operatorToNext",
+    },
+    step: {
+      call:
+        'string (required) - "core.method", "particles.method", "values.method", "api.method", a bukkit call like "player.getLocation", or a bare variable name to read it',
+      args:
+        'Arg[] - each arg is a JSON literal (string/number/boolean), or { var: "player" } to pass a variable, or a nested { call, args } to pass a method result',
+      operatorToNext:
+        "NONE | ADD | SUBTRACT | MULTIPLY | DIVIDE | EQUALS | NOT_EQUALS | GREATER_THAN | LESS_THAN | GREATER_THAN_EQUALS | LESS_THAN_EQUALS | AND | OR | END | COMMA - how this step combines with the next one (defaults to END)",
+    },
+    bukkitObjects:
+      "player, shooter, victim, arrow, event, and any entity, block, world, location, or ItemStack returned by a method are real Bukkit/Spigot objects. You can call any standard Spigot method on them in a step (for example player.sendMessage, player.getHealth, player.getWorld, victim.setFireTicks), not only the ItemsCore methods. These are not in the method list below; see https://hub.spigotmc.org/javadocs/spigot/ for the full Spigot API. Prefer a core method when one exists.",
+    bindings: idx.bindings.map((b) => ({ name: b.name, description: b.description || "", methodCount: (b.methods || []).length })),
+    variables: idx.variables,
+    triggers: idx.triggers,
+  }
+}
+
+function generateItemTemplate(kind) {
+  const k = (kind || "basic").toLowerCase()
+  if (k === "ability" || k === "spell") {
+    return {
+      name: "magic_wand",
+      fancyName: "&dMagic Wand",
+      material: "BLAZE_ROD",
+      needBlock: "BOTH",
+      lore: ["&7Right-click to cast.", "&dExample ItemsCore item."],
+      talisman: false,
+      actions: [
+        { trigger: "rightAction", needBlock: "BOTH", steps: [{ call: "core.broadcastMessage", args: ["A wand was cast!"], operatorToNext: "END" }] },
+      ],
+      events: [],
+    }
+  }
+  return {
+    name: "example_sword",
+    fancyName: "&bExample Sword",
+    material: "DIAMOND_SWORD",
+    needBlock: "BOTH",
+    lore: ["&7A starter ItemsCore item.", "&7Left-click to greet the server."],
+    enchantments: [{ name: "DAMAGE_ALL", level: 1 }],
+    flags: [],
+    talisman: false,
+    actions: [
+      { trigger: "leftAction", needBlock: "BOTH", steps: [{ call: "core.broadcastMessage", args: ["Hello from my custom sword!"], operatorToNext: "END" }] },
+    ],
+    events: [],
+  }
+}
+
+module.exports = { loadManifest, buildIndex, searchMethods, getMethod, validateItem, itemSchema, generateItemTemplate, resolveManifestPath }

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "itemscore-helper",
+  "version": "1.0.0",
+  "description": "Local MCP server + skill that lets any AI (Claude, Codex, Cursor, Gemini, and others) build and edit custom Minecraft items for the ItemsCore plugin. Runs entirely on your machine.",
+  "bin": {
+    "itemscore-helper": "bin/cli.js",
+    "itemscore-mcp": "bin/mcp.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "data/",
+    "skill/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "itemscore",
+    "minecraft",
+    "spigot",
+    "bukkit",
+    "mcp",
+    "model-context-protocol",
+    "ai",
+    "skill",
+    "claude",
+    "cursor",
+    "codex",
+    "gemini"
+  ],
+  "homepage": "https://www.coredevelopment.shop/docs/items-core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Tc554/itemscore-helper.git"
+  },
+  "license": "MIT",
+  "author": "TastyCake",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  }
+}

package/skill/ITEM_FORMAT.md

@@ -0,0 +1,193 @@
+# ItemsCore clean item JSON reference
+
+This is the offline reference for the item format ItemsCore imports. When the live API is reachable, prefer it (`get_item_schema`, `search_methods`, `get_method`), because it reflects the exact methods on the user's server. Use this file when offline.
+
+## Top-level fields
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | string, required | Internal id, no spaces (e.g. `flame_sword`) |
+| `fancyName` | string | Display name, supports `&` color codes |
+| `id` | string | Optional explicit id; defaults to `name` |
+| `material` | string, required | Bukkit material (e.g. `DIAMOND_SWORD`, `BLAZE_ROD`, `PLAYER_HEAD`) |
+| `needBlock` | `BOTH` \| `AIR` \| `BLOCK` | Default interaction context for the item |
+| `lore` | string[] | Lore lines, support `&` color codes |
+| `enchantments` | `{ name, level }[]` | e.g. `{ "name": "DAMAGE_ALL", "level": 3 }` |
+| `flags` | string[] | Bukkit ItemFlag names (e.g. `HIDE_ATTRIBUTES`) |
+| `talisman` | boolean | If true, the item works from anywhere in the inventory |
+| `customModelData` | number | Resource-pack model id |
+| `skullOwner` | string | Player name, for `PLAYER_HEAD` skins |
+| `stats` | object[] | Stat modifiers (authored in the editor; preserved on re-import) |
+| `actions` | Action[] | The behavior graph (see below) |
+| `events` | object[] | Custom event definitions |
+
+## Action
+
+```json
+{ "trigger": "rightAction", "needBlock": "BOTH", "steps": [ ... ] }
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `trigger` | string, required | One of the triggers below |
+| `needBlock` | `BOTH` \| `AIR` \| `BLOCK` | Optional per-action override of the item default |
+| `steps` | Step[] | Run in order, combined by each step's `operatorToNext` |
+
+### Triggers
+
+| Trigger | Fires when | Variables available |
+|---|---|---|
+| `leftAction` | Left-click holding the item (this is the attack swing) | player, item, event |
+| `leftSAction` | Sneak + left-click | player, item, event |
+| `rightAction` | Right-click holding the item | player, item, event |
+| `rightSAction` | Sneak + right-click | player, item, event |
+| `shiftAction` | Starts sneaking while holding or wearing it | player, item, event |
+| `dropAction` | Drops the item (the drop is cancelled) | player, item, event |
+| `swapAction` | Swaps hands (F) with the item | player, item, event |
+| `shootAction` | Shoots a projectile while holding it | shooter, item, event |
+| `pickupAction` | Picks up the item | player, item, event |
+| `arrowLandAction` | An arrow shot while holding it lands | shooter, item, arrow, landLocation, event |
+| `armorEquipEvent` | The item (armor) is equipped | player, item, event |
+| `armorUnEquipEvent` | The item (armor) is unequipped | player, item, event |
+| `playerMoveEvent` | Moves while holding or wearing it | player, item, event |
+| `playerDamageEvent` | The holder/wearer takes damage | player, item, event |
+| `projectileHitEntityEvent` | A custom projectile from this item hits an entity | shooter, victim, item, lastLocation, event |
+| `projectileHitBlockEvent` | A custom projectile from this item hits a block | shooter, item, lastLocation, event |
+
+## Step
+
+```json
+{ "call": "core.heal", "args": [ { "var": "player" }, 6 ], "operatorToNext": "END" }
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `call` | string, required | `core.method`, `particles.method`, `values.method`, `api.method`, a Bukkit call like `player.getLocation`, or a bare variable name to read it |
+| `args` | Arg[] | The call arguments, in order |
+| `operatorToNext` | string | How this step joins the next one (default `END`) |
+
+### Arg forms
+
+- A JSON literal: `"hello"`, `6`, `1.5`, `true`.
+- A variable: `{ "var": "player" }` passes the `player` object.
+- A nested call: `{ "call": "player.getLocation", "args": [] }` passes one call's result into another.
+
+Example, passing results into a call:
+
+```json
+{ "call": "core.playSound", "args": [
+  { "var": "player" },
+  { "call": "player.getLocation", "args": [] },
+  { "call": "core.getSound", "args": ["ENTITY_BLAZE_SHOOT"] },
+  1, 1
+] }
+```
+
+### Operators (`operatorToNext`)
+
+| Operator | Meaning |
+|---|---|
+| `END` | End the statement (most common; use between independent steps) |
+| `NONE` | No joining token |
+| `ADD` `SUBTRACT` `MULTIPLY` `DIVIDE` | Arithmetic `+ - * /` between values |
+| `EQUALS` `NOT_EQUALS` | `===` `!==` |
+| `GREATER_THAN` `LESS_THAN` `GREATER_THAN_EQUALS` `LESS_THAN_EQUALS` | `>` `<` `>=` `<=` |
+| `AND` `OR` | `&&` `\|\|` |
+| `COMMA` | `,` separate values |
+
+For most items, every step uses `END`. Operators other than `END` build a single expression across steps (for conditions and math). When you need a condition, prefer `core.doIf` / `core.doIfElse` / `core.chanceOf` rather than chaining raw operators.
+
+## Variables
+
+| Variable | When |
+|---|---|
+| `core` `particles` `values` `api` | Always available (the scripting bindings) |
+| `item` | Always (the custom item this action belongs to) |
+| `event` | Always (the Bukkit event; cancel it with `core.cancelEvent(event)`) |
+| `player` | Most triggers |
+| `shooter` | shootAction, arrowLandAction, projectile hit events |
+| `victim` | projectileHitEntityEvent |
+| `arrow` | arrowLandAction |
+| `landLocation` | arrowLandAction |
+| `lastLocation` | projectile hit events |
+
+## Bukkit objects expose their full Spigot API
+
+`player`, `shooter`, `victim`, `arrow`, `event`, and any entity, block, world, location, or `ItemStack` returned by a method are real Bukkit/Spigot objects. You can call any standard Spigot method on them in a step, not only the ItemsCore methods:
+
+- `{ "call": "player.sendMessage", "args": ["&aHi"] }`
+- `{ "call": "player.setFireTicks", "args": [60] }`
+- `{ "call": "victim.getHealth", "args": [] }`
+- `{ "call": "player.getWorld", "args": [] }`
+
+These are not in the `core` / `particles` / `values` / `api` method list. For the complete set, see the Spigot API docs at https://hub.spigotmc.org/javadocs/spigot/ (match your server version). Prefer a `core` method when one exists; use raw Spigot calls for the rest.
+
+## Bindings (summary)
+
+- `core` - the main toolkit: messaging, teleport, damage/heal, effects, sounds, projectiles, conditions, loops, variables, commands, placeholders.
+- `particles` - build and display particle effects (`of`, `colored`, `withLocation`, `circle`, ...).
+- `values` - custom values registered by addons.
+- `api` - the public plugin API.
+
+Always confirm a method's exact name and parameters with `get_method` / `search_methods` before using it. Do not guess.
+
+## Worked example: a healing ability wand
+
+```json
+{
+  "name": "healers_touch",
+  "fancyName": "&dHealer's Touch",
+  "material": "BLAZE_ROD",
+  "needBlock": "BOTH",
+  "lore": ["&7Right-click to channel healing energy."],
+  "enchantments": [{ "name": "LUCK", "level": 1 }],
+  "flags": ["HIDE_ENCHANTS"],
+  "talisman": false,
+  "actions": [
+    {
+      "trigger": "rightAction",
+      "needBlock": "BOTH",
+      "steps": [
+        { "call": "core.sendColorMessage", "args": [ { "var": "player" }, "&aYou channel healing energy!" ], "operatorToNext": "END" },
+        { "call": "core.heal", "args": [ { "var": "player" }, 6 ], "operatorToNext": "END" },
+        { "call": "core.giveEffect", "args": [ { "var": "player" }, "REGENERATION", 100, 1, false, true ], "operatorToNext": "END" },
+        { "call": "core.playSound", "args": [ { "var": "player" }, { "call": "player.getLocation", "args": [] }, { "call": "core.getSound", "args": ["ENTITY_PLAYER_LEVELUP"] }, 1, 1 ], "operatorToNext": "END" }
+      ]
+    }
+  ],
+  "events": []
+}
+```
+
+## Worked example: a lightning sword with a chance roll
+
+```json
+{
+  "name": "storm_blade",
+  "fancyName": "&bStorm Blade",
+  "material": "DIAMOND_SWORD",
+  "needBlock": "BOTH",
+  "lore": ["&7Left-click: 25% chance to call lightning."],
+  "enchantments": [{ "name": "DAMAGE_ALL", "level": 4 }],
+  "talisman": false,
+  "actions": [
+    {
+      "trigger": "leftAction",
+      "needBlock": "BOTH",
+      "steps": [
+        { "call": "core.doIf", "args": [ { "call": "core.chanceOf", "args": [25] }, "core.summonLightningByLocation(player.getLocation())" ], "operatorToNext": "END" }
+      ]
+    }
+  ],
+  "events": []
+}
+```
+
+Note on `core.doIf(boolean condition, String action)`: the second argument is a short string of script that runs only when the condition is true. Keep that string to a single statement and use methods you have verified exist. For multi-step conditional logic, run several `doIf` steps.
+
+## Before you deliver
+
+1. Every `trigger` is in the table above.
+2. Every `core.` / `particles.` / `values.` / `api.` call is a real method (checked with `get_method`).
+3. Argument order and count match the method signature.
+4. Run `validate_item` and clear all errors.

package/skill/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: itemscore
+description: Build and edit custom Minecraft RPG items for the ItemsCore plugin. Use whenever the user wants to create a new item, change how an item behaves, add an ability or particle effect, or fix an ItemsCore item. The user runs a Minecraft server with ItemsCore installed; you produce a clean item JSON file they import in-game.
+---
+
+# ItemsCore item builder
+
+ItemsCore is a Minecraft (Bukkit/Spigot) plugin that lets a server owner create fully custom RPG items without writing Java. You help the user build those items.
+
+## The one rule that matters
+
+Always produce a **clean item JSON** (the format described below). Never hand-write the plugin's internal `.item` YAML or its generated JavaScript `code`. When the user imports your JSON, the plugin builds **both** the runnable code **and** the in-game GUI action graph from it. That means an item you create this way still works **and** stays fully editable in the in-game editor. Hand-writing raw code produces an item the GUI cannot open, which is exactly the problem this format avoids.
+
+## Step 1: Get the API (do this first)
+
+Use the real API instead of guessing method names.
+
+Preferred - the `itemscore` MCP server. It runs locally on the user's machine (installed with `npx itemscore-helper`) and exposes these tools. If it is connected, call them:
+- `search_methods(query, binding?, includeUseless?)` - find scripting methods by name, category, or description
+- `get_method(name, binding?)` - full signature, params, return, and example for one method (accepts `core.teleport` or `teleport`)
+- `list_triggers()` - every trigger an item can react to, and the variables available in each
+- `list_events()` - custom events and the global variables (player, event, core, particles, ...)
+- `get_item_schema()` - the full field reference for the clean item JSON
+- `validate_item(item)` - checks an item JSON and returns errors and warnings
+- `generate_item_template(kind?)` - a valid starter item (`basic` or `ability`)
+
+Fallback - if no MCP is connected, a hosted copy is available over plain HTTP:
+- MCP endpoint: `https://www.coredevelopment.shop/api/mcp`
+- API manifest: `https://www.coredevelopment.shop/api/itemscore/manifest`
+- Item schema: `https://www.coredevelopment.shop/api/itemscore/item-schema`
+- Quick guide: `https://www.coredevelopment.shop/llms.txt`
+
+If nothing is reachable, use `ITEM_FORMAT.md` in this folder as the offline reference.
+
+## Step 2: Build the item JSON
+
+Minimal shape:
+
+```json
+{
+  "name": "flame_sword",
+  "fancyName": "&cFlame Sword",
+  "material": "DIAMOND_SWORD",
+  "needBlock": "BOTH",
+  "lore": ["&7Left-click to ignite the server."],
+  "talisman": false,
+  "actions": [
+    {
+      "trigger": "leftAction",
+      "needBlock": "BOTH",
+      "steps": [
+        { "call": "core.broadcastMessage", "args": ["The flame sword roars!"], "operatorToNext": "END" }
+      ]
+    }
+  ],
+  "events": []
+}
+```
+
+Rules:
+- `name` and `material` are required. `material` is a Bukkit material name (e.g. `DIAMOND_SWORD`, `BLAZE_ROD`).
+- Color codes use `&` (e.g. `&c` red, `&a` green).
+- `trigger` must be one of the valid triggers (call `list_triggers`). Common ones: `leftAction` (left-click, which is also the attack swing), `rightAction` (right-click, e.g. cast an ability), `shiftAction` (start sneaking), `playerDamageEvent` (the wearer takes damage), `projectileHitEntityEvent` (a custom projectile from the item hits an entity). There is no separate melee-attack trigger; left-click is the attack.
+- Each step has a `call`, an `args` array, and `operatorToNext`. `call` is `core.method`, `particles.method`, a Bukkit call like `player.getLocation`, or a bare variable name to read it.
+- An arg is a JSON literal, `{ "var": "player" }` to pass a variable, or a nested `{ "call": ..., "args": ... }` to pass one method's result into another.
+- `operatorToNext` joins a step to the next one. Use `END` to end a statement. Other values (`ADD`, `EQUALS`, `AND`, ...) build expressions and conditions. See `ITEM_FORMAT.md`.
+
+Find the exact method you need with `search_methods` / `get_method` before using it. Do not invent method names.
+
+## Bukkit and Spigot objects
+
+The variables `player`, `shooter`, `victim`, `arrow`, `event`, and any entity, block, world, location, or item you get back from a method are real Bukkit/Spigot objects. They expose their entire normal Spigot API, not just the ItemsCore methods, so you can call any standard Spigot method on them directly in a step.
+
+Examples:
+- `{ "call": "player.sendMessage", "args": ["&aHi"] }`
+- `{ "call": "player.getHealth", "args": [] }`
+- `{ "call": "player.getWorld", "args": [] }`
+- `{ "call": "victim.setFireTicks", "args": [100] }`
+- `{ "call": "player.getLocation", "args": [] }` (pass the result into another call)
+
+These Spigot methods are not listed by `search_methods`, because the ItemsCore API (`core`, `particles`, `values`, `api`) is only one part of what you can call. For the full set of methods on `player`, `event`, entities, blocks, worlds, and locations, use the Spigot API docs at https://hub.spigotmc.org/javadocs/spigot/ and match the server's Minecraft version. Prefer a `core` method when one exists (for example `core.heal`, `core.teleport`, `core.giveEffect`), and use raw Spigot calls for anything `core` does not cover.
+
+## Step 3: Validate
+
+Run `validate_item` on your JSON. Fix every entry under `errors` before continuing. `warnings` are usually fine (for example a Bukkit call the API cannot introspect), but read them.
+
+## Step 4: Hand it to the user
+
+1. Save the JSON as `<name>.item` (or `<name>.json`).
+2. Tell the user to put the file in `plugins/ItemsCore/imports/` on their server.
+3. Tell them to run `/ic import <name>` in-game.
+
+On success the plugin replies: `Imported <name> (N action(s)). It is now live and GUI-editable.` The item is immediately usable and can be opened in the editor with `/itemeditor <name>`.
+
+## Editing an existing item
+
+1. User runs `/ic export <name>` in-game. The plugin writes `plugins/ItemsCore/exports/<name>.json`.
+2. User shares that file with you. Edit the clean JSON.
+3. Validate, then re-import the same way. Importing by the same `name` updates the item and preserves its stats, recipe, and attributes.
+
+If the item is a **legacy code-only item** (made before this format, so the editor cannot open it), have the user run `/ic adopt <name>` first. That converts its code into GUI actions; then export, edit, and re-import as above.
+
+## Command cheat sheet
+
+| Command | What it does |
+|---|---|
+| `/ic import <file>` | Import a clean JSON from `plugins/ItemsCore/imports/` (live + GUI-editable) |
+| `/ic export <item>` | Write an existing item to `plugins/ItemsCore/exports/<item>.json` |
+| `/ic adopt <item>` | Make a legacy code-only item GUI-editable |
+| `/ic reload [item]` | Reload all items, or one, and report success or errors |
+| `/ic exportapi` | Regenerate `plugins/ItemsCore/itemscore-api.json` (the API manifest) |
+| `/itemeditor <item>` | Open the visual editor for an item |
+
+## When in doubt
+
+- Ask the user what the item should look like (material, name) and what it should do, and on which interaction.
+- Keep effects simple unless asked: a message, a heal, a teleport, a particle burst, lightning, potion effects.
+- Always validate before delivering. Never claim an item works if you did not validate it.

package/skill/examples/healers_touch.item

@@ -0,0 +1,23 @@
+{
+  "name": "healers_touch",
+  "fancyName": "&dHealer's Touch",
+  "material": "BLAZE_ROD",
+  "needBlock": "BOTH",
+  "lore": ["&7Right-click to channel healing energy."],
+  "enchantments": [{ "name": "LUCK", "level": 1 }],
+  "flags": ["HIDE_ENCHANTS"],
+  "talisman": false,
+  "actions": [
+    {
+      "trigger": "rightAction",
+      "needBlock": "BOTH",
+      "steps": [
+        { "call": "core.sendColorMessage", "args": [ { "var": "player" }, "&aYou channel healing energy!" ], "operatorToNext": "END" },
+        { "call": "core.heal", "args": [ { "var": "player" }, 6 ], "operatorToNext": "END" },
+        { "call": "core.giveEffect", "args": [ { "var": "player" }, "REGENERATION", 100, 1, false, true ], "operatorToNext": "END" },
+        { "call": "core.playSound", "args": [ { "var": "player" }, { "call": "player.getLocation", "args": [] }, { "call": "core.getSound", "args": ["ENTITY_PLAYER_LEVELUP"] }, 1, 1 ], "operatorToNext": "END" }
+      ]
+    }
+  ],
+  "events": []
+}

package/skill/examples/storm_blade.item

@@ -0,0 +1,19 @@
+{
+  "name": "storm_blade",
+  "fancyName": "&bStorm Blade",
+  "material": "DIAMOND_SWORD",
+  "needBlock": "BOTH",
+  "lore": ["&7Left-click: 25% chance to call lightning."],
+  "enchantments": [{ "name": "DAMAGE_ALL", "level": 4 }],
+  "talisman": false,
+  "actions": [
+    {
+      "trigger": "leftAction",
+      "needBlock": "BOTH",
+      "steps": [
+        { "call": "core.doIf", "args": [ { "call": "core.chanceOf", "args": [25] }, "core.summonLightningByLocation(player.getLocation())" ], "operatorToNext": "END" }
+      ]
+    }
+  ],
+  "events": []
+}

package/skill/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "itemscore": {
+      "command": "npx",
+      "args": ["-y", "itemscore-helper", "serve"]
+    }
+  }
+}