查文档(search_docs) → 读代码(list_labels) → 写代码(exec_rpy) → 编译验证(check_project) → 自动修复(auto_fix)

┌──────────────────────────────────────────────┐
│              AI Agent (Cursor / Claude)        │
│                  通过 MCP 协议调用               │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│              renpy-mcp Server                  │
│              (FastMCP, 19 个工具)               │
├──────────┬──────────┬──────────┬──────────────┤
│  读代码   │  写代码   │  验证修复  │   文档知识库   │
│ (4 tools)│ (1 tool) │ (5 tools)│  (2 tools)  │
├──────────┴──────────┴──────────┴──────────────┤
│   翻译检查(3)  通用CLI(1)  存档(1)  素材(2)      │
├───────────────────────────────────────────────┤
│                  底层能力                       │
│  ┌─────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ 正则解析 │  │ 文件读写  │  │ subprocess    │  │
│  │ .rpy文件 │  │ BOM安全  │  │ 调用Ren'Py SDK │  │
│  └─────────┘  └──────────┘  └───────────────┘  │
└──────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│           Ren'Py SDK (renpy.py)               │
│     compile · lint · 项目文件 (.rpy/.rpyc)     │
└──────────────────────────────────────────────┘

renpy-mcp/
├── src/renpy_mcp/
│   ├── server.py              # MCP 服务入口 + 工具注册
│   ├── project.py             # 标签解析：list_labels / read_script / find_references / list_definitions
│   ├── executor.py            # 代码注入：exec_rpy（8种定位 + CJK字体）
│   ├── build.py               # 编译验证：compile / lint / check_project / manage_saves / run_renpy_command
│   ├── fixer.py               # 自动修复：auto_fix（5类修复器）
│   ├── assets.py              # 素材管理：copy_asset / get_image_size
│   ├── translation.py         # 翻译检查：list_translations / check_translation / check_language_picker
│   ├── docs_search.py         # 文档搜索：search_docs / list_doc_pages
│   ├── config.py              # SDK 路径配置（跨平台自动探测）
│   └── docs/                  # 内置官方文档（23页，580KB）
│       ├── quickstart.txt     # 快速入门
│       ├── screens.txt        # 界面语言（77KB）
│       ├── screen_actions.txt # 界面行为（60KB）
│       ├── transforms.txt     # 变换和ATL（43KB）
│       ├── gui.txt            # GUI定制化（44KB）
│       └── ...                # 共23个文档页面
├── AI_GUIDE.md                # AI Agent 操作规范
├── CHANGELOG.md               # 变更日志
├── pyproject.toml             # 包配置
├── LICENSE                    # MIT 协议
├── README.md                  # 中文（默认，Gitee 首页展示）
└── README.en.md               # English

git clone https://gitee.com/gdouage/renpy-mcp.git
cd renpy-mcp

# 创建虚拟环境
python -m venv .venv

# Windows
.venv\Scripts\pip install -e .

# macOS / Linux
.venv/bin/pip install -e .

{
  "mcpServers": {
    "renpy-mcp": {
      "command": "D:/absolute/path/to/renpy-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "renpy_mcp.server"],
      "env": {
        "PYTHONPATH": "D:/absolute/path/to/renpy-mcp/src",
        "RENPY_SDK_PATH": "D:/absolute/path/to/renpy-sdk"
      }
    }
  }
}

{
  "mcpServers": {
    "renpy-mcp": {
      "command": "/absolute/path/to/renpy-mcp/.venv/bin/python",
      "args": ["-m", "renpy_mcp.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/renpy-mcp/src",
        "RENPY_SDK_PATH": "/absolute/path/to/renpy-sdk"
      }
    }
  }
}

list_labels(rich=True)    → 看全项目结构和跳转关系
list_definitions()         → 看有哪些角色/立绘/screen
read_script("start")      → 读入口标签代码
find_references("chapter_01") → 看谁调用了这个标签

search_docs("Movie")      → 查官方文档怎么播放视频
exec_rpy(...)              → 根据文档写正确的代码
check_project(force=True)  → 编译 + lint 验证

auto_fix()                 → 自动检测并修复 5 类常见问题
manage_saves("clear_stale") → 清掉导致崩溃的陈旧存档

find_references("arrow_round")  → 看谁调了它（12 处）
find_references("chapter_03")   → 没人调 = 死代码
find_references("typo_label")   → defined=False = 有 jump 指向不存在的标签

list_translations()        → 看有哪些语言、每个语言翻译了多少
check_translation("english") → 抓"只有字符串翻译缺块翻译"的静默 bug
                             + 重复 old 字符串 + 缺翻译文件的源文件
check_language_picker()    → 校验"English"按钮是否误用 Language(None)
run_renpy("translate",["english"]) → 重新生成块翻译骨架

Copyright (c) 2026 abbuibuibui