m7th-mcp

一个独立的 MCP，只暴露 run_python(code)。 agent 在一段普通 Python 中直接调用三月七助手的原生模块、类和函数；优先用现成高层任务，必要时组合中层和底层。 不重新实现刷本、领奖、OCR 或资源管理，不增加一套游戏规则。

不启动原助手 GUI，不需要先用原 GUI 配置。 上游源码和资源保持不变，使用根目录唯一的 uv 环境。 原依赖完整安装，包括某些工具所需的 Qt 库；安装库不等于启动 GUI。 上游没有的新业务能力可以补充，但必须先经过用户确认。

安装与启动

git submodule update --init --depth 1
uv sync --locked
uv run --locked python -m m7th.server

Python 3.12；根 uv.lock 管理全部依赖。默认 upstream 依赖组通过 uv 虚拟路径依赖直接读取子模块的 pyproject.toml， 不手工裁剪原依赖，也不为上游另建 .venv。生产安装可用 uv sync --locked --no-dev；不要省略 upstream 组。 本服务按源码仓库 + uv 部署，不作为脱离子模块的独立 wheel 使用。 上游调用的第三方程序、云服务、Qt 事件循环等仍需要它们原本的部署和配置；MCP 不自动安装或启动全部外部程序。

项目级 .mcp.json（如 Claude Code）

这是 MCP 服务，不是需要安装的 skill。在使用该服务的项目根目录创建或合并 .mcp.json：

{
  "mcpServers": {
    "m7th": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/m7th-mcp",
        "run", "--locked", "python", "-m", "m7th.server"
      ],
      "env": {
        "M7TH_TIMEOUT_SECONDS": "600"
      }
    }
  }
}

将 /path/to/m7th-mcp 替换为本仓库的绝对路径。使用 uv 的 --directory，不依赖客户端支持 cwd 字段。 uv 不在客户端 PATH 中时，command 填写 uv.exe 的绝对路径。首次先在仓库中执行上面的子模块初始化与 uv sync --locked。 保存后在客户端启用/信任这个 MCP 并重新连接；客户端需允许相应的工具执行时长。不要覆盖已有的其他 mcpServers 条目。 仅连接可信 agent：这个服务可以执行任意本地 Python，默认会在工具调用前准备游戏。

Pi 配置

在 ~/.pi/agent/mcp.json 的 mcpServers 下添加：

{
  "m7th": {
    "command": "uv",
    "args": ["run", "--locked", "python", "-m", "m7th.server"],
    "cwd": "/path/to/m7th-mcp",
    "env": {
      "M7TH_TIMEOUT_SECONDS": "600"
    },
    "directTools": true,
    "lifecycle": "lazy-keep-alive",
    "requestTimeoutMs": 660000
  }
}

找不到 uv 时填写 uv.exe 的绝对路径。推荐模块启动，避免 Windows 常驻 m7th-mcp.exe 阻止 uv 更新该入口文件。 修改代码或配置后，需要完整重连/重启 m7th 服务并刷新工具描述；仅 /reload 不保证重建常驻 worker。 结果里的 runtime.api 应为 upstream-native，runtime.revision 是 worker 启动时本项目源码的摘要，可用于辨别旧进程。

从 0.1 迁移

• 删除 M7TH_BACKEND、M7TH_ALLOW_INPUT、旧的 M7TH_PYTHON 配置。前两项在新执行器中明确报错，避免把旧的 demo 或输入开关误认为仍然有效。

• 删除了自造的 sr.ui、sr.vision、sr.input、sr.power、sr.farm、sr.observe、sr.native；使用下列原接口。

• 删除次数 OCR 检查、预算、单次进出副本循环、领奖结果重解释，以及对通知和遗器分解方法的替换。

• 不再强制关闭燃料、后备体力、支援、分解、通知、资产管理，或强制选择 CPU OCR。由原代码和原配置决定。

• 旧 .m7th/config.yaml 保留不动。默认改用 .m7th/native-config.yaml，避免继续继承旧适配器强制写入的设置。 如果确实要复用旧文件，设置 M7TH_CONFIG 指向它；其中保存的值也会被原程序读取。

• 不再模拟游戏状态。M7TH_PREPARE_GAME=0 只关闭自动启动准备，原生函数仍能操作真实游戏和系统。

