itemscore-helper 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TastyCake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# 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.
+
+```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.
+
+## What it sets up
+
+1. **The skill** (`SKILL.md`) - the instructions your AI follows to author correct ItemsCore items.
+2. **A local MCP server** - runs on your machine (no account, no hosting, works offline) so your AI can look up the exact methods, triggers, and item schema and validate an item before you use it.
+
+The MCP server is `npx -y itemscore-helper serve`. It speaks the standard stdio MCP transport, which every MCP client supports.
+
+## Commands
+
+| 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 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 |
+| `npx itemscore-helper help` | Show help |
+
+## Connecting your AI (any provider)
+
+Add the local MCP server. The config is the same everywhere: run `npx -y itemscore-helper serve`.
+
+**Cursor** - `.cursor/mcp.json`
+```json
+{ "mcpServers": { "itemscore": { "command": "npx", "args": ["-y", "itemscore-helper", "serve"] } } }
+```
+
+**Claude Code** - `.mcp.json` in your project (or `claude_desktop_config.json` for Claude Desktop)
+```json
+{ "mcpServers": { "itemscore": { "command": "npx", "args": ["-y", "itemscore-helper", "serve"] } } }
+```
+
+**Gemini CLI** - `~/.gemini/settings.json`
+```json
+{ "mcpServers": { "itemscore": { "command": "npx", "args": ["-y", "itemscore-helper", "serve"] } } }
+```
+
+**Codex** - `~/.codex/config.toml`
+```toml
+[mcp_servers.itemscore]
+command = "npx"
+args = ["-y", "itemscore-helper", "serve"]
+```
+
+### Use your server's exact API (optional)
+
+By default the server ships with a snapshot of the standard ItemsCore API. If you use addons that add methods, run `/ic exportapi` in-game and point the server at the generated file so it knows your exact API:
+
+- set an env var `ITEMSCORE_API=/path/to/plugins/ItemsCore/itemscore-api.json`, or
+- add `"--manifest", "/path/to/itemscore-api.json"` to the `args`.
+
+### Prefer not to install anything?
+
+A hosted copy of the same server is also available (no install): `https://www.coredevelopment.shop/api/mcp` (Streamable HTTP), with `https://www.coredevelopment.shop/llms.txt` as a plain-text guide.
+
+After connecting, give your AI the `SKILL.md` file as its instructions (paste it into the chat, or add it to `.cursorrules` / `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`).
+
+## How you use it
+
+1. Ask your AI for an item.
+2. It writes a small `.item` (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.
+
+To edit an existing item, run `/ic export <name>`, share the exported file with your AI, and re-import the result.
+
+## Links
+
+- Documentation: https://www.coredevelopment.shop/docs/items-core
+- Plugin page: https://www.coredevelopment.shop/plugins/items-core
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+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 SKILL_DIR = path.join(__dirname, "..", "skill")
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true })
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name)
+    const d = path.join(dest, entry.name)
+    if (entry.isDirectory()) copyDir(s, d)
+    else fs.copyFileSync(s, d)
+  }
+}
+
+function parseArgs(argv) {
+  const out = { cmd: "install", dir: "itemscore-helper" }
+  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"
+    else rest.push(a)
+  }
+  if (rest[0]) out.cmd = rest[0]
+  return out
+}
+
+function printHelp() {
+  console.log([
+    "",
+    "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 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.",
+    "Docs: " + DOCS_URL,
+    "",
+  ].join("\n"))
+}
+
+function printMcp() {
+  console.log(
+    JSON.stringify(
+      { mcpServers: { itemscore: { command: "npx", args: ["-y", "itemscore-helper", "serve"] } } },
+      null,
+      2
+    )
+  )
+}
+
+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 main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.cmd === "serve") {
+    require("./mcp.js")
+    return
+  }
+  if (args.cmd === "help") return printHelp()
+  if (args.cmd === "mcp") return printMcp()
+  if (args.cmd === "print") return printSkill()
+  if (args.cmd !== "install") {
+    console.error("Unknown command: " + args.cmd + "\nRun: npx itemscore-helper help")
+    process.exitCode = 1
+    return
+  }
+  const targetDir = path.resolve(process.cwd(), args.dir)
+  copyDir(SKILL_DIR, targetDir)
+  printGuide(targetDir)
+}
+
+main()

