UMDGenCLI MCP Server

An MCP (Model Context Protocol) server that lets AI agents drive UMDGenCLI — the command-line tool for creating and editing PSP UMD images (ISO / CSO / DAX). Every major function of UMDGenCLI is exposed as a dedicated tool, so agents can build compilations, save images, convert formats, patch, extract, and inspect without learning the CLI syntax.

Requirements

• Node.js 18+ (developed and tested on Node 22 / Windows)
• The UMDGenCLI executable (umdgen-win-x64.exe / umdgen-win-x86.exe / umdgen.exe), from the GitHub Releases page

Setup

npm install
npm run build   # compiles TypeScript into dist/

Installing from npm (other PCs)

The server is published as the umdgencli-mcp npm package. On any machine with Node.js, install it globally (or use npx), then point an MCP client at the umdgen-mcp binary with the UMDGENCLI_PATH env var set to that machine's UMDGenCLI executable:

npm install -g umdgencli-mcp

{
  "mcpServers": {
    "umdgencli": {
      "command": "umdgen-mcp",
      "env": {
        "UMDGENCLI_PATH": "C:\\tools\\umdgen.exe",
        "UMDGENCLI_CWD": "C:\\workspace\\psp-images"
      }
    }
  }
}

No local build or install step is needed — the published package contains the compiled server (dist/). The UMDGenCLI executable itself is not bundled; it must exist on the target machine (it's self-contained, so no .NET runtime is needed there either).

Configuration

The server is configured entirely through environment variables:

Variable	Required	Default	Description
UMDGENCLI_PATH	yes	—	Path to the UMDGenCLI executable. The server refuses to start without it.
UMDGENCLI_STATE_FILE	no	<cwd>/.umdgen-mcp/umdgen.state	Path of the persistent compilation state file. UMDGenCLI keeps the in-memory compilation (folder/file tree + volume metadata) in this file between invocations, so a compilation can be built up across many tool calls.
UMDGENCLI_CWD	no	server working directory	Working directory for the CLI subprocess. Relative paths in tool arguments (source files, output images) resolve against this.

The server starts the CLI as a subprocess per tool call with --state <file> prepended automatically. Call umdgen_reset_session to discard the current compilation, and umdgen_get_session to see the active configuration.

Registering with an MCP client

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "umdgencli": {
      "command": "node",
      "args": ["H:\\path\\to\\UMDGenCLI MCP\\dist\\server.js"],
      "env": {
        "UMDGENCLI_PATH": "H:\\path\\to\\umdgen.exe",
        "UMDGENCLI_CWD": "H:\\workspace\\psp-images"
      }
    }
  }
}

Kilo (kilo.json)

{
  "mcp": {
    "umdgencli": {
      "type": "stdio",
      "command": "node",
      "args": ["H:/path/to/UMDGenCLI MCP/dist/server.js"],
      "env": {
        "UMDGENCLI_PATH": "H:/path/to/umdgen.exe",
        "UMDGENCLI_CWD": "H:/workspace/psp-images"
      }
    }
  }
}

Cursor / generic

Any client that supports stdio MCP servers works the same way: run node <path-to-repo>/dist/server.js with the environment variables above.

Tools

All tools are prefixed with umdgen_ (per MCP naming conventions, to avoid collisions with tools from other MCP servers). All tools return the CLI's stdout/stderr plus the process exit code; a non-zero exit code is surfaced as an error result (isError: true). Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can show accurate approval prompts — e.g. umdgen_set_version is marked destructive when patching in place, and umdgen_reset_session / umdgen_new_compilation discard unsaved work. Outputs longer than 25,000 characters are truncated with a message telling the agent how to narrow the result.

Session & environment

Tool	Description
umdgen_get_session	Show executable path, state file, working directory
umdgen_reset_session	Delete the state file and start a fresh compilation
umdgen_get_version	Print the UMDGenCLI version
umdgen_get_help	Show help (optionally for one command)
umdgen_run_raw	Escape hatch: run any command with raw arguments

Compilation building

