itemscore-helper 1.0.0 → 1.2.1

package/README.md

@@ -1,12 +1,33 @@
 # itemscore-helper
 
-Set up **any** AI assistant to build and edit custom Minecraft items for the [ItemsCore](https://www.coredevelopment.shop/plugins/items-core) plugin. Works with Claude, Codex, Cursor, Gemini, and anything else that supports MCP or custom instructions. You do not need to know how to code.
+Set up **any** AI assistant to build and edit custom Minecraft items for the [ItemsCore](https://www.coredevelopment.shop/plugins/itemscore) plugin. Works with Claude, Codex, Cursor, Gemini, and anything else that supports MCP or custom instructions. You do not need to know how to code.
+
+## Easiest: paste one prompt into your AI
+
+Copy the prompt below and paste it into your AI (Claude, Cursor, Gemini, Codex, anything). It downloads and connects the ItemsCore tools itself, then asks what item you want - no terminal knowledge needed:
+
+```text
+You are my coding agent and I do not know how to code, so do the whole setup yourself - actually run the commands, do not just tell me what to run.
+
+1. In my project folder, run this to download and connect the ItemsCore tools:
+   npx -y itemscore-helper install
+   It installs a local helper and wires an "itemscore" MCP server into this project. When it finishes, reload your MCP servers (or ask me to restart this app) so the itemscore tools load. If you truly cannot run commands, add this to your MCP config instead:
+   {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}
+
+2. Read https://www.coredevelopment.shop/llms.txt so you know the ItemsCore item format and every method available.
+
+3. Tell me you are ready, then ask what item I want. Build a valid .import file (clean item JSON), validate it, and tell me to drop it in plugins/ItemsCore/imports/ and run /ic import in-game. The item stays fully editable in the in-game editor.
+```
+
+The same prompt is on the [docs page](https://www.coredevelopment.shop/docs/itemscore) with a one-click Copy button.
+
+## Or set it up in one command
 
 ```bash
 npx itemscore-helper
 ```
 
-That command drops the ItemsCore skill into a folder and prints exactly what to paste into your AI tool. Then you can ask things like *"make me a sword that calls lightning on left-click"* and your AI produces a ready-to-import item file.
+This auto-detects the AI tools on your machine and connects the local MCP server to each one (a backup of every file it changes is saved beside it). Then just ask your AI for an item.
 
 ## What it sets up
 
@@ -19,8 +40,8 @@ The MCP server is `npx -y itemscore-helper serve`. It speaks the standard stdio
 
 | Command | What it does |
 |---|---|
-| `npx itemscore-helper` | Install the skill files into `./itemscore-helper/` and print setup steps |
-| `npx itemscore-helper --dir DIR` | Install into a custom folder |
+| `npx itemscore-helper` | Auto-detect your AI tools and connect the local MCP server |
+| `npx itemscore-helper --dry-run` | Show what would change, without writing anything |
 | `npx itemscore-helper serve` | Run the local MCP server (this is what your AI runs) |
 | `npx itemscore-helper print` | Print the skill instructions to stdout |
 | `npx itemscore-helper mcp` | Print the MCP server config |
@@ -68,7 +89,7 @@ After connecting, give your AI the `SKILL.md` file as its instructions (paste it
 ## How you use it
 
 1. Ask your AI for an item.
-2. It writes a small `.item` (JSON) file and validates it.
+2. It writes a small `.import` (JSON) file and validates it.
 3. Put that file in `plugins/ItemsCore/imports/` on your server.
 4. Run `/ic import <name>` in-game. The item is live and stays editable in the in-game editor.
 
@@ -76,8 +97,8 @@ To edit an existing item, run `/ic export <name>`, share the exported file with
 
 ## Links
 
-- Documentation: https://www.coredevelopment.shop/docs/items-core
-- Plugin page: https://www.coredevelopment.shop/plugins/items-core
+- Documentation: https://www.coredevelopment.shop/docs/itemscore
+- Plugin page: https://www.coredevelopment.shop/plugins/itemscore
 
 ## License
 

package/bin/cli.js

@@ -3,12 +3,26 @@
 
 const fs = require("fs")
 const path = require("path")
+const { autoConfigure } = require("../lib/install.js")
 
 const HOSTED_URL = "https://www.coredevelopment.shop/api/mcp"
 const LLMS_URL = "https://www.coredevelopment.shop/llms.txt"
-const DOCS_URL = "https://www.coredevelopment.shop/docs/items-core"
+const DOCS_URL = "https://www.coredevelopment.shop/docs/itemscore"
 const SKILL_DIR = path.join(__dirname, "..", "skill")
 
+const SETUP_PROMPT = [
+  "You are my coding agent and I do not know how to code, so do the whole setup yourself - actually run the commands, do not just tell me what to run.",
+  "",
+  "1. In my project folder, run this to download and connect the ItemsCore tools:",
+  "   npx -y itemscore-helper install",
+  '   It installs a local helper and wires an "itemscore" MCP server into this project. When it finishes, reload your MCP servers (or ask me to restart this app) so the itemscore tools load. If you truly cannot run commands, add this to your MCP config instead:',
+  '   {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}',
+  "",
+  "2. Read " + LLMS_URL + " so you know the ItemsCore item format and every method available.",
+  "",
+  "3. Tell me you are ready, then ask what item I want. Build a valid .import file (clean item JSON), validate it, and tell me to drop it in plugins/ItemsCore/imports/ and run /ic import in-game. The item stays fully editable in the in-game editor.",
+].join("\n")
+
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true })
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -20,12 +34,11 @@ function copyDir(src, dest) {
 }
 
 function parseArgs(argv) {
-  const out = { cmd: "install", dir: "itemscore-helper" }
+  const out = { cmd: "install", dryRun: false }
   const rest = []
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i]
-    if (a === "--dir") out.dir = argv[++i]
-    else if (a === "-h" || a === "--help") out.cmd = "help"
+  for (const a of argv) {
+    if (a === "-h" || a === "--help") out.cmd = "help"
+    else if (a === "--dry-run") out.dryRun = true
     else rest.push(a)
   }
   if (rest[0]) out.cmd = rest[0]
@@ -38,16 +51,15 @@ function printHelp() {
     "itemscore-helper - set up any AI to build ItemsCore items",
     "",
     "Usage",
-    "  npx itemscore-helper            Install the skill files here and print setup steps",
-    "  npx itemscore-helper install    Same as above",
-    "  npx itemscore-helper --dir DIR  Install into a custom folder (default: itemscore-helper)",
+    "  npx itemscore-helper            Auto-detect your AI tools and connect the local MCP server",
+    "  npx itemscore-helper --dry-run  Show what would be changed, without writing anything",
     "  npx itemscore-helper serve      Run the local MCP server (this is what your AI runs)",
     "  npx itemscore-helper print      Print the skill instructions (SKILL.md) to stdout",
     "  npx itemscore-helper mcp        Print the MCP server config",
     "  npx itemscore-helper help       Show this help",
     "",
-    "The MCP server runs locally on your machine over stdio. Works with Claude, Codex, Cursor,",
-    "Gemini, and any other AI that supports MCP.",
+    "Don't want to use a terminal? Copy the setup prompt from " + DOCS_URL + " and paste it into your AI - it does the rest.",
+    "Supports Claude (Code & Desktop), Cursor, Gemini CLI, Codex, Windsurf and any MCP client.",
     "Docs: " + DOCS_URL,
     "",
   ].join("\n"))
@@ -55,11 +67,7 @@ function printHelp() {
 
 function printMcp() {
   console.log(
-    JSON.stringify(
-      { mcpServers: { itemscore: { command: "npx", args: ["-y", "itemscore-helper", "serve"] } } },
-      null,
-      2
-    )
+    JSON.stringify({ mcpServers: { itemscore: { command: "npx", args: ["-y", "itemscore-helper", "serve"] } } }, null, 2)
   )
 }
 
@@ -67,58 +75,55 @@ function printSkill() {
   process.stdout.write(fs.readFileSync(path.join(SKILL_DIR, "SKILL.md"), "utf8"))
 }
 
-function printGuide(targetDir) {
-  const skillPath = path.join(targetDir, "SKILL.md")
-  console.log([
-    "",
-    "ItemsCore helper installed.",
-    "",
-    "Files written to " + targetDir + ":",
-    "  SKILL.md          the instructions to give your AI",
-    "  ITEM_FORMAT.md    the full item format reference",
-    "  mcp.json          the MCP server config",
-    "  examples/         ready-made example items",
-    "",
-    "Two things to set up in your AI:",
-    "",
-    "1) Add the local ItemsCore MCP server (runs on your machine over stdio)",
-    "   Same config for every client - command npx, args [-y, itemscore-helper, serve]:",
-    "",
-    "   Cursor        .cursor/mcp.json",
-    '     {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}',
-    "",
-    "   Claude Code   .mcp.json in your project (or claude_desktop_config.json for Desktop)",
-    '     {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}',
-    "",
-    "   Gemini CLI    ~/.gemini/settings.json",
-    '     {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}',
-    "",
-    "   Codex         ~/.codex/config.toml",
-    "     [mcp_servers.itemscore]",
-    '     command = "npx"',
-    '     args = ["-y","itemscore-helper","serve"]',
-    "",
-    "   To match YOUR server's exact API (including addon methods), run /ic exportapi in-game",
-    "   and point the server at the generated file, either with the env var:",
-    "     ITEMSCORE_API=/path/to/plugins/ItemsCore/itemscore-api.json",
-    '   or by adding "--manifest","/path/to/itemscore-api.json" to the args. Otherwise it uses',
-    "   a bundled snapshot of the standard API.",
-    "",
-    "   No MCP support at all? An online copy also exists at " + HOSTED_URL,
-    "   and a plain-text guide at " + LLMS_URL,
-    "",
-    "2) Give your AI the skill",
-    "   Load " + skillPath + " as the AI's instructions / rules:",
-    "   Cursor        copy SKILL.md into .cursor/rules/itemscore.md (or .cursorrules)",
-    "   Claude Code   copy SKILL.md into .claude/skills/ or append it to CLAUDE.md",
-    "   Codex         append SKILL.md to AGENTS.md",
-    "   Gemini CLI    append SKILL.md to GEMINI.md",
-    "   Anything else paste SKILL.md into the chat or system prompt",
-    "",
-    'Then just ask: "make me a sword that calls lightning on left-click".',
-    "Your AI writes a .item file; drop it in plugins/ItemsCore/imports/ and run /ic import <name>.",
-    "",
-  ].join("\n"))
+function manualLines() {
+  return [
+    "  Add this to your AI client's MCP config (same for Claude, Cursor, Gemini):",
+    '    {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}',
+    "  Codex (~/.codex/config.toml):",
+    "    [mcp_servers.itemscore]",
+    '    command = "npx"',
+    '    args = ["-y","itemscore-helper","serve"]',
+    "  No MCP client? A hosted copy is at " + HOSTED_URL + " (guide: " + LLMS_URL + ").",
+  ]
+}
+
+function runInstall(dryRun) {
+  const targetDir = path.resolve(process.cwd(), "itemscore-helper")
+  if (!dryRun) copyDir(SKILL_DIR, targetDir)
+
+  const results = autoConfigure({ dryRun })
+  const configured = results.filter((r) => r.ok)
+
+  const out = ["", dryRun ? "ItemsCore helper - dry run (nothing was changed):" : "ItemsCore helper installed.", ""]
+
+  if (configured.length > 0) {
+    out.push(dryRun ? "Would connect the ItemsCore MCP server to:" : "Connected the ItemsCore MCP server to:")
+    for (const r of results) {
+      if (r.ok) out.push("  + " + r.name + (r.already ? " (already set)" : "") + "  ->  " + r.file)
+      else out.push("  ! " + r.name + " skipped: " + r.reason)
+    }
+    if (!dryRun) {
+      out.push("")
+      out.push("Restart your AI app, then just ask it to build an ItemsCore item.")
+      out.push("A backup of each changed file was saved beside it (*.itemscore-bak).")
+    }
+  } else {
+    out.push("No AI tool configs were detected on this machine. Two easy options:")
+    out.push("")
+    out.push("  1. Paste this prompt into your AI and it sets itself up:")
+    out.push("")
+    out.push(SETUP_PROMPT.split("\n").map((l) => "     " + l).join("\n"))
+    out.push("")
+    out.push("  2. Or add the MCP server to your AI client's config yourself:")
+    out.push(...manualLines())
+  }
+
+  if (!dryRun) {
+    out.push("")
+    out.push("Skill files written to " + targetDir + " - hand SKILL.md to your AI if it asks for guidance.")
+  }
+  out.push("")
+  console.log(out.join("\n"))
 }
 
 function main() {
@@ -135,9 +140,7 @@ function main() {
     process.exitCode = 1
     return
   }
-  const targetDir = path.resolve(process.cwd(), args.dir)
-  copyDir(SKILL_DIR, targetDir)
-  printGuide(targetDir)
+  runInstall(args.dryRun)
 }
 
 main()

package/bin/mcp.js

@@ -106,7 +106,7 @@ async function main() {
     {
       title: "Validate an ItemsCore item",
       description:
-        "Validate a clean item JSON object against the ItemsCore schema. Reports errors (must fix) and warnings (likely fine). Run this before giving the user a .item file.",
+        "Validate a clean item JSON object against the ItemsCore schema. Reports errors (must fix) and warnings (likely fine). Run this before giving the user a .import file.",
       inputSchema: { item: z.unknown().describe("The clean item JSON object to validate") },
     },
     async ({ item }) => jsonResult(M.validateItem(idx, item))

package/data/itemscore-api.json

@@ -352,7 +352,7 @@
           "returnsValue": true,
           "useless": false,
           "documented": true,
-          "description": "Builds a movement equation (using 't' for time) used to shape custom projectile paths.",
+          "description": "Builds a movement equation (using 't' for time in ticks) that shapes a custom projectile path. Axes are relative to the shooter's facing: X = forward (the way they look), Y = up, Z = left. A normal forward-flying projectile puts the motion on X, e.g. createEquationVector(\"t * 0.4\", \"0\", \"0\"); use Y for arc and Z to curve sideways.",
           "category": "Projectiles",
           "example": "core.createEquationVector(\"cos(t)\", \"0\", \"sin(t)\")"
         },
@@ -2509,7 +2509,7 @@
           "returnsValue": false,
           "useless": false,
           "documented": true,
-          "description": "Fires a custom ItemsCore projectile from a player, following the given path equation for a set number of ticks.",
+          "description": "Fires a custom ItemsCore projectile from a player, following the given path equation for a set number of ticks. The equation axes are relative to where the player looks: X is forward, Y is up, Z is left - so a straight forward shot puts the motion on X.",
           "category": "Projectiles",
           "example": "core.shootProjectile(player, player.getEyeLocation(), \"FIREBALL\", null, 60, true, core.createEquationVector(\"t\", \"0\", \"t\"))"
         },

package/lib/install.js

@@ -0,0 +1,113 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+const os = require("os")
+
+const ENTRY = { command: "npx", args: ["-y", "itemscore-helper", "serve"] }
+const TOML_BLOCK = '\n[mcp_servers.itemscore]\ncommand = "npx"\nargs = ["-y", "itemscore-helper", "serve"]\n'
+
+function homeDir() {
+  return process.env.ITEMSCORE_HOME_OVERRIDE || os.homedir()
+}
+
+function backup(file) {
+  const bak = file + ".itemscore-bak"
+  if (fs.existsSync(file) && !fs.existsSync(bak)) {
+    try {
+      fs.copyFileSync(file, bak)
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+function mergeJsonMcp(file, key) {
+  let data = {}
+  if (fs.existsSync(file)) {
+    const txt = fs.readFileSync(file, "utf8").trim()
+    if (txt) {
+      try {
+        data = JSON.parse(txt)
+      } catch {
+        return { ok: false, reason: "existing config is not valid JSON; left untouched" }
+      }
+    }
+  }
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return { ok: false, reason: "existing config is not a JSON object; left untouched" }
+  }
+  if (!data[key] || typeof data[key] !== "object") data[key] = {}
+  const already = JSON.stringify(data[key].itemscore) === JSON.stringify(ENTRY)
+  data[key].itemscore = ENTRY
+  backup(file)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n")
+  return { ok: true, already }
+}
+
+function appendTomlMcp(file) {
+  const txt = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : ""
+  if (txt.includes("[mcp_servers.itemscore]")) return { ok: true, already: true }
+  backup(file)
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const next = txt.trim() ? txt.trimEnd() + "\n" + TOML_BLOCK : TOML_BLOCK.replace(/^\n/, "")
+  fs.writeFileSync(file, next)
+  return { ok: true, already: false }
+}
+
+function globalTargets() {
+  const h = homeDir()
+  const list = [
+    { name: "Cursor", dir: path.join(h, ".cursor"), file: path.join(h, ".cursor", "mcp.json"), kind: "json", key: "mcpServers" },
+    { name: "Codex", dir: path.join(h, ".codex"), file: path.join(h, ".codex", "config.toml"), kind: "toml" },
+    { name: "Gemini CLI", dir: path.join(h, ".gemini"), file: path.join(h, ".gemini", "settings.json"), kind: "json", key: "mcpServers" },
+    { name: "Windsurf", dir: path.join(h, ".codeium", "windsurf"), file: path.join(h, ".codeium", "windsurf", "mcp_config.json"), kind: "json", key: "mcpServers" },
+  ]
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || path.join(h, "AppData", "Roaming")
+    list.push({ name: "Claude Desktop", dir: path.join(appData, "Claude"), file: path.join(appData, "Claude", "claude_desktop_config.json"), kind: "json", key: "mcpServers" })
+  } else if (process.platform === "darwin") {
+    list.push({ name: "Claude Desktop", dir: path.join(h, "Library", "Application Support", "Claude"), file: path.join(h, "Library", "Application Support", "Claude", "claude_desktop_config.json"), kind: "json", key: "mcpServers" })
+  } else {
+    list.push({ name: "Claude Desktop", dir: path.join(h, ".config", "Claude"), file: path.join(h, ".config", "Claude", "claude_desktop_config.json"), kind: "json", key: "mcpServers" })
+  }
+  return list
+}
+
+function isProjectDir(cwd) {
+  return [".git", "package.json", ".cursor", ".claude", ".vscode"].some((m) => fs.existsSync(path.join(cwd, m)))
+}
+
+function applyTarget(t, dryRun) {
+  if (dryRun) return { name: t.name, file: t.file, ok: true, already: false, dry: true }
+  const r = t.kind === "json" ? mergeJsonMcp(t.file, t.key) : appendTomlMcp(t.file)
+  return { name: t.name, file: t.file, ...r }
+}
+
+/**
+ * Detects installed AI tools and writes the itemscore MCP server into each one's
+ * config (creating a backup first). Returns a list describing what happened.
+ */
+function autoConfigure(opts) {
+  opts = opts || {}
+  const dryRun = !!opts.dryRun
+  const cwd = opts.cwd || process.cwd()
+  const results = []
+
+  for (const t of globalTargets()) {
+    const present = fs.existsSync(t.dir) || fs.existsSync(t.file)
+    if (!present) continue
+    results.push({ scope: "global", ...applyTarget(t, dryRun) })
+  }
+
+  // Project-scoped .mcp.json for Claude Code, VS Code and project-level Cursor.
+  if (isProjectDir(cwd)) {
+    const file = path.join(cwd, ".mcp.json")
+    results.push({ scope: "project", name: "Project (.mcp.json)", file, ...(dryRun ? { ok: true, dry: true } : mergeJsonMcp(file, "mcpServers")) })
+  }
+
+  return results
+}
+
+module.exports = { autoConfigure, globalTargets, isProjectDir, ENTRY }

package/lib/manifest.js

@@ -88,6 +88,123 @@ function getMethod(idx, name, binding) {
   return out
 }
 
+const NUMERIC_TYPES = new Set([
+  "int", "long", "double", "float", "short", "byte",
+  "Integer", "Long", "Double", "Float", "Short", "Byte", "Number",
+])
+
+// Object types that cause a hard ClassCastException when mismatched (cannot be coerced at runtime).
+// Mismatching any of these against each other, or against a primitive/literal, is a real bug.
+const HARD_OBJECT_TYPES = new Set(["Location", "ParticleDisplay", "Vector", "World"])
+
+// Return types of the few bukkit getters agents use constantly. Lets us catch a swap even when one
+// side is a raw Spigot call (e.g. player.getLocation()) that is not in the manifest.
+const BUKKIT_GETTER_RETURNS = {
+  getlocation: "Location",
+  geteyelocation: "Location",
+  getworld: "World",
+  getdirection: "Vector",
+  getvelocity: "Vector",
+}
+
+// A handful of action variables whose type we know for sure.
+const KNOWN_VARIABLE_TYPES = {
+  landlocation: "Location",
+  lastlocation: "Location",
+}
+
+function simpleType(t) {
+  if (!t) return ""
+  const dot = t.lastIndexOf(".")
+  return dot >= 0 ? t.slice(dot + 1) : t
+}
+
+// Returns a description of what an argument produces, as { kind, type? }.
+// kind is one of: "unknown", "string", "number", "boolean", "type".
+function producedType(idx, arg) {
+  if (arg === null) return { kind: "unknown" }
+  if (typeof arg === "string") return { kind: "string" }
+  if (typeof arg === "number") return { kind: "number" }
+  if (typeof arg === "boolean") return { kind: "boolean" }
+  if (typeof arg !== "object") return { kind: "unknown" }
+
+  if (typeof arg.var === "string") {
+    const known = KNOWN_VARIABLE_TYPES[arg.var.toLowerCase()]
+    return known ? asProduced(known) : { kind: "unknown" }
+  }
+  if (typeof arg.call === "string") {
+    const call = arg.call
+    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 === 1 && found[0].returns && found[0].returns !== "void") {
+          return asProduced(found[0].returns)
+        }
+        return { kind: "unknown" }
+      }
+      const getter = BUKKIT_GETTER_RETURNS[method.toLowerCase()]
+      return getter ? asProduced(getter) : { kind: "unknown" }
+    }
+    return { kind: "unknown" }
+  }
+  return { kind: "unknown" }
+}
+
+function asProduced(simpleName) {
+  const s = simpleType(simpleName)
+  if (NUMERIC_TYPES.has(s)) return { kind: "number" }
+  if (s === "boolean" || s === "Boolean") return { kind: "boolean" }
+  if (s === "String" || s === "CharSequence") return { kind: "string" }
+  return { kind: "type", type: s }
+}
+
+// Conservative: returns true unless the arg is a definite, uncoercible mismatch.
+function argCompatible(expectedRaw, produced) {
+  const expected = simpleType(expectedRaw)
+  if (!expected || expected === "Object") return true
+  if (produced.kind === "unknown") return true
+
+  if (expected === "String" || expected === "CharSequence") return true
+  if (NUMERIC_TYPES.has(expected)) {
+    if (produced.kind === "type") return NUMERIC_TYPES.has(produced.type)
+    return true
+  }
+  if (expected === "boolean" || expected === "Boolean") {
+    if (produced.kind === "type") return false
+    return true
+  }
+  if (HARD_OBJECT_TYPES.has(expected)) {
+    if (produced.kind === "type") return produced.type === expected || !HARD_OBJECT_TYPES.has(produced.type)
+    return false
+  }
+  return true
+}
+
+function describeProduced(produced) {
+  if (produced.kind === "type") return produced.type
+  if (produced.kind === "string") return "string"
+  if (produced.kind === "number") return "number"
+  if (produced.kind === "boolean") return "boolean"
+  return "value"
+}
+
+function validateArgs(idx, method, args, p, errors) {
+  if (!method || !Array.isArray(method.params) || !Array.isArray(args)) return
+  for (let i = 0; i < args.length && i < method.params.length; i++) {
+    const param = method.params[i]
+    const expected = param.type || param.jvmType
+    const produced = producedType(idx, args[i])
+    if (!argCompatible(expected, produced)) {
+      errors.push(
+        p + '.args[' + i + '] (parameter "' + param.name + '") expects ' + simpleType(expected) +
+        " but a " + describeProduced(produced) + " was passed. Check the argument order against the method signature: " + method.signature
+      )
+    }
+  }
+}
+
 function validateStep(idx, step, p, errors, warnings) {
   if (typeof step !== "object" || step === null) {
     errors.push(p + " must be an object")
@@ -105,8 +222,14 @@ function validateStep(idx, step, p, errors, warnings) {
       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 (found[0].useless) {
+          warnings.push(p + '.call "' + call + '" is flagged useless (no real effect)')
+        }
+        // Only type-check when the method is unambiguous (one overload) so we never guess wrong.
+        if (found.length === 1 && Array.isArray(step.args)) {
+          validateArgs(idx, found[0], step.args, p, errors)
+        }
       }
     } 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')
@@ -144,6 +267,9 @@ function validateItem(idx, item) {
         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 (action.cooldown !== undefined && typeof action.cooldown !== "string" && typeof action.cooldown !== "number") {
+          warnings.push(ap + '.cooldown should be a duration like "5s", "1m", "1h" or a number of seconds')
+        }
         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))
       })