package/bin/mcp.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+"use strict"
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js")
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js")
+const { z } = require("zod")
+const M = require("../lib/manifest.js")
+
+function getManifestArg() {
+  const argv = process.argv.slice(2)
+  const i = argv.indexOf("--manifest")
+  if (i !== -1 && argv[i + 1]) return argv[i + 1]
+  return undefined
+}
+
+function jsonResult(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] }
+}
+
+async function main() {
+  const idx = M.buildIndex(M.loadManifest(getManifestArg()))
+
+  const server = new McpServer(
+    { name: "itemscore", version: String(idx.manifest.pluginVersion || "1") },
+    {
+      instructions:
+        "ItemsCore is a Minecraft (Bukkit/Spigot) plugin that lets server owners build custom RPG items with no Java. Use these tools to look up the scripting API, then author a clean item JSON (get_item_schema / generate_item_template), validate it (validate_item), and tell the user to drop it in plugins/ItemsCore/imports/ and run /ic import <file>. Items authored this way stay editable in the in-game GUI." +
+        (idx.isBundled
+          ? " (Using the bundled API snapshot. To match this server's exact API including addon methods, run /ic exportapi and point this server at the generated plugins/ItemsCore/itemscore-api.json via --manifest or the ITEMSCORE_API env var.)"
+          : " (Using the live API manifest at " + idx.source + ".)"),
+    }
+  )
+
+  server.registerTool(
+    "search_methods",
+    {
+      title: "Search ItemsCore methods",
+      description:
+        "Search the ItemsCore scripting API for methods by name, category, signature, or description. Returns matching methods across the core, particles, values and api bindings.",
+      inputSchema: {
+        query: z.string().describe("Text to search for, e.g. 'teleport', 'message', 'damage'"),
+        binding: z.enum(["core", "particles", "values", "api"]).optional().describe("Restrict to a single binding"),
+        includeUseless: z.boolean().optional().describe("Include methods flagged useless (Object-inherited or no-op)"),
+        limit: z.number().int().positive().max(200).optional(),
+      },
+    },
+    async ({ query, binding, includeUseless, limit }) => {
+      const hits = M.searchMethods(idx, { query, binding, includeUseless, limit })
+      return jsonResult({ count: hits.length, methods: hits })
+    }
+  )
+
+  server.registerTool(
+    "get_method",
+    {
+      title: "Get an ItemsCore method",
+      description:
+        "Get the full details (signature, params, return, description, example) of a specific method. Accepts 'core.teleport' or just 'teleport'.",
+      inputSchema: {
+        name: z.string().describe("Method name, optionally prefixed with its binding, e.g. 'core.teleport'"),
+        binding: z.enum(["core", "particles", "values", "api"]).optional(),
+      },
+    },
+    async ({ name, binding }) => {
+      const found = M.getMethod(idx, name, binding)
+      if (found.length === 0) return jsonResult({ found: false, message: 'No method named "' + name + '" was found.' })
+      return jsonResult({ found: true, matches: found })
+    }
+  )
+
+  server.registerTool(
+    "list_triggers",
+    {
+      title: "List ItemsCore triggers",
+      description:
+        "List every action trigger (when an item's actions can run, e.g. leftAction, rightAction) and the variables available inside each.",
+      inputSchema: {},
+    },
+    async () => jsonResult({ count: idx.triggers.length, triggers: idx.triggers })
+  )
+
+  server.registerTool(
+    "list_events",
+    {
+      title: "List ItemsCore events and variables",
+      description:
+        "List the custom events and the global scripting variables (player, event, core, particles, etc.) available when writing item actions.",
+      inputSchema: {},
+    },
+    async () => jsonResult({ events: idx.events, variables: idx.variables, bindings: idx.BINDING_NAMES })
+  )
+
+  server.registerTool(
+    "get_item_schema",
+    {
+      title: "Get the ItemsCore item JSON schema",
+      description:
+        "Get the full schema and field reference for the clean item JSON that ItemsCore imports. Read this before authoring or editing an item.",
+      inputSchema: {},
+    },
+    async () => jsonResult(M.itemSchema(idx))
+  )
+
+  server.registerTool(
+    "validate_item",
+    {
+      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.",
+      inputSchema: { item: z.unknown().describe("The clean item JSON object to validate") },
+    },
+    async ({ item }) => jsonResult(M.validateItem(idx, item))
+  )
+
+  server.registerTool(
+    "generate_item_template",
+    {
+      title: "Generate an ItemsCore item template",
+      description:
+        "Return a valid starter item JSON to build from. kind can be 'basic' (a sword that greets the server on left-click) or 'ability' (a wand triggered on right-click).",
+      inputSchema: { kind: z.enum(["basic", "ability"]).optional() },
+    },
+    async ({ kind }) => jsonResult(M.generateItemTemplate(kind))
+  )
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+main().catch((e) => {
+  process.stderr.write("itemscore-helper MCP server failed to start: " + (e && e.stack ? e.stack : e) + "\n")
+  process.exit(1)
+})