Tool	CLI equivalent
umdgen_new_compilation	new (label, padding, pad, no-pathtables, date)
umdgen_open_image	open <image>
umdgen_add_file	add-file <src...> [--to <dir>]
umdgen_add_folder	add-folder <src...> [--to <dir>]
umdgen_new_folder	new-folder <name> [--to <dir>]
umdgen_rename_item	rename <path> <newname>
umdgen_delete_items	delete <path...>
umdgen_hide_items / umdgen_unhide_items	hide / unhide <path...>
umdgen_dummy_items	dummy <path...>
umdgen_dummy_search	dummy-search [image]
umdgen_optimize_image	optimize [image]
umdgen_relink_files / umdgen_relink_source	relink / relink-source
umdgen_move_lba	move-lba <file> <lba>
umdgen_set_label	set-label <label>
umdgen_set_date	set-date <yyyy-MM-dd>
umdgen_gen_umddata	gen-umddata [path]

Display

Tool	CLI equivalent
umdgen_list_contents	list [image]
umdgen_show_tree	tree [image]
umdgen_show_props	props [image]

Image operations

Tool	CLI equivalent
umdgen_image_info	info <image>
umdgen_dump_sfo	sfo <image>
umdgen_set_version	set-version <image> <version> [--out]
umdgen_save_image	save <out> (+ format, level, nc, padding, pad)
umdgen_extract_image	extract <image> <outdir> [paths...]
umdgen_convert_image	convert <in> <out> (+ format, level, nc)
umdgen_batch_convert	batch <outdir> <iso|cso|dax> <images...>
umdgen_apply_ppf	ppf-apply <image> <patch.ppf> [--file] [--out]
umdgen_export_iml / umdgen_import_iml	iml-export / iml-import
umdgen_create_image	create <dir> <out> (one-shot build from a folder)
umdgen_verify_image	verify <image>

Agent workflow example

umdgen_get_session                    # confirm executable + state file
umdgen_reset_session                  # start clean
umdgen_new_compilation { label: "GAME001", padding: "umd" }
umdgen_new_folder { name: "PSP_GAME" }
umdgen_new_folder { name: "SYSDIR", to: "PSP_GAME" }
umdgen_add_file { src: ["EBOOT.BIN"], to: "PSP_GAME/SYSDIR" }
umdgen_add_file { src: ["PARAM.SFO"], to: "PSP_GAME" }
umdgen_list_contents                  # review the compilation
umdgen_save_image { out: "GAME001.iso", padding: "umd" }
umdgen_image_info { image: "GAME001.iso" }  # inspect the result
umdgen_convert_image { input: "GAME001.iso", output: "GAME001.cso" }

Notes

• Paths: relative paths in tool arguments resolve against UMDGENCLI_CWD (or the server's working directory). Agents should prefer absolute paths for source files and outputs.
• add-file reads source data at save time: the on-disk source files must still exist when save_image runs.
• iml-import only relocates existing files: open the image (or build the compilation) first, then import the IML to apply the listed LBA layout.
• set-version and ppf-apply require raw ISOs; CSO/DAX inputs are rejected by UMDGenCLI itself.
• --padding umd reproduces UMDGen v4.00's output byte-for-byte; the default is no padding.

Tests

test/run-tests.mjs is an end-to-end suite that spawns the server over stdio, builds a compilation from generated fixtures (including a valid PARAM.SFO), and exercises every tool against a real UMDGenCLI executable:

$env:UMDGENCLI_PATH = "H:\path\to\umdgen.exe"
node test\run-tests.mjs

Evaluation

test/evaluation.xml contains 10 read-only, independent, verifiable questions designed to measure how well an agent can use the server with no other context. The corpus is deterministic:

$env:UMDGENCLI_PATH = "H:\path\to\umdgen.exe"
npm run eval:fixtures   # builds test/eval/work/eval1.iso, eval2.iso, eval2.cso
npm run eval:verify     # solves all 10 questions through the server; asserts answers

To run the questions through an LLM harness (requires Python 3.10+ and an ANTHROPIC_API_KEY), point it at the server with the working directory set to test/eval/work so the relative image paths in the questions resolve. Any standard MCP evaluation harness works — for example the one shipped with the mcp-builder skill (install its dependencies with pip install anthropic mcp first) — run against this server as:

python evaluation.py `
  -t stdio -c node -a dist/server.js `
  -e UMDGENCLI_PATH=H:\path\to\umdgen.exe `
  -e UMDGENCLI_CWD=test/eval/work `
  test/evaluation.xml