MCP Server

Active

MIT

io.github.alex-jordan547/renforge MCP Server

io.github.alex-jordan547/renforge

Inspect, drive, and debug Ren'Py games with live editing, screenshots, and state control.

What is the io.github.alex-jordan547/renforge MCP server?

RenForge is an MCP server, CLI, and web dashboard for inspecting and controlling Ren'Py visual-novel projects at runtime. It enables AI agents and humans to launch games with a Live Editor, select and edit on-screen controls, capture screenshots, manage game state, and generate builds—all with pixel-perfect scene perception and source-safe editing.

RenForge bridges AI agents and Ren'Py game development by providing live runtime control and inspection. You can launch a game, inspect its structure (labels, scripts, assets), select UI elements in the running game, preview and save layout changes, drive dialogue and choices, capture frames, audit assets for orphans or missing files, generate translations, and run builds. The Live Editor lets you edit eligible controls inside the running game and preview changes before saving to source.

How to install io.github.alex-jordan547/renforge

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "renforge": {
      "command": "uvx",
      "args": [
        "renforge",
        "serve"
      ]
    }
  }
}

Tools & capabilities

Tools this server exposes to the agent.

renforge_inspect_project — Summarize a Ren'Py project's structure, scripts, labels, and assets.
renforge_launch — Launch a Ren'Py game with the Live Editor and in-game bridge enabled.
renforge_launch_status — Poll the status of a running game launch.
renforge_screenshot — Capture a frame from the running game.
renforge_scene_tree — Read the running frame as structured logical-coordinate nodes: sprites, controls, text blocks with bounds, z-order, colour, and style.
renforge_measure — Report alignment, spacing, overlap, fit, and WCAG contrast metrics from the scene.
renforge_click_at — Send a guarded click at pixel coordinates in the running game.
renforge_click_element — Send a guarded click on a named scene element.
renforge_info — Read project metadata and Live Editor state.
renforge_stop — Stop the running game cleanly.
renforge_advance_dialogue — Advance dialogue in the running game.
renforge_list_choices — List available choices in the running game.
renforge_select_choice — Select a choice in the running game.
renforge_evaluate_expression — Evaluate a Ren'Py expression in the running game context.
renforge_get_store_variable — Get a store variable from the running game.
renforge_set_store_variable — Set a store variable in the running game.
renforge_send_input — Send focused text, key, or scroll input to the running game.
renforge_poll_events — Poll pushed events from the running game.
renforge_autopilot — Auto-play choices across fresh replays to measure label coverage and detect crashes.
renforge_find_orphaned_assets — Find orphaned and missing image and audio assets.

Use cases

Edit UI layouts and control positions inside a running Ren'Py game, preview changes in real-time, and save only when source-safe.
Automate testing by launching a game, capturing screenshots, reading the scene tree, and driving dialogue choices to measure label coverage.
Audit a Ren'Py project for orphaned assets, missing files, and undefined images; generate or update translation files.
Inspect a game's runtime state—read and set variables, evaluate expressions, and send input—to debug logic or test edge cases.
Build and package desktop and web distributions of a Ren'Py project from the command line or MCP server.

io.github.alex-jordan547/renforge MCP server FAQ

What is RenForge?

RenForge is an MCP server, CLI, and web dashboard for inspecting and controlling Ren'Py visual-novel games at runtime. It lets you launch a game with a Live Editor, select and edit on-screen controls, capture screenshots, drive game state, audit assets, generate translations, and build distributions.

Is RenForge free?

Yes, RenForge is open-source under the MIT license.

How do I install RenForge in Cursor or Claude?

Use `claude mcp add renforge -- uvx renforge@latest serve` for Claude Code, or add the MCP server to your client's config file (e.g., `.cursor/mcp.json` for Cursor) with command `uvx` and args `["renforge@latest", "serve"]`. See the README for client-specific config paths.

Do I need Ren'Py installed?

No. RenForge reuses an SDK it finds on your machine or downloads one automatically on first launch.