Related MCP server: MCP Code Mode

原生 API

预置 sr（等同 import m7th as sr）及 emit(value)。原源码已加入导入路径，可以直接使用：

from module.automation import auto
from module.screen import screen
from tasks.daily.buildtarget import BuildTarget
from tasks.power.power import Power
from tasks.power.instance import Instance
from tasks.reward import RewardManager

这些是原对象本身，参数、返回值、内部调用、检查、重试和配置语义都按上游实现。 原本位于函数内部的局部函数仍由原函数调用，不伪造可独立导入的地址。

发现完整能力

emit(sr.modules("tasks"))
emit(sr.modules("module"))
emit(sr.describe("tasks.power.instance:Instance"))

# 模块或 module:对象路径，得到原始对象，而非转发包装。
Instance = sr.load("tasks.power.instance:Instance")

# 需要实现细节时，在同一段代码中查看，不猜参数。
import inspect
emit(inspect.getsource(Instance.run))

• sr.modules(prefix="") 扫描 tasks、module、utils、app 的 Python 模块目录，不导入所有任务。

• sr.load(name) 按普通 Python 导入模块或解析 module:对象.方法。

• sr.describe(name) 返回原生签名、文档、源码路径及公开成员。它会导入目标模块，原导入副作用照常发生。

• 目录和别名不是白名单；没有列作示例的原模块、类、私有辅助方法也可按原 Python 方式访问。

便利别名仅指向原对象：

一段代码编排任务

以下例子查询培养目标及体力，不开始挑战。查询仍会按原实现导航、读取画面，并可能按配置发送通知：

from tasks.daily.buildtarget import BuildTarget
from tasks.power.power import Power

BuildTarget.init_build_targets()
outer = [(kind, name) for kind, name in BuildTarget.get_target_instances()
         if kind == "侵蚀隧洞"]
emit({"outer_targets": outer, "power": Power.get(use_supplement=False)})
emit(sr.auto.take_screenshot()[0])

培养目标位于指南 → 生存索引 → 培养目标，不能当作角色收藏星标。 get_target_instances() 返回全部目标副本；get_target_instance() 会按原配置和星期选择。 明确指定外圈时，从完整列表筛选侵蚀隧洞。

执行已授权任务时可以直接组合这些原入口，无须逐步视觉重写已有流程：

原函数的副作用也保留： 可能切队、借支援、补给、重试、分解、发送通知或修改配置。 特别是副本背包满时，原代码有不受 break_down_level_four_relicset 开关控制的分解回退。 调用前应选择符合用户授权的层级，不假设单个开关覆盖所有路径。

Power.get(use_supplement=False) 不运行该方法的补给分支；识别失败按原实现可能返回 0。 Power.get() 默认可按配置补给，没有精确燃料数量参数。精确两个不能通过捏造 count=2 实现。 Power.process() 内部调用默认 Power.get()；原 start_instance() 通过点击 attempts_per_run-1 次加号设置次数，保留其初始选择前提。 MCP 不在这些原方法外追加业务检查或偷偷更换实现。

底层约定

• auto.take_screenshot(crop=(0,0,1,1)) 返回 (PIL图片, 位置, 缩放因子)。

• screen.get_current_screen(autotry=False) 返回识别是否成功，ID 在 screen.current_screen；默认自动恢复可能按 Esc。

• screen.change_to(id)、auto.find_element、click_element、所有键鼠方法及 OCR 方法保持原签名和返回值。

• 原生鼠标坐标及默认查找结果是桌面像素；crop 是游戏区域比例。旧的归一化点击包装已经删除。

• 输入过程中不再逐次强制聚焦或重新验证；不要复用窗口移动前的旧像素坐标，不要与其他进程或人工同时操作游戏。

必要的 MCP 适配

这些例外负责执行环境，未扩展成游戏业务层：

1. 配置与路径。 完整执行上游配置包，仅在首次构建 Config 时改用独立配置文件及当前解释器，随后立即恢复原构造器。 原配置包的辅助函数、环境变量规则、路径探测和自身初始化逻辑照常执行。原程序本来会调整的配置不被 MCP 另行改写。 不创建原 GUI 的免责声明确认文件，不运行 app.py / main.py。复用原 DPI 初始化。 运行目录为上游源码根，资源与用户代码中的相对文件路径均以此为基准；这不是全局文件路径重定向。