@@ -181,6 +307,7 @@ function itemSchema(idx) {
     action: {
       trigger: "string (required) - one of: " + idx.TRIGGER_NAMES.join(", "),
       needBlock: "BOTH | AIR | BLOCK - optional per-action override",
+      cooldown: 'optional - per-player reuse delay for this action. Any duration: a number plus a unit s/m/h, e.g. "5s", "45s", "2m", "90s", "1h" (a bare number means seconds). Omit or "0" for no cooldown.',
       steps: "Step[] - executed in order, combined by operatorToNext",
     },
     step: {
@@ -193,6 +320,8 @@ function itemSchema(idx) {
     },
     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.",
+    projectiles:
+      'For core.shootProjectile + core.createEquationVector the equation axes are relative to where the player looks: X = forward, Y = up, Z = left. A straight forward-flying projectile puts the motion on X, e.g. core.createEquationVector("t * 0.4", "0", "0"). Use Y for arc/gravity and Z to curve sideways.',
     bindings: idx.bindings.map((b) => ({ name: b.name, description: b.description || "", methodCount: (b.methods || []).length })),
     variables: idx.variables,
     triggers: idx.triggers,

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "1.2.1",
+  "description": "One command sets up any AI (Claude, Codex, Cursor, Gemini, and others) to build and edit custom Minecraft items for the ItemsCore plugin. Auto-detects your AI tools and connects a local MCP server that runs entirely on your machine.",
   "bin": {
     "itemscore-helper": "bin/cli.js",
     "itemscore-mcp": "bin/mcp.js"
@@ -28,10 +28,10 @@
     "codex",
     "gemini"
   ],
-  "homepage": "https://www.coredevelopment.shop/docs/items-core",
+  "homepage": "https://www.coredevelopment.shop/docs/itemscore",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Tc554/itemscore-helper.git"
+    "url": "https://github.com/Core-Pluginss/ItemsCore-Helper.git"
   },
   "license": "MIT",
   "author": "TastyCake",

package/skill/ITEM_FORMAT.md

@@ -31,6 +31,7 @@ This is the offline reference for the item format ItemsCore imports. When the li
 |---|---|---|
 | `trigger` | string, required | One of the triggers below |
 | `needBlock` | `BOTH` \| `AIR` \| `BLOCK` | Optional per-action override of the item default |
+| `cooldown` | duration string | Optional per-player reuse delay. Any duration: a number plus a unit s/m/h, e.g. `"5s"`, `"45s"`, `"2m"`, `"90s"`, `"1h"` (a bare number means seconds) |
 | `steps` | Step[] | Run in order, combined by each step's `operatorToNext` |
 
 ### Triggers
@@ -131,6 +132,10 @@ These are not in the `core` / `particles` / `values` / `api` method list. For th
 
 Always confirm a method's exact name and parameters with `get_method` / `search_methods` before using it. Do not guess.
 
+## Projectiles
+
+`core.shootProjectile` and `core.createEquationVector` use a movement equation whose axes are relative to where the player looks: **X = forward, Y = up, Z = left**. A straight forward-flying projectile puts the motion on X, e.g. `core.createEquationVector("t * 0.4", "0", "0")`. Use Y for arc/gravity and Z to curve left/right.
+
 ## Worked example: a healing ability wand
 
 ```json

package/skill/SKILL.md

@@ -9,7 +9,7 @@ ItemsCore is a Minecraft (Bukkit/Spigot) plugin that lets a server owner create
 
 ## 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.
+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)
 
@@ -86,7 +86,7 @@ Run `validate_item` on your JSON. Fix every entry under `errors` before continui
 
 ## Step 4: Hand it to the user
 
-1. Save the JSON as `<name>.item` (or `<name>.json`).
+1. Save the JSON as `<name>.import` (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.