universal-game-modder 0.1.4

package/ACCEPTABLE_USE.md

@@ -0,0 +1,49 @@
+# Acceptable Use Policy
+
+**Universal Game Modder ("UGM") -- free open-core edition**
+
+UGM is a general-purpose, offline binary-analysis and interoperability toolkit. Like a hex
+editor or a disassembler, what it does is neutral; what it is used for is not. This policy
+states the line. If you cannot honor it, do not install UGM.
+
+## Permitted
+
+- Modding, save editing and configuration changes to **single-player or offline** software
+  that **you legally own**, on your own machine.
+- Reverse engineering for **interoperability** -- making programs, mods, tools or file
+  formats work together -- in the sense protected by 17 U.S.C. 1201(f) and similar law.
+- **Security research and education** on software you own or are authorized to test,
+  including coursework, CTFs, and responsible-disclosure work under a published policy or a
+  written engagement.
+- Preservation, accessibility and personal backup work on software you own.
+
+## Prohibited
+
+- Defeating, removing or bypassing **copy protection, licensing checks or DRM** to obtain
+  or distribute software you have not paid for.
+- Tampering with **online, multiplayer or competitive** systems: anti-cheat evasion,
+  cheating against other players, manipulating leaderboards, economies or matchmaking, or
+  interfering with a service's integrity.
+- **Redistributing** decrypted, extracted or modified proprietary assets, code or data that
+  you do not have the right to redistribute.
+- Analyzing or modifying software you **do not own and are not authorized** to analyze.
+- Building malware, exploiting third parties, or any use that breaks the law where you are.
+- Any use that violates the EULA or terms of service of the software or platform involved,
+  where that violation would harm other people or the service.
+
+## How this is enforced
+
+It is not, technically. UGM has no telemetry, no kill switch and no way to know what you
+are doing. This policy is enforced by you. The author disclaims all responsibility for
+prohibited use (see `LICENSE-EULA.md`), and will not provide support, features or guidance
+for it.
+
+## Reporting
+
+If you believe a UGM feature exists primarily to enable a prohibited use, or you find a
+defect that makes prohibited use easier than intended, open an issue and say so. Features
+that turn out to serve only prohibited ends will be removed or moved behind a re-aim.
+
+*Last updated 2026-09-02 (v0.1.3). Rewritten after the original file was lost to a disk
+incident; the substance is unchanged: interoperability, education and personal modding of
+software you own -- nothing that harms other players, services or rights-holders.*