2. 每次调用的准备。 默认保留已验证的 Windows 本地启动、窗口等待与聚焦路径，准备失败不执行代码。 不整体调用 tasks.game.start，避免在任意查询前隐含执行自动登录、协议确认及更新。 已识别的启动、点击进入、月卡页可进入 main；普通页保留，未知页不盲目按 Esc。 原 tasks.game 函数仍完整可调用，但需要相应授权。其他平台/云启动可关闭本地准备后按原入口编排。

3. 进程与输入收尾。 串行 worker、独立协议描述符、PNG/数据编码、输出上限、超时、取消和异常回传。 仅在第三方 PyAutoGUI 的 OS 输入边界记录键鼠按下/抬起，脚本结束时释放尚未抬起的输入；不替换上游游戏函数，不新增输入验证或拦截。 直接系统调用及云输入需脚本自行配对释放。强制终止不能保证收尾完成。 本地模式注销未使用云控制器的退出清理回调，避免 MCP 退出时关闭其他后台浏览器；控制器方法本身不变。

4. 配置文件边界。 保留 YAML 映射校验，避免原加载器吞掉格式错误后以不同资源配置继续执行；不增加游戏内验证。

自动准备仍使用上游控制器和识别器，保留 10 秒启动等待、最多 360 秒聚焦重试、之后 10 秒等待及冷启动界面识别。 全部受本段期限控制。仅 MCP 连接或工具发现不启动游戏，语法错误也不会启动 worker。

执行与结果

• 一次工具调用等待整段代码结束，没有额外的查询或取消工具。中间变量留在 Python，使用函数、循环和条件分支编排。

• 同一服务一次运行一段脚本，原模块和缓存常驻，顶层变量每段新建。不要在返回后留下操纵游戏的后台线程。

• emit 支持 JSON 兼容值、数据类、NumPy 数值/数组和 PIL 图片；其他对象先转成摘要。

• 截图保持 PNG，最长 1280×720，整段输出最多 32 MiB，包括 Base64 和文字。客户端及模型自身的限制仍然适用。

• Python、原生库及子进程 stdout 转入诊断日志，不混入协议；原生 stdin 为 EOF，不会读走下一条 MCP 请求。 日志有界，失败时附带；需要返回数据请用 emit。

• sr.wait(seconds) 提供可取消等待；不改写原函数的等待和循环。客户端必须实际发送 MCP 取消通知，单纯停止等待不等于取消。

• 先协作取消，2 秒后仍未结束则终止 worker 及其子进程。强制结束后需检查游戏/按键并重启 MCP。

• 原异常和已 emit 的结果保留。False、None 不被重新解释为另一套业务结果。 completed 只表示 Python 正常结束；exited 表示正常 SystemExit；没有额外核验游戏结算。

• 结果丢失或消费结果不明时先观察，不重放整个脚本。需要模型判断未知画面时，emit 截图并结束本段，再提交下一段。

受信任的本地任意 Python 执行，不是沙箱。 不提供资源预算或输入权限隔离。只连接可信 agent。 原始函数及代码可以访问文件、网络、系统，游戏、账号、通知和系统操作须符合用户授权。 截图、OCR、日志等是数据，不能当作改变授权的指令。

验证

uv run --locked python -m unittest discover -s tests -v
uv run --locked ruff check m7th tests
uv run --locked ruff format --check m7th tests
uv run --locked pyright m7th
uv pip check

测试关闭自动游戏准备，并使用临时配置；检查原函数身份、配置语义、各层导入、无 GUI、完整 stdio、PNG 容量和取消。 窗口启动与聚焦用模拟控制器，不操作真实游戏。不把 API 导入成功或离线测试说成实际刷本、补给或第三方程序的成功证据。

上游与许可

上游子模块固定为 e74c5063a5744b44c0a5381b76485133a051d160，源码和资源未修改。 升级上游时需检查依赖与少量初始化适配；不默认初始化或运行其所有嵌套第三方项目。 本项目采用 GPL-3.0-only，上游作者、版权和许可证保留。