itemscore-helper 1.0.0 → 1.2.0

package/README.md

@@ -1,12 +1,24 @@
 # 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: let your AI set itself up
+
+Run this, copy what it prints, and paste it into your AI (Claude, Cursor, Gemini, Codex, anything):
+
+```bash
+npx itemscore-helper prompt
+```
+
+Your AI reads the prompt, sets up the ItemsCore tools itself, then asks what item you want. No config files, no terminal knowledge needed.
+
+## 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 +31,9 @@ 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 prompt` | Print a prompt to paste into your AI so it sets itself up |
+| `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 |
@@ -76,8 +89,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 = [
+  "Help me build a custom item for my Minecraft server with the ItemsCore plugin. Set yourself up first, then we'll build it together.",
+  "",
+  "1. Fetch and read " + LLMS_URL + " - it explains how ItemsCore items work, the item JSON format, and every method you can use.",
+  "",
+  "2. Set up the ItemsCore tools so you can look up methods and validate items for me. In my project folder, run:",
+  "   npx -y itemscore-helper install",
+  '   Then reload your MCP servers (or restart this app) so the "itemscore" tools appear. If you cannot run commands, add this to your MCP config instead:',
+  '   {"mcpServers":{"itemscore":{"command":"npx","args":["-y","itemscore-helper","serve"]}}}',
+  "",
+  "3. Once you are set up, tell me you are ready and ask what item I want. Write a valid .item file, validate it, then tell me to drop it in plugins/ItemsCore/imports/ and run /ic import. 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,16 @@ 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 prompt     Print a prompt to paste into your AI so it sets itself up",
+    "  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.",
+    "Zero terminal? Run `npx itemscore-helper prompt`, copy it, and paste it into your AI - it sets itself up.",
+    "Supports Claude (Code & Desktop), Cursor, Gemini CLI, Codex, Windsurf and any MCP client.",
     "Docs: " + DOCS_URL,
     "",
   ].join("\n"))
@@ -55,11 +68,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 +76,59 @@ 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 printPrompt() {
+  console.log(SETUP_PROMPT)
+}
+
+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() {
@@ -129,15 +139,14 @@ function main() {
   }
   if (args.cmd === "help") return printHelp()
   if (args.cmd === "mcp") return printMcp()
+  if (args.cmd === "prompt") return printPrompt()
   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)
+  runInstall(args.dryRun)
 }
 
 main()

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/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.0",
+  "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,7 +28,7 @@
     "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"