package/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+All notable changes to Universal Game Modder are documented here.
+This project adheres to [Semantic Versioning](https://semver.org).
+
+## [0.1.4] - 2026-09-02
+
+Packaging release for npm and the official MCP Registry. No tool behavior changes.
+
+### Added
+- `bin` entry so `npx universal-game-modder` starts the server; `#!/usr/bin/env node` on `dist/index.js`.
+- `mcpName`, `repository`, `homepage`, `bugs`, `keywords` and `files` in `package.json`.
+- `server.json` (MCP Registry manifest, schema 2025-12-11) and `llms-install.md` (agent-facing install steps).
+
+## [0.1.3] - 2026-09-02
+
+Privacy + recovery release. No tool behavior changes.
+
+### Fixed
+- **Machine-specific paths can no longer ship in the config.** The loader now resolves
+  `$UGM_CONFIG` (explicit path) -> `ugm.config.local.json` (developer/machine paths,
+  git-ignored, never in a release) -> `ugm.config.json` (the tracked file, placeholders
+  only) -> built-in defaults, merging each file over the defaults. This closes the
+  Gatekeeper privacy finding that had blocked a clean ship since 2026-06-17.
+
+### Recovered
+- On 2026-08-31 a TRIM incident zeroed this release's README, CHANGELOG, VERIFICATION,
+  LICENSE, EULA, acceptable-use policy, package.json, lock file and gate script, plus
+  21 of 39 TypeScript source files. The compiled `dist/` survived byte-intact. Docs and
+  the gate were restored from session records; LICENSE, EULA and AUP were rewritten to
+  the same terms. The full release gate was re-run on the restored cut (see
+  `VERIFICATION.md`). The TypeScript rebuild is a v0.2 task, not a ship blocker.
+
+## [0.1.2] - 2026-08-25
+
+Engine-detection correctness release. v0.1.1 passed its tool gate but misidentified two of
+the three major engines it advertises; detection is now verified against real engine layouts.
+
+### Fixed
+- **Unreal Engine games were not detected at all.** Detection looked for files literally named
+  `UE4-Win64-Shipping.exe` / `UE5-Win64-Shipping.exe`, but shipped Unreal titles name that
+  binary `<GameName>-Win64-Shipping.exe` (e.g. `Subnautica2-Win64-Shipping.exe`), so the
+  marker never matched a real game. The search was also capped at depth 2 while the binary
+  lives at `<Game>/Binaries/Win64/` (depth 3), and the `.pak` fallback required a
+  `shipping`-named exe at that same too-shallow depth. A standard Unreal install returned
+  `null` — no engine, not even `native`. Detection now globs `*-Win64-Shipping.exe`
+  (plus Win32/WinGDK variants) to depth 4 and recognizes the `Content/Paks` layout.
+- **Unity games without `UnityPlayer.dll` were reported as `native`.** All Unity detection
+  was gated behind `UnityPlayer.dll`; if it was absent, `Assembly-CSharp.dll`,
+  `GameAssembly.dll`, `global-metadata.dat` and the `*_Data` directory were never
+  examined. Unity is now identified by any of its definitive markers, and an IL2CPP build
+  whose metadata cannot be located is reported as `unity-il2cpp` (inferred) rather than
+  falling through.
+
+### Verified
+- Engine detection: 4/4 on authentic Unity Mono / Unity IL2CPP / Unreal / Godot layouts
+  (was 1/4).
+- Real Steam library sweep: 13/34 directories detected, up from 9/34, with **zero regressions**
+  — every previously-detected title resolves identically — and zero crashes. The remaining
+  undetected directories are installs stripped of game content (mod scaffolds, empty
+  `Paks`), which correctly report uncertainty rather than guessing.
+- Full release gate re-run from a true cold install: 20/20 free-edition tools returning real
+  data, 3/3 Pro backends failing cleanly.
+
+## [0.1.1] - 2026-07-27
+
+Correctness and honesty release. v0.1.0 shipped documentation that did not match the code;
+every documented call is now executed by a release gate before shipping.
+
+### Fixed
+- **Every Quickstart example in the README was wrong.** The docs told users to pass `path`,
+  but the tools require `file_path` (or `file_path_a`/`file_path_b`, `binary_path`,
+  `game_path`). All 9 documented calls failed with
+  `The "path" argument must be of type string… Received undefined`. Anyone copying the
+  README verbatim hit an immediate error. Documentation now matches the real schemas.
+- **The server announced the wrong version.** It reported `1.0.0` in the MCP handshake while
+  the package and changelog said `0.1.0`. The version is now read from `package.json`, so it
+  cannot drift again — and the release gate fails the build if it does.
+- **`jar_open` failed opaquely.** Its backend command defaults to `python` (never empty), so
+  the configuration check passed, the process spawned, and it died with
+  `MCP error -32000: Connection closed`. Unconfigured backends now report a missing script
+  path, matching the Unity and Unreal backends.
+
+### Added
+- **`verify-release.mjs`** — a pre-ship gate that executes every README-documented
+  free-edition tool against a real binary, asserts each returns recognizable data, and
+  confirms Pro-tier tools fail cleanly rather than hanging. Non-zero exit blocks a release.
+  Run it yourself: `node verify-release.mjs`.
+- **`VERIFICATION.md`** — the recorded result of the latest gate run, including the exact
+  binary analyzed and what each tool returned.
+
+### Changed
+- The README now states the honest tool inventory: **29 tools run standalone** (19 native +
+  10 workflow) out of the **100** the server lists. The other 64 route to Pro-tier backends
+  and say so explicitly, rather than appearing to be included.
+- **Native disassembly is documented as included**, not Pro-deferred — `disassemble_function`
+  and `disassemble_range` work in-process via capstone 5.0 and are verified. (The
+  `capstone-wasm` license is still being confirmed upstream; these may move tiers.)
+
+## [0.1.0] - 2026-07-12
+
+First public open-core release.
+
+### Included (free edition)
+- Stdio MCP server that an AI agent connects to and drives.
+- Game-engine auto-detection (`detect_engine`, `load_game`) — Unity Mono/IL2CPP, Unreal, Godot, Java, native.
+- Native binary analysis + patching toolset (19 in-process tools): PE analysis, hex read/write/search/replace, pattern scanning, string/class extraction, checksums, binary diffing, Godot PCK analysis. *(v0.1.0 said 22; the verified count is 19 — corrected in 0.1.1.)*
+- MIT license + buyer-responsibility EULA + Acceptable Use Policy + third-party attribution.
+- Ships from a scrubbed release set (no personal machine paths; empty-placeholder config).
+
+### Deferred to a later release
+- The `game-modder` guided-workflow skill (needs portable template resolution before shipping).
+
+### Not included (deferred to Pro tier)
+- Local web dashboard (port 7777).
+- Delegated Unity/Unreal/JAR decompilation backends.
+- Native disassembly (pending `capstone-wasm` license resolution).
+
+[0.1.0]: first release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justanotherrandomaiguy
+
+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/LICENSE-EULA.md

@@ -0,0 +1,62 @@
+# End-User Terms (Buyer Responsibility)
+
+**Universal Game Modder ("UGM") -- free open-core edition**
+
+The UGM source code is licensed under the MIT License (see `LICENSE`). These terms do not
+narrow that license. They exist to make one thing explicit before you install: **UGM is a
+dual-use binary-analysis tool, and responsibility for how it is used sits with you, the
+user, not with the author.**
+
+## 1. What UGM is
+
+UGM is a local Model Context Protocol server that gives an AI agent tools for inspecting,
+analyzing and patching software on your own machine: engine detection, PE analysis, hex
+read/write, pattern scanning, string extraction, checksums, binary diffing and native
+disassembly. It runs entirely locally. It sends nothing anywhere.
+
+## 2. Intended use
+
+UGM is provided for **modding, interoperability, security research and education on
+software you legally own or are expressly authorized to analyze.** Typical intended uses:
+personal single-player mods, save and config editing, learning how a game is built, and
+achieving interoperability between programs in the sense of 17 U.S.C. 1201(f) and
+comparable provisions elsewhere.
+
+## 3. Your responsibilities
+
+By installing or using UGM you agree that you are solely responsible for:
+
+- confirming you own or are authorized to analyze and modify any software you point UGM at;
+- reading and honoring the license, EULA and terms of service of every game, platform and
+  store that governs that software (for example the Steam Subscriber Agreement);
+- complying with the laws that apply to you, including anti-circumvention and computer-misuse
+  law in your jurisdiction;
+- the consequences of any modification you make, including bans, save corruption, or loss
+  of access to online services;
+- not using UGM in any way described in `ACCEPTABLE_USE.md` as prohibited.
+
+## 4. What the author does not do
+
+The author does not review, approve, or take responsibility for what you do with UGM, does
+not provide legal advice, and makes no representation that any particular use is lawful
+where you live. Nothing in this project's documentation is legal advice; confirm before any
+high-stakes use.
+
+## 5. No warranty
+
+UGM is provided "AS IS" with no warranty of any kind, as stated in the MIT License. Binary
+patching can damage files irreversibly. Back up anything you point it at.
+
+## 6. Third-party components
+
+Runtime dependencies and their licenses are listed in `licenses/THIRD-PARTY-NOTICES.md`.
+Each is permissive (MIT / Apache-2.0). Nothing proprietary from any game or engine is
+included in this edition.
+
+## 7. Changes to these terms
+
+These terms ship with the release they apply to. A later release may ship revised terms;
+the terms in the copy you installed are the ones that apply to that copy.
+
+*Last updated 2026-09-02 (v0.1.3). These terms were rewritten after the original file was
+lost to a disk incident; the substance is unchanged.*

package/README.md

@@ -0,0 +1,162 @@
+# Universal Game Modder
+
+**One MCP server to inspect and mod any game — driven by an AI agent.**
+
+Universal Game Modder (UGM) is a local [Model Context Protocol](https://modelcontextprotocol.io) server that gives an AI agent (like Claude in Claude Code) hands for game reverse-engineering and modding: it auto-detects a game's engine, then exposes a toolset for analyzing and patching the binaries — all running locally on your own machine, no cloud, no telemetry.
+
+This is the **free open-core edition (v0.1.3)**.
+
+---
+
+## ⚠️ Responsible-use notice
+
+UGM is a general-purpose binary-analysis and interoperability tool. It is meant for **modding, interoperability, security research, and education on software you legally own or are authorized to analyze.** You are responsible for how you use it. Before installing, read [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) and [`LICENSE-EULA.md`](LICENSE-EULA.md).
+
+---
+
+## What's in the free edition
+
+- **One stdio MCP server** that an agent connects to and drives.
+- **Game-engine auto-detection** — point it at a game directory; it identifies Unity (Mono / IL2CPP), Unreal, Godot, Java, and native binaries from file signatures.
+- **Native binary analysis + patching toolset** — PE header analysis, hex read/write/search/replace, IDA-style pattern scanning, string extraction, checksums, and binary diffing, running natively in-process (no external tools required).
+
+The guided `game-modder` workflow skill and the delegated decompilation backends land in a later release; this edition is the MCP server + engine detection + the native toolset.
+
+### Not in the free edition (Pro tier)
+
+The web dashboard, the delegated Unity/Unreal/JAR decompilation backends, and native disassembly are part of the **Pro** tier and are **not** included here. The free edition is fully functional on its own for engine detection and native binary work.
+
+---
+
+## Requirements
+
+- **Node.js 18+** (uses ES modules and `better-sqlite3`)
+- **[Claude Code](https://claude.com/claude-code)** or any MCP-capable client
+- Windows / macOS / Linux (native tools are cross-platform; the smallest cut ships no OS-specific binaries)
+
+---
+
+## Install
+
+```powershell
+# from the repo root
+./setup.ps1
+```
+
+Or manually (`dist/` ships prebuilt; there is nothing to compile in this edition):
+
+```bash
+npm install
+```
+
+Then register the server with your MCP client. For Claude Code, add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "universal-game-modder": {
+      "command": "node",
+      "args": ["dist/index.js"]
+    }
+  }
+}
+```
+
+On first run, `ugm.config.json` ships with **empty placeholders** — the free edition needs no external paths. (The Pro delegate backends are where those get filled in.)
+
+### Config resolution
+
+The server reads the first of these that exists and merges it over built-in defaults:
+
+1. the file named by the `UGM_CONFIG` environment variable
+2. `ugm.config.local.json` next to `package.json` — your machine-specific paths; keep it out of version control (the repo's `.gitignore` already does)
+3. `ugm.config.json` — the tracked file, placeholders only
+
+So you can fill in backend paths without ever editing a file that could end up in a release or a pull request.
+
+---
+
+## Quickstart
+
+Once connected, ask your agent to work through these. **Every example below is executed against a real binary before each release** — see [Verified examples](#verified-examples).
+
+> **Parameter naming:** file-level tools take **`file_path`** (and `file_path_a` / `file_path_b` for comparisons). Game-directory tools take **`game_path`**. Disassembly tools take **`binary_path`**.
+
+**1. Detect what a game is built with:**
+```
+detect_engine  { "game_path": "C:\\Path\\To\\Game" }
+```
+
+**2. Set it as the active target:**
+```
+load_game  { "game_path": "C:\\Path\\To\\Game" }
+```
+
+**3. Analyze a binary:**
+```
+analyze_file_format  { "file_path": "...\\SomeBinary.dll" }   # magic bytes, managed vs native
+analyze_pe_full      { "file_path": "...\\SomeBinary.exe" }   # PE headers, sections, data directories
+```
+
+**4. Search and inspect:**
+```
+extract_strings          { "file_path": "...", "min_length": 8 }
+extract_dll_classes      { "file_path": "...", "search_terms": ["Health","Damage"] }
+pattern_scan             { "file_path": "...", "pattern": "48 8B ?? ?? ?? ?? ??" }
+search_binary_pattern    { "file_path": "...", "patterns": ["maxHealth"] }
+```
+
+**5. Patch and verify:**
+```
+hex_read       { "file_path": "...", "offset": 4096, "length": 64 }
+hex_replace    { "file_path": "...", "search_hex": "90 90", "replace_hex": "EB 00" }
+calculate_checksums       { "file_path": "..." }              # before/after integrity
+compare_binaries_detailed { "file_path_a": "...", "file_path_b": "..." }
+```
+
+**6. Disassemble (native, included):**
+```
+disassemble_function  { "binary_path": "...\\SomeBinary.exe", "rva": 4096 }
+disassemble_range     { "binary_path": "...\\SomeBinary.exe", "rva": 4096 }
+```
+
+### Full free-edition tool list
+
+These **29 tools run entirely in-process** and need no external backend.
+
+**Native binary tools (19)** — all take `file_path` unless noted:
+Detection / PE: `analyze_pe_full`, `analyze_file_format`, `analyze_dll_structure`, `rva_to_offset` (+`rva`), `offset_to_rva` (+`offset`)
+Hex: `hex_read` (+`offset`), `hex_write` (+`offset`,`hex_data`), `hex_search` (+`hex_pattern`), `hex_replace` (+`replace_hex`)
+Scanning: `pattern_scan` (+`pattern`), `pattern_scan_all` (+`pattern`), `search_binary_pattern` (+`patterns`)
+Strings / classes: `extract_strings`, `extract_strings_advanced`, `extract_dll_classes`
+Integrity / diff: `calculate_checksums`, `compare_binaries_detailed` (`file_path_a`,`file_path_b`)
+Godot: `analyze_godot_pck`
+Disassembly: `disassemble_function` (`binary_path`,`rva`)
+
+**Workflow / session tools (10):**
+`detect_engine`, `load_game`, `game_status`, `find_steam_games`, `mod_this_game`, `find_gameplay_values`, `build_and_deploy`, `debug_mod`, `scaffold_mod`, `list_available_tools`
+
+### What the server also lists (Pro backends)
+
+For transparency: the server advertises **100 tools total**. The other **64** are the Unity (27), Unreal (11), and Java/JAR (26) decompilation suites, which **route to external Pro-tier backend executables**. They appear in the tool list, but calling one without a configured backend returns a clear error:
+
+```
+ERROR: Backend unity-decompiler not configured (missing executable path)
+```
+
+That is expected behavior in the free edition, not a defect. Configure their paths in `ugm.config.json` (Pro) to enable them.
+
+### Verified examples
+
+The Quickstart calls above are not aspirational. Each release is gated on a verification pass that executes them against a real PE binary and requires every one to return real data. The v0.1.3 pass (2026-09-02, on the restored release cut) ran the gate's 20 documented calls plus 3 clean-failure checks; results are recorded in [`VERIFICATION.md`](VERIFICATION.md).
+
+---
+
+## License
+
+The UGM code is released under the [MIT License](LICENSE). Use of the tool is additionally governed by [`LICENSE-EULA.md`](LICENSE-EULA.md) and [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md). Third-party components used by the Pro-tier backends are attributed in [`licenses/`](licenses/).
+
+## Changelog
+
+See [`CHANGELOG.md`](CHANGELOG.md). Current version: **v0.1.3** — the config can no longer ship machine paths, and the release was
+restored and re-verified after a disk incident. v0.1.2 fixed engine detection; v0.1.1 fixed the docs and added the gate.

package/VERIFICATION.md

@@ -0,0 +1,132 @@
+# Verification record — v0.1.4
+
+Every call documented in [`README.md`](README.md) is executed against a real binary before
+release. This file records the most recent run. If a documented call does not return real
+data, the build does not ship.
+
+**Run the gate yourself:**
+
+```bash
+node verify-release.mjs
+```
+
+It exits non-zero if any documented tool errors, times out, or returns data it cannot
+recognize. Point it at a different binary with `UGM_VERIFY_TARGET=/path/to/binary`.
+
+---
+
+## Last run
+
+- **Date:** 2026-09-02
+- **Version:** 0.1.3
+- **Environment:** the restored release cut, run in place after the 2026-08-31 disk incident. Dependencies resolved from the sibling dev tree's `node_modules` (not a cold install this run; the v0.1.2 cold-install result below still stands for the unchanged tool code).
+- **Config:** shipped `ugm.config.json` -- all backend paths empty, exactly as a buyer receives it. Loader order is new in 0.1.3: `UGM_CONFIG` > `ugm.config.local.json` > `ugm.config.json` > defaults.
+- **Target binary:** `C:\Windows\System32\notepad.exe`
+- **Result:** **PASS** -- 20/20 documented free-edition tools returned real data; 3/3 Pro-backend tools failed cleanly
+
+Re-run the same day on the v0.1.4 packaging tree (bin entry, shebang, server.json, llms-install.md; no tool changes): **PASS** 20/20 + 3/3; `npm pack --dry-run` = 92 files, 117 kB packed; `node dist/index.js` announces 0.1.4.
+
+Additional checks this run:
+
+| Check | Result |
+|---|---|
+| Server boots over stdio | `universal-game-modder` 0.1.3, 100 tools listed |
+| Zero-filled (disk-incident) files in the release tree | 0 remaining; 31 zeroed `.map` / `.d.ts` files purged (not needed to run) |
+| Personal or machine paths anywhere in the release tree | none (scan for username, e-mail, `C:\projects`) |
+| Tracked config files carry machine paths | no (`ugm.config.json` here and in the dev tree) |
+| Docs and gate script | restored from session records; LICENSE, EULA and AUP rewritten to the same terms |
+
+## Previous run (v0.1.2, 2026-08-25)
+
+- **Date:** 2026-08-25
+- **Version:** 0.1.2
+- **Environment:** clean install (fresh `npm install`, no dev tree on the module path)
+- **Config:** shipped `ugm.config.json` — all backend paths empty, exactly as a buyer receives it
+- **Target binary:** `C:\Windows\System32\notepad.exe` (x64 PE, 200,704 bytes)
+- **Result:** **PASS** — 20/20 documented free-edition tools returned real data; 3/3 Pro-backend tools failed cleanly
+
+### Free-edition tools verified (20/20)
+
+| Tool | Verified result |
+|---|---|
+| `analyze_file_format` | Identified PE, x64, unmanaged, 7 sections |
+| `analyze_pe_full` | Returned headers, architecture, and data directories |
+| `analyze_dll_structure` | Returned section count and structure |
+| `calculate_checksums` | Real MD5 / SHA1 / SHA256 (sha256 `da5807bb…d7c5b`) |
+| `hex_read` | Returned the `4d 5a` (MZ) header at offset 0 |
+| `hex_search` | Located the MZ pattern |
+| `pattern_scan` | 7 matches for `4D 5A` with byte context |
+| `pattern_scan_all` | Whole-file scan returned matches |
+| `extract_strings` | 645 strings extracted |
+| `extract_strings_advanced` | Filtered extraction returned data |
+| `extract_dll_classes` | Targeted name search returned data |
+| `search_binary_pattern` | Text pattern search returned data |
+| `compare_binaries_detailed` | Byte-level comparison completed |
+| `rva_to_offset` | RVA `0x1000` → file offset `0x400`, section `.text` |
+| `offset_to_rva` | Reverse mapping completed |
+| `disassemble_function` | 34 instructions, terminated on `ret` (capstone 5.0) |
+| `disassemble_range` | 60 instructions from `.text` |
+| `game_status` | Session state returned |
+| `list_available_tools` | Tool inventory returned |
+| `find_steam_games` | Library scan completed |
+
+### Pro-backend tools fail cleanly (3/3)
+
+With no backend configured, these return a clear, actionable error rather than hanging or
+crashing:
+
+| Tool | Result |
+|---|---|
+| `decompile_type` | `ERROR: Backend unity-decompiler not configured (missing executable path)` |
+| `open_game` | `ERROR: Backend unreal-assets not configured (missing executable path)` |
+| `jar_open` | `ERROR: Backend jar-editor not configured (missing script path)` |
+
+---
+
+## What this run fixed
+
+Three defects were found by building this gate and are corrected in v0.1.1:
+
+1. **Every Quickstart example in the v0.1.0 README was wrong.** The docs told buyers to pass
+   `path`; every tool requires `file_path` (or `file_path_a`/`file_path_b`, `binary_path`,
+   `game_path`). All 9 documented calls failed with
+   `The "path" argument must be of type string… Received undefined`. Documentation is now
+   generated against the real schemas and executed by this gate.
+
+2. **The server reported the wrong version.** It announced `1.0.0` in the MCP handshake while
+   the package and changelog said `0.1.0`, making it impossible to tell which build a buyer
+   was running. Now consistent.
+
+3. **`jar_open` failed opaquely.** Its backend command defaults to `python` (never empty), so
+   the "is it configured?" check passed and the process spawned and died with
+   `MCP error -32000: Connection closed`. It now reports a missing script path like the other
+   backends.
+
+## Known limits
+
+- Verification runs against a Windows PE binary. Cross-platform ELF/Mach-O paths are
+  supported by the code but are not covered by this gate.
+- The Pro-tier Unity, Unreal, and Java backends are not exercised here; this gate proves only
+  that they refuse cleanly when absent.
+- `disassemble_function` / `disassemble_range` depend on `capstone-wasm`, whose license is
+  still being confirmed upstream. They are verified working but may move tiers.
+
+---
+
+## Engine detection (added v0.1.2)
+
+Detection is verified against authentic engine directory layouts, not only against a stock
+PE binary. Prior to v0.1.2 this was never tested and two of the three advertised engines
+were misidentified.
+
+| Layout | Expected | v0.1.1 | v0.1.2 |
+|---|---|---|---|
+| Unity Mono (`*_Data/Managed/Assembly-CSharp.dll`) | `unity-mono` | `native` | `unity-mono` (verified) |
+| Unity IL2CPP (`GameAssembly.dll` + `global-metadata.dat`) | `unity-il2cpp` | `native` | `unity-il2cpp` (verified) |
+| Unreal (`<Game>-Win64-Shipping.exe` + `Content/Paks`) | `unreal` | `null` | `unreal` (verified) |
+| Godot (`*.pck`) | `godot` | `godot` | `godot` (verified) |
+
+Real-library sweep across 34 installed Steam directories: **13 detected, up from 9, with zero
+regressions and zero crashes.** Directories still reporting uncertainty are installs stripped
+of game content (mod scaffolds with the game uninstalled, empty `Paks`) — the detector
+correctly declines to guess rather than reporting a false engine.

package/dist/backends/child-pool.js

@@ -0,0 +1,91 @@
+import { McpChild } from './mcp-child.js';
+import { loadConfig } from '../core/config.js';
+import { logger } from '../utils/logger.js';
+export class ChildPool {
+    children = new Map();
+    configs;
+    // A backend is only usable if every path it needs is set. jar-editor is the
+    // special case: its `command` defaults to "python" (always non-empty), so the
+    // command check alone would let it spawn and die with an opaque transport
+    // error. Its real requirement is the script path.
+    static requiredArgIndex = {
+        'jar-editor': 0,
+    };
+    assertConfigured(backend, cfg) {
+        if (!cfg.command) {
+            throw new Error(`Backend ${backend} not configured (missing executable path)`);
+        }
+        const idx = ChildPool.requiredArgIndex[backend];
+        if (idx !== undefined && !cfg.args?.[idx]) {
+            throw new Error(`Backend ${backend} not configured (missing script path)`);
+        }
+    }
+    constructor() {
+        const config = loadConfig();
+        this.configs = new Map([
+            ['unity-decompiler', {
+                    name: 'unity-decompiler',
+                    command: config.unityDecompilerExe,
+                    args: [],
+                }],
+            ['unreal-assets', {
+                    name: 'unreal-assets',
+                    command: config.unrealAssetExe,
+                    args: [],
+                }],
+            ['jar-editor', {
+                    name: 'jar-editor',
+                    command: config.pythonExe,
+                    args: [config.jarEditorScript],
+                }],
+        ]);
+    }
+    async call(backend, toolName, args) {
+        let child = this.children.get(backend);
+        if (!child) {
+            const cfg = this.configs.get(backend);
+            if (!cfg)
+                throw new Error(`Unknown backend: ${backend}`);
+            this.assertConfigured(backend, cfg);
+            child = new McpChild(cfg);
+            this.children.set(backend, child);
+        }
+        return child.callTool(toolName, args);
+    }
+    async listToolsFor(backend) {
+        let child = this.children.get(backend);
+        if (!child) {
+            const cfg = this.configs.get(backend);
+            if (!cfg)
+                throw new Error(`Unknown backend: ${backend}`);
+            this.assertConfigured(backend, cfg);
+            child = new McpChild(cfg);
+            this.children.set(backend, child);
+        }
+        return child.listTools();
+    }
+    getStatus() {
+        const status = {};
+        for (const [name, cfg] of this.configs) {
+            const child = this.children.get(name);
+            status[name] = {
+                connected: child?.isConnected ?? false,
+                configured: !!cfg.command,
+            };
+        }
+        return status;
+    }
+    async closeAll() {
+        for (const [name, child] of this.children) {
+            try {
+                await child.close();
+            }
+            catch (err) {
+                logger.error(`Error closing child ${name}`, err);
+            }
+        }
+        this.children.clear();
+    }
+}
+export const childPool = new ChildPool();
+//# sourceMappingURL=child-pool.js.map