renforge

RenForge

RenForge は、Ren'Py のビジュアルノベルプロジェクトを操作するための MCP（Model Context Protocol）サーバー、CLI、ウェブダッシュボードです。

AI エージェント、またはダッシュボードを使う人間が、プロジェクトを調査したり、Live Editor がデフォルトで有効な状態でゲームを起動したり、画面上のコントロールを選択して調査したりできます。保護された .rpy ソースを書き込む前にレイアウトの変更をプレビューし、実行時の状態を操作し、スクリーンショットを撮影し、翻訳を生成し、孤立したアセットを見つけ、ビルドを実行し、Ren'Py のドキュメントを検索できます。

ステータス：アルファ版で、積極的に開発中です。主要な機能（MCP ツール、ゲーム内ブリッジ、Live Editor、CLI、ダッシュボード）は動作しますが、API は今後変更される可能性があります。

Live Editor — 編集可能なコントロールを選択して調査し、移動をプレビューしてから、Save to source をクリックします

ダッシュボード — 実行中のゲームをリアルタイムで操作	Live Editor — ロックされた対象も、明確な理由とともに調査できます
ストーリーマップ — ノードをクリックして実行中のゲームをワープさせます	アセット監査 — 孤立ファイル、欠落ファイル、未定義の画像

クイックスタート — ダッシュボード

Python 3.11 以降と uv が必要です。それ以外は不要です。 Ren'Py をインストールする必要もありません。RenForge はマシン上で見つかった SDK を再利用するか、初回起動時に自動でダウンロードします。

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

次に、ダッシュボードのプロジェクト選択画面でゲームを選びます。パスを入力する必要はありません。（または --project /path/to/your/game を指定して選択画面をスキップできます。）ゲームを起動し、フローティング RF コントロールをクリックして Live Editor を開きます。

ライブエディター

ライブエディターは、目玉となるバージョン 0.7 の機能です。画面上の対象コントロールを実行中のゲーム内で編集し、実行時にレイアウトの変更をプレビューできます。対象のソースが安全な場合にのみ保存します。ロックされた対象やサポートされていない対象も、理由を明示したうえで引き続き確認できます。意図せず変更を強制することはありません。

対象	まずはこちら
人間	ダッシュボードまたはゲームウィンドウ → 起動 → RF をクリック → キャンバスまたはシーンツリーから選択 → 編集可能な箇所を確認／移動 → 保存 → 正常に停止します。
AI エージェント	renforge_info（live_editor を読み取る）→ renforge_launch → renforge_launch_status をポーリング → renforge_screenshot ／ renforge_scene_tree → ガード付きの renforge_click_at または renforge_click_element → 検証 → renforge_stop。

人間とエージェント向けの詳細なワークフロー、ソースの安全性に関するルール、スクリーンショット： docs/LIVE_EDITOR.md。

インストール

uvx はインストール不要です。PATH 上で renforge コマンドを常時使う場合は、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] を指定すると、オプションのダッシュボード用スタック（Starlette、uvicorn、watchfiles）がインストールされます。MCP サーバーまたは CLI だけが必要な場合は省略してください。

管理対象システム（Debian/Ubuntu）では、PEP 668 により通常の pip install はブロックされます。代わりに uvx または pipx を使用してください。

アップデート

インストール方法	アップデート方法
uvx … @latest	不要です。@latest は起動のたびに最新リリースを取得します
pipx（フルまたはスリム）	pipx upgrade renforge
pip / venv	pip install -U "renforge[ui]"（スリム版の場合は renforge）

新機能：CHANGELOG.md · GitHub リリース。

MCP サーバーを設定する（AI エージェント）

サーバーコマンドは、どのクライアントでも同じです。

uvx renforge@latest serve

すべての RenForge ツールは project_path 引数を取るため、エージェントは呼び出しごとにゲームのパスを渡します。以下の設定をそのままコピーしてください。パスの置き換えは不要です。

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 — 各クライアントの設定ファイルで、同じ mcpServers JSON 形式を使用します。

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

