Skip to main content
Glama

RenForge

PyPI Python License: MIT CI

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.

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.

Related MCP server: onyx MCP

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.

Available Tools

54 tools
renforge_advanceRenforge AdvanceC

Advance the current dialogue.

Inputs: project_path (required). Returns: object

renforge_assetsRenforge AssetsC

Find orphaned and missing image/audio assets in the project.

Inputs: project_path (required). Returns: object

renforge_autopilotRenforge AutopilotC

Auto-play the game across all branches; report label coverage and crashes.

Inputs: project_path (required), max_runs, max_steps. Returns: object

renforge_capture_screenshotRenforge Capture ScreenshotC

Persist a screenshot under the project's controlled capture directory.

Inputs: project_path (required), grid, name, scale, +9 more. Returns: object

renforge_click_atRenforge Click AtC

Click screen coordinates with optional frame/state safety guards.

Inputs: x (required), y (required), project_path (required), expected_state, +2 more. Returns: object

renforge_click_elementRenforge Click ElementB

Click a visible control by text/id, guarded against a stale frame.

Returns received_by when another control owns the hit point. With wait_for_effect=true, wait for a correlated business event such as quick_save.completed when the clicked action is recognizable.

Inputs: project_path (required), text, exact, screen, +5 more. Returns: object

renforge_contextRenforge ContextC

Discover the active Ren'Py project (dashboard, serve default, or cwd).

Inputs: no named parameters. Returns: object

renforge_controlRenforge ControlB

Run a runtime action: advance, rollback, toggle_skip, toggle_auto, toggle_afm, game_menu, hide_windows, quick_save, quick_load, reload_script, restart_interaction, or quit.

Emits correlated business events (quick_save.completed, skip.stopped, …). Set wait_for_effect=true to block until the matching event appears.

Inputs: action (required), project_path (required), effect_timeout, interaction_id, +1 more. Returns: object

renforge_diff_screenshotsRenforge Diff ScreenshotsA

Diff two frames and return the bounding box of what changed.

before_path is a saved PNG. after_path is another saved PNG, or empty to diff against the current live frame. Use it to measure how far an element moved or to confirm a tweak left everything else untouched.

Inputs: before_path (required), project_path (required), threshold, after_path. Returns: object

renforge_distributeRenforge DistributeC

Build desktop distributions (e.g. package='pc', 'mac', 'linux').

Inputs: project_path (required), package, destination. Returns: object

renforge_estimate_translationRenforge Estimate TranslationC

Estimate stable visual translation between two saved frames.

Inputs: after_path (required), before_path (required), region_x, region_y, +4 more. Returns: object

renforge_evalRenforge EvalC

Evaluate a Python expression in the running game's store namespace.

Inputs: expr (required), project_path (required). Returns: object

renforge_export_dialogueRenforge Export DialogueC

Export the game's dialogue as plain text.

Inputs: project_path (required), language. Returns: object

renforge_find_image_on_screenRenforge Find Image On ScreenC

Find a template image in the current frame and return its bounds.

Inputs: project_path (required), template_path (required), region_x, region_y, +4 more. Returns: object

renforge_find_referencesRenforge Find ReferencesC

Find exact Ren'Py definitions/usages, including text interpolations.

Inputs: symbol (required), project_path (required), limit, offset, +1 more. Returns: object

renforge_game_stateRenforge Game StateC

Return complete live state; optionally include compact metrics or audio.

Inputs: project_path (required), include. Returns: object

renforge_game_state_compactRenforge Game State CompactB

Return bounded live state, optionally with selected variables.

Defaults to state_profile='interaction' so the full store is never returned in the payload unless state_profile='full' is requested.

Inputs: project_path (required), max_depth, max_items, state_profile, +3 more. Returns: object

renforge_generate_translationsRenforge Generate TranslationsC

