微信小游戏 MCP

让 AI Agent 直接驱动微信小游戏开发者工具，建立从观察、操作到诊断的自动化闭环。

项目定位

wxgame-mcp 是面向 微信小游戏 开发者工具的 MCP Server。它不是简单的点按脚本，而是把 IDE 生命周期、画面感知、交互注入、运行时观测与故障诊断统一为 46 个 MCP Tool，让 Claude Code 等 AI 编程客户端能在不改造游戏业务代码的前提下，完成“观察 → 操作 → 等待 → 采集 → 诊断”闭环。

系统架构

系统将稳定的外部控制与游戏内部的运行时采集拆成两个平面：控制面管理开发者工具和会话，数据面通过幂等 Shim 提供游戏内部信号。

核心设计

1. 复用 IDE，避免自动化抖动

wxgame_ensure 先探测默认 9421 端口，已开启则直接复用当前 IDE；只在端口关闭时通过新版 cli auto 拉起开发者工具。会话管理器每次复用前先执行轻量 evaluate 存活检查，死连接自动重建，切换项目时主动断开旧会话。

2. 幂等、零依赖的运行时探针

Shim 以纯 JavaScript 字符串注入 AppService，通过版本号保证重复注入安全。它不依赖具体游戏引擎或业务符号，只在某个工具被调用时暴露对应调试能力，不会在未请求时改变游戏行为。

3. 有界可观测，不让调试本身成为负担

日志、错误、网络、长帧和 FPS 数据都使用有上限的环形缓冲；对象安全序列化，请求与响应预览截断至可控大小。Shim 内部尽量捕获异常、避免向业务链路抛错，使可观测能力在长时间调试中仍保持可预期。

能力地图

能力域	Agent 可执行的任务
画面与交互	截图可直接以 MCP Image 返回给模型；合成点按、滑动，或按 PIXI 节点名称点击
日志与异常	按级别、正则和时间窗口读取 `console.*`、`wx.onError` 与未处理 Promise 拒绝
网络调试	采集 `request / download / upload / WebSocket`，记录状态、耗时与载荷预览，并支持 URL 正则 Mock
性能与内存	统计 FPS 的 avg / min / max / p95，记录超阈值长帧，采样 JS Heap 趋势
引擎内省	探测 PIXI、Laya、Cocos、Phaser 和 Three；对 PIXI 深入提供场景树、命中测试、UI 审计与纹理显存估算
游戏专项	追踪激励视频、插屏、Banner、自定义广告和 InnerAudioContext 实例状态

面向 Agent 的可组合工作流

工具设计不停留在单次 API 调用，而是支持 Agent 组合出可重复的诊断链路。例如：

复用 IDE 并重启游戏，等待 “scene-ready” 日志出现。
截图后扫描 PIXI 场景树，定位越屏元素或过小的交互热区。
按节点名查找按钮并点击，同时记录网络请求、控制台日志和异常。
在复现操作窗口中采样 FPS 和 Heap，再按时间戳将长帧、请求和错误串联归因。

工程交付

项目以 TypeScript 实现，通过 esbuild 输出可独立运行的单文件 Bundle，同时支持 npx wxgame-mcp 接入。仓库提供 Launch Smoke Test 与“ensure → screenshot → console → perf → disconnect”端到端测试，覆盖生命周期复用、Shim 幂等性和核心观测链路。

微信小游戏 MCP

难点与亮点

观察—操作—诊断闭环

控制面与数据面分离

面向游戏的深度可观测

可降级的工程边界