What Python version is required?

Python 3.11 or later.

Can I use RenForge without the web dashboard?

Yes. Install the slim version with `pipx install renforge` (no `[ui]`) to get the MCP server and CLI only, without dashboard dependencies.

README (reference)

Source of truth, from the repository.

RenForge

RenForge is an MCP (Model Context Protocol) server, CLI, and web dashboard for working with Ren'Py visual-novel projects.

It lets an AI agent — or a human via the dashboard — inspect a project, launch a game with the Live Editor enabled by default, select and inspect on-screen controls, preview layout changes before writing guarded .rpy source, drive runtime state, capture screenshots, generate translations, find orphaned assets, run builds, and search Ren'Py's docs.

Status: alpha, actively developed. The core surfaces (MCP tools, in-game bridge, Live Editor, CLI, dashboard) are functional; APIs may still change.

<img src=".github/screenshots/live-editor-editable-selection.png" alt="RenForge Live Editor — selected editable control with scene tree, handles, inspector, and style panel" /> Live Editor — select an editable control, inspect it, preview moves, then Save to source <table> <tr> <td width="50%"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/screenshots/live-dark.png" /> <img src=".github/screenshots/live.png" alt="RenForge dashboard — live control of a running game" /> </picture> </td> <td width="50%"> <img src=".github/screenshots/live-editor-locked-reason.png" alt="Live Editor — locked selection with a clear human-readable reason" /> </td> </tr> <tr> <td align="center">Dashboard — live control of a running game</td> <td align="center">Live Editor — locked targets stay inspectable with a clear reason</td> </tr> <tr> <td width="50%"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/screenshots/storymap-dark.png" /> <img src=".github/screenshots/storymap.png" alt="Story map — interactive graph of labels and transitions" /> </picture> </td> <td width="50%"> <picture> <source media="(prefers-color-scheme: dark)" srcset=".github/screenshots/assets-dark.png" /> <img src=".github/screenshots/assets.png" alt="Assets — orphaned, missing and undefined asset audit" /> </picture> </td> </tr> <tr> <td align="center">Story map — click a node to warp the running game</td> <td align="center">Asset audit — orphans, missing files, undefined images</td> </tr> </table>

Quick start — dashboard

Requires Python 3.11+ and uv — nothing else. You don't even need Ren'Py installed: RenForge reuses an SDK it finds on your machine, or downloads one automatically on first launch.

uvx --from "renforge[ui]@latest" renforge ui

Then choose your game in the dashboard's project picker — no path to type. (Or skip the picker with --project /path/to/your/game.) Launch the game and click the floating RF control to open the Live Editor.

Live Editor

The Live Editor is the headline 0.7 feature: edit eligible on-screen controls inside the running game, preview layout changes at runtime, and Save only when a target is source-safe. Locked or unsupported targets stay inspectable with a clear reason — they are not silently forced.

Audience	Start here
Human	Dashboard or game window → launch → click RF → select from canvas or scene tree → inspect / move where editable → Save → stop cleanly.
AI agent	`renforge_info` (read `live_editor`) → `renforge_launch` → poll `renforge_launch_status` → `renforge_screenshot` / `renforge_scene_tree` → guarded `renforge_click_at` or `renforge_click_element` → verify → `renforge_stop`.

Full human and agent workflows, source-safety rules, and screenshots: docs/LIVE_EDITOR.md.

Install

uvx needs no install at all. For a persistent renforge command on your PATH, use pipx:

# Full install — MCP + CLI + web dashboard
pipx install "renforge[ui]"
renforge ui

# Slim install — MCP server + CLI only (no dashboard deps)
pipx install renforge
renforge serve

[ui] pulls in the optional dashboard stack (Starlette, uvicorn, watchfiles). Skip it if you only need the MCP server or CLI.

On managed systems (Debian/Ubuntu), plain pip install is blocked by PEP 668 — use uvx or pipx instead.

Update

Installed with	How to update
`uvx … @latest`	Nothing to do — `@latest` fetches the newest release on each start
pipx (full or slim)	`pipx upgrade renforge`
pip / venv	`pip install -U "renforge[ui]"` (or `renforge` for slim)

What's new: CHANGELOG.md · GitHub releases.

Set up the MCP server (AI agents)

The server command is the same for every client:

uvx renforge@latest serve

Every RenForge tool takes a project_path argument, so the agent passes your game's path on each call — copy the configs below as-is, no path substitution.

Claude Code

claude mcp add renforge -- uvx renforge@latest serve

Codex CLI

codex mcp add renforge -- uvx renforge@latest serve

Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI — same mcpServers JSON shape in each client's config file:

{
  "mcpServers": {
    "renforge": {
      "command": "uvx",
      "args": ["renforge@latest", "serve"]
    }
  }
}

Client	Config file
Claude Desktop	`claude_desktop_config.json`
Cursor	`.cursor/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`
Cline	`cline_mcp_settings.json`
Gemini CLI	`~/.gemini/settings.json`

VS Code (Copilot), Zed, Windows PATH issues, and the pipx variant are covered in the MCP guide.

Verify it works — ask the agent:

Inspect my Ren'Py project at /path/to/game

The agent should call renforge_inspect_project with that path and return a JSON summary of the project (labels, scripts, assets, and related metadata).

What it does

Live Editor (default on launch) — in-game selection, inspection, and source-safe preview/Save for editable controls; locked targets stay inspectable. Guide: docs/LIVE_EDITOR.md.
Project inspection — summarize structure, scan scripts/labels/assets, parse lint output.
Live game control — launch a project with an injected in-game bridge and Live Editor, then advance dialogue, list/select choices, evaluate expressions, get/set store variables, send focused text/key/scroll input, poll pushed events, and capture frames the model can literally see.
Scene perception (pixel-perfect, no vision needed) — read the whole frame as structured logical-coordinate nodes (renforge_scene_tree): every sprite, control, and text block with bounds, z-order, colour, and style, plus an ASCII wireframe and structural scene diffs. Then renforge_measure reports alignment, spacing, overlap, fit, and WCAG contrast as numbers an agent can act on.
Autopilot — auto-play choices backed by Ren'Py menu items across fresh replays, including custom-named and one-item menus, while reporting label coverage and crashes. Custom call_screen interactions that do not expose Ren'Py menu items are not currently explored automatically.
Assets & translations — find orphaned/missing image+audio assets, list languages, compute translation stats, generate/update game/tl/<lang>/ files, export dialogue as text.
Builds — package desktop distributions and web builds.
Docs — search and read Ren'Py's offline documentation.
Web dashboard — live story map, activity log, autopilot coverage, lint view, and game-state controls (default 127.0.0.1:8765).

CLI

renforge --version
renforge inspect <project>      # lightweight project summary (JSON)
renforge serve [--project .]    # start the MCP server (stdio transport)
renforge ui [--project <project>] [--port 8765]  # start the web dashboard

Documentation

Live Editor — human and agent workflows, editable vs locked targets, source-safety, public screenshots.
MCP guide — full tool catalogue, agent workflows (Live Editor, hot reload, saves, pixel-perfect placement, scene perception).
Runtime policy — operation-level risk enforcement vs MCP ToolAnnotations, authorization, and the compatibility plan.
Architecture — code layout, live-control flow, Ren'Py SDK resolution, packaging.
Contributing — dev setup, frontend build, PRs.
Cloud / CI environment — Cursor Cloud Agents, Xvfb, Ren'Py SDK bootstrap, and env smoke.
Changelog — release history.
examples/demo_game/ — small sample Ren'Py project to try everything on.

License

MIT

Contributors

Special thanks to the people who have contributed to RenForge:

@AxelBeary — complete Simplified Chinese dashboard translation and related internationalization fixes.

View repository →

DilutionLens — ASX dilution

ASX dilution data from company filings: raises, options overhang, cash runway, capacity. Keyless.