Generate/update translation files for a language (writes game/tl//).

Inputs: language (required), project_path (required). Returns: object

renforge_get_displayable_boundsRenforge Get Displayable BoundsC

Report where a shown image tag was rendered, in logical coordinates.

Inputs: tag (required), project_path (required), layer. Returns: object

renforge_get_docRenforge Get DocB

Read a Ren'Py documentation page as plain text (e.g. topic='cli').

Inputs: topic (required). Returns: object

renforge_get_errorsRenforge Get ErrorsC

Return recent bridge exceptions or bounded crash-file diagnostics.

Inputs: project_path (required), since. Returns: object

renforge_get_ui_element_boundsRenforge Get Ui Element BoundsC

Report focus bounds and rendered painted bounds for a UI element.

Inputs: project_path (required), text, exact, screen, +2 more. Returns: object

renforge_get_varRenforge Get VarC

Read a variable from the running game's store.

Inputs: name (required), project_path (required). Returns: object

renforge_hit_testRenforge Hit TestB

Inspect the interactive focus stack at a coordinate.

Returns topmost and underneath focusable controls so agents can detect transparent overlays that intercept clicks.

Inputs: x (required), y (required), project_path (required), coordinate_space. Returns: object

renforge_hover_elementRenforge Hover ElementC

Move the pointer over a visible control without clicking it.

Inputs: project_path (required), text, exact, screen, +2 more. Returns: object

renforge_infoRenforge InfoA

Call first: report RenForge version and the active project.

active_project falls back from the dashboard selection to the serve default, then to a Ren'Py project detected from the current directory (project_source says which one matched). A null active_project only means auto-discovery found nothing — every tool accepts project_path directly, so ask the user for the game's path and keep going.

Inputs: no named parameters. Returns: object

renforge_inspect_imageRenforge Inspect ImageC

Open a local image and return an optional cropped/zoomed PNG for inspection.

Inputs: image_path (required), scale, crop_x, crop_y, +2 more.

renforge_inspect_projectRenforge Inspect ProjectD

Inputs: project_path (required). Returns: object

renforge_inspect_screenRenforge Inspect ScreenC

Inspect an active screen's layer, JSON-safe scope, and arguments.

Inputs: name (required), project_path (required). Returns: object

renforge_jumpRenforge JumpC

Restart at a label or file:line; poll launch status when still starting.

Inputs: target (required), project_path (required), version. Returns: object

renforge_languagesRenforge LanguagesC

List translation languages present under game/tl/.

Inputs: project_path (required). Returns: object

renforge_launchRenforge LaunchA

Launch or reuse a game with the Live Editor enabled by default.

Pass editor=False to launch intentionally without the visual editor.

After launch, poll renforge_launch_status until ready, then observe with a fresh renforge_screenshot or renforge_scene_tree before any click. Use renforge_click_at or renforge_click_element with a current frame_id guard; verify the result, then renforge_stop. See docs/LIVE_EDITOR.md. Optional warp is a Ren'Py file:line target.

The call waits at most 20 seconds for readiness, then returns status="starting" while startup continues in the background. Poll renforge_launch_status until it reports ready or failed. display/audio default to auto; savedir='temporary' isolates saves. timeout controls the background startup deadline, not the MCP call.

Inputs: project_path (required), warp, audio, editor, +6 more. Returns: object

renforge_launch_statusRenforge Launch StatusB

Return starting, ready, failed, or idle for a background launch.

Inputs: project_path (required). Returns: object

renforge_list_choicesRenforge List ChoicesC

List the on-screen menu choices (text + index).

Inputs: project_path (required). Returns: object

renforge_list_docsRenforge List DocsB

List available Ren'Py documentation topics.

Inputs: no named parameters. Returns: object

renforge_list_ui_elementsRenforge List Ui ElementsC

List visible focusable Ren'Py controls with bounds and frame guard.

Inputs: project_path (required), text, screen, element_type. Returns: object

renforge_measureRenforge MeasureA

Measure pixel relationships between scene nodes, without eyes.

action is one of align, gap, distribute, center, overlap, fit, contrast. Each target (and within) is a renforge_scene_tree node id (string, resolved live) or a literal bounds object {x,y,width,height}. Returns actionable deltas in logical pixels; when tolerance is given, adds a pass verdict. contrast samples the live frame and reports a WCAG ratio (one target = its internal fg/bg, two targets = between the two elements).

Inputs: action (required), targets (required), project_path (required), within, +1 more. Returns: object

renforge_new_gameRenforge New GameC

Start at the start label; poll launch status when still starting.

Inputs: project_path (required), version. Returns: object

renforge_parse_lintRenforge Parse LintD

Inputs: text (required). Returns: object

renforge_poll_eventsRenforge Poll EventsB

Return pushed events (dialogue, labels, exceptions) newer than since.

Inputs: project_path (required), since. Returns: object

renforge_position_elementRenforge Position ElementA

Reposition a shown image tag live and return its new logical bounds.

Provide at least one placement field. The tag keeps its current attributes. Positions follow Ren'Py's rule: an integer is absolute pixels (xpos=600 is 600px), a float is a fraction of the screen (xpos=0.5 is the centre). Use this to converge on coordinates interactively, then write the final values into the .rpy script.

Inputs: tag (required), project_path (required), xpos, ypos, +9 more. Returns: object

renforge_run_scenarioRenforge Run ScenarioB

Run a multi-step live scenario (click/wait/assert/...) in one call.

On failure, captures a screenshot and compact diagnostics automatically. Supported step actions: set, eval, click, click_at, advance, scroll, wait, assert, select_choice, capture, save, load, control, send_input.

Inputs: steps (required), project_path (required), name, timeout, +3 more. Returns: object

renforge_savesRenforge SavesC

Save, load, or list named save slots without screenshot payloads.

Inputs: action (required), project_path (required), slot, regexp, +1 more. Returns: object

renforge_scan_projectRenforge Scan ProjectC

Scan scripts; defaults to summary-only, with opt-in sections and pagination.

Inputs: project_path (required), limit, offset, symbol, +2 more. Returns: object

renforge_scene_treeRenforge Scene TreeA

Perceive the whole scene as structured data (logical coordinates).

Unlike renforge_list_ui_elements (focusables only), this reports every layer displayable, focusable control, and text block with id, type, bounds, center, zorder and screen. Every reply carries an omitted completeness hint. detail is semantic (default), layout or raw; layers/types/screen/ids scope the result. include=["color","style","overflow"] opts into composited colour, declared style, and best-effort text overflow. format="wireframe" adds an ASCII map. save_as persists a snapshot under .renforge/scenes/; diff_against diffs the live scene against a saved snapshot.

Inputs: project_path (required), ids, types, detail, +9 more. Returns: object

renforge_screenshotRenforge ScreenshotB

Capture a game frame, optionally resizing, cropping, and zooming it.

Measurement guides help pixel-perfect placement: grid draws lines every N pixels, rulers labels those steps along the edges, and crosshair_x/crosshair_y mark a point. Capture at the game's logical resolution (width/height) so the labels read as logical coordinates. Passing only one of width/height keeps the game's aspect ratio.

Inputs: project_path (required), grid, scale, width, +8 more.

renforge_search_docsRenforge Search DocsC

Search Ren'Py's offline documentation for a keyword.

Inputs: query (required). Returns: object

renforge_select_choiceRenforge Select ChoiceB

Select a menu choice by visible text (preferred) or by index.

Inputs: project_path (required), text, index. Returns: object

renforge_send_inputRenforge Send InputB

Send exactly one input mode: text, named key, or scroll object.

text posts character-by-character TEXTINPUT events to a focused Ren'Py Input; submit optionally presses Enter after the text. key accepts readable names such as enter, esc, arrows, pageup, pagedown, backspace, delete, home, end, space, tab, and function keys. scroll is {"x": ..., "y": ..., "direction": "up"|"down"} in logical game coordinates, with optional integer amount. Exactly one of text, key, and scroll must be supplied.

Inputs: project_path (required), key, text, scroll, +1 more. Returns: object

renforge_set_varRenforge Set VarC

Set a variable in the running game's store namespace.

Inputs: name (required), value (required), project_path (required). Returns: object

renforge_stopRenforge StopC

Stop a running game or cancel its in-progress launch, then clean up.

Inputs: project_path (required). Returns: object

renforge_translation_statsRenforge Translation StatsC

Report missing dialogue/string translation counts for a language.

Inputs: language (required), project_path (required). Returns: object

renforge_wait_untilRenforge Wait UntilB

Wait for exactly one label, screen, or expression condition.

Returns a compact state by default (state_profile='interaction'). Pass include for extra fields/variables; use state_profile='full' only when the complete store is required.

Inputs: project_path (required), expr, label, screen, +7 more. Returns: object

renforge_web_buildRenforge Web BuildC

Package the project as a browser-playable build (needs the web DLC).

Inputs: project_path (required), destination. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.5/5.0

    Scored across 54 tools

    Disambiguation2/5

    The set has multiple overlapping tools: renforge_info vs renforge_context both discover the active project; renforge_screenshot vs renforge_capture_screenshot blur capture/persist; renforge_advance duplicates part of renforge_control; renforge_game_state and renforge_game_state_compact create state-reading ambiguity. Two tools (renforge_inspect_project, renforge_parse_lint) have no descriptions at all, worsening boundaries.

    Naming Consistency5/5

    All 54 tools use a uniform `renforge_` snake_case prefix with no camelCase or mixed conventions. Although some names are noun-based (renforge_info) and some verb-based (renforge_click_at), the pattern is predictable and consistent throughout.

    Tool Count1/5

    54 tools far exceeds the 50+ threshold for extreme mismatch; even for a broad Ren'Py automation domain, the surface is bloated. Many operations (advance, bounds, state, screenshots) are duplicated across separate tools, indicating poor scoping.

    Completeness5/5

    The set covers project discovery, scanning, docs, live launch/control, UI automation, screenshots, scene perception, variables, events, saves, translations, assets, builds, and autopilot. No obvious workflow dead ends appear for Ren'Py development and testing, aside from direct script editing which may be outside this server's control plane.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers