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

Related MCP server: local-skills-mcp

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:

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

Compilation building

Display

Image operations

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