クライアント	設定ファイル
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 に関する問題、および pipx 版については、MCP ガイドで説明しています。

動作を確認する — エージェントに次のように依頼します。

/path/to/game にある Ren'Py プロジェクトを調査してください

エージェントは、そのパスを使って renforge_inspect_project を呼び出し、プロジェクトの JSON サマリー（ラベル、スクリプト、アセット、および関連するメタデータ）を返します。

機能

• ライブエディター（起動時はデフォルトで有効） — ゲーム内で選択、検査を行い、編集可能なコントロールをソースを変更せずにプレビュー／保存できます。ロックされた対象も検査できます。ガイド：docs/LIVE_EDITOR.md。
• プロジェクトの検査 — 構造の概要、スクリプト／ラベル／アセットのスキャン、lint 出力の解析を行います。
• ゲームのライブ操作 — ゲーム内ブリッジとライブエディターを注入してプロジェクトを起動し、会話を進め、選択肢の一覧表示／選択、式の評価、ストア変数の取得／設定、フォーカスされたテキスト／キー／スクロール入力の送信、プッシュされたイベントのポーリング、モデルが文字どおり認識できるフレームのキャプチャを行います。
• シーン認識（ピクセル単位の精度。ビジョン不要） — フレーム全体を構造化された論理座標のノード（renforge_scene_tree）として読み取ります。各スプライト、コントロール、テキストブロックの境界、z 順、色、スタイルに加え、ASCII ワイヤーフレームとシーンの構造差分も確認できます。続いて renforge_measure が、配置、間隔、重なり、収まり、WCAG コントラストをエージェントが活用できる数値で報告します。
• オートパイロット — Ren'Py のメニュー items に基づき、新しいリプレイで選択肢を自動再生します。独自の名前が付いたメニューや選択肢が1つだけのメニューも対象とし、ラベルの網羅状況とクラッシュを報告します。Ren'Py のメニュー items を公開しないカスタムの call_screen インタラクションは、現在、自動探索の対象外です。
• アセットと翻訳 — 孤立した／不足している画像・音声アセットの検出、言語の一覧表示、翻訳統計の計算、game/tl/<lang>/ ファイルの生成／更新、会話のテキスト形式でのエクスポートを行います。
• ビルド — デスクトップ配布物と Web ビルドをパッケージ化します。
• ドキュメント — Ren'Py のオフラインドキュメントを検索して読み取ります。
• Web ダッシュボード — ライブストーリーマップ、アクティビティログ、オートパイロットの網羅状況、lint ビュー、ゲーム状態の操作機能を提供します（デフォルトは 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

ドキュメント

• ライブエディター — 人間とエージェントのワークフロー、編集可能な対象とロックされた対象、ソースの安全性、公開用スクリーンショット。
• MCP ガイド — ツールの全カタログ、エージェントのワークフロー（ライブエディター、ホットリロード、セーブ、ピクセル単位の配置、シーン認識）。
• ランタイムポリシー — 操作レベルでのリスク適用と MCP の ToolAnnotations、認可、互換性計画。
• アーキテクチャ — コードの構成、ライブ操作のフロー、Ren'Py SDK の解決、パッケージ化。
• コントリビューション — 開発環境のセットアップ、フロントエンドのビルド、PR。
• クラウド／CI 環境 — Cursor Cloud Agents、Xvfb、Ren'Py SDK のブートストラップ、環境のスモークテスト。
• 変更履歴 — リリース履歴。
• examples/demo_game/ — すべての機能を試せる、小規模な Ren'Py サンプルプロジェクト。

ライセンス

MIT

コントリビューター

RenForge に貢献してくださった皆さんに、心より感謝します。

• @AxelBeary — 簡体字中国語ダッシュボードの完全な翻訳と、関連する国際化の修正。