Renforge

Name: Renforge
Author: alex-jordan547

@alex-jordan547MCP server · External

Inspect, drive and debug a running Ren'Py game: state, screenshots, guarded clicks, saves, builds.

Video gamesv0.7.3MITPython

Freeno charge per call

How to install

Runs on your machine from its package; the steps are below.

RenForge Live Editor — selected editable control with scene tree, handles, inspector, and style panel — From the README · 1 of 5

What it does

Reads
Writes
High impact

At most: moves money, runs code or commands, deletes data, or sends messages for you.

What it costs

Free

Odel charges nothing per call. The publisher may charge for its own service.

Runs locally over stdio

This server isn't hosted — your MCP client launches it from a package registry. Use one of the commands below, or drop the config into your client (e.g. Claude Desktop).

PyPIrenforgev0.7.3

Run

uvx renforge

MCP client config

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

README5 min readView on GitHub

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.

Live Editor — select an editable control, inspect it, preview moves, then Save to source


Dashboard — live control of a running game	Live Editor — locked targets stay inspectable with a clear reason

Story map — click a node to warp the running game	Asset audit — orphans, missing files, undefined images

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.

bash

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:

bash

# 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:

bash

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

bash

claude mcp add renforge -- uvx renforge@latest serve

Codex CLI

bash

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:

json

{
  "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

bash

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.

Similar modules

Browse Video games