小游戏开放服务 taptap/instant-games-open-mcp

TapTap Open API MCP 服务器

基于 Model Context Protocol (MCP) 的 TapTap 小游戏和 H5 游戏服务器，提供排行榜、分享、多人联机、云存档，以及当前游戏 DC 数据查询、统计概览与评价操作能力，并支持 OAuth 2.0 零配置认证。

🔐 零配置 OAuth | 📚 完整文档 | 🎯 丰富 Tools & Resources | 🌍 小游戏 & H5 | 📦 单文件 Bundle

✨ 核心特性

- 🔐 零配置认证 - OAuth 2.0 Device Code Flow，扫码即用
- 📖 完整 API 文档 - 6 个排行榜 API + 详细代码示例
- ⚙️ 服务端管理 - 创建/管理排行榜，自动处理 ID
- 🎮 H5 游戏支持 - 上传、发布、状态查询
- 📺 广告接入闭环 - 仅用于 TapTap 小游戏/H5，自动查询广告状态和广告位 ID；方向缺失时先刷新服务端应用信息，确认仍未设置后引导用户选择方向，不与 Maker MCP 混用
- 🧭 当前游戏 DC 能力 - 商店/评价/社区统计概览、商店快照、论坛内容、评价列表、评价点赞、官方回复
- 🦞 OpenClaw Plugin - 提供一个原生 OpenClaw plugin 子包，内部复用 TapTap MCP 运行时并暴露 raw JSON 工具 + bundled skill
- 🚀 三种传输模式 - stdio（本地）、SSE（远程/实时）、HTTP（兼容）
- 🔌 多客户端并发 - 独立会话管理，无限并发
- 📦 单文件 Bundle - 零依赖，包体积减少 96%（567 KB）
- 🤖 智能引导 - AI Agent 自动验证前置条件，主动询问用户选择

NPM: @taptap/instant-games-open-mcp
Maker NPM: @taptap/maker

Maker 创作画布的 UI 设计稿、多轮识别、去文字、分层图集和独立 PNG 导出流程见 Maker UI 工作流。

控制台新增「UI 编辑器」页签：直接读取当前项目的 .ui.json，支持节点编辑、左右设计稿对照、透明度叠加和按需查看变更，保存直接写入当前项目。刷新文件列表保留编辑草稿和撤销历史。
编辑器随 Maker 包内置，无需另装或启动服务；顶部问号链接到在线示例。
控制台各页签统一使用紧凑顶部；深浅色切换同步自由画布和 UI 编辑器，无需刷新，不丢失草稿。
UI 编辑器与控制台共用配色：普通按钮为中性色，保存、选中态和勾选控件采用青绿色强调。
旧项目写在 Lua 中的 UI 可由内置 lua-ui-to-json Skill 提取为可编辑的 .ui.json，并运行静态检查；默认保留游戏入口和行为逻辑，已有 JSON 不覆盖用户编辑。
模板与示例媒体不装入 npm 包，首次使用按需从 CDN 下载，失败时尝试 GitHub，校验后缓存到本机。
官方模板图片统一运行 npm run maker:resources:prepare 做无损压缩与像素核对；未处理或未上传 CDN 会阻止打包，发布时再验证两个下载源。维护流程见 示例资源维护。
对 AI 说“把设计稿做成游戏 UI”“拆 UI 素材”或“把切图拼成 UI.json”，通过内置 maker-ui-workflow Skill 从对应阶段继续，不新增 MCP tools。
UI 复原使用 Skill 自带组装脚本：按稳定编号与原稿坐标组装，保留备用切图，再通过 UI 编辑器对照截图记录纠偏；由 AI 分阶段执行与复核，详见同一工作流文档。

Maker 支持本地控制台管理项目、构建和 Git 历史，并在文件不冲突时拉取远端代码；项目页可查看所有项目共用的本机 Runtime 与独立 Lua LSP 安装状态，构建页可单独检查 Lua，构建前默认可选检查。构建失败信息默认展开。构建与本地预览快捷操作会自动切换到对应工作页。构建页按当前阶段显示真实进度，构建详情与 Runtime 日志使用整行宽度；本地窗口预览会在启动 Runtime 前区分普通单机、联机/server 和无配置新项目：不依赖资源索引的单机直接加载原目录；声明公共来源或非默认资源/构建规则、 Windows 旧 dist、联机/server 或缺配置的项目使用受管理副本生成本轮 manifest。所有需要准备产物的项目在 Windows/macOS 均通过仅本机可访问的资源服务加载，统一读取配置和资源索引；单机不会因此申请测试服。
副本固定在项目内 .maker-preview/source，每次覆盖同步，只保留一份；自动加入 Git 忽略。
仅有 .meta、默认资源组或常规构建输出字段不再触发复制；原项目的配置和 dist 不覆盖。
Windows 使用短临时下载缓存，本轮项目下载资源在退出后清理。
联网项目复用 Maker 登录，自动连接线上测试服，无需扫码；服务端改动仍需提交构建后生效，联机项目缺少构建产物时直接报错，不静默降级为离线窗口。
新项目缺少发布配置也可预览：默认入口为 scripts/main.lua、窗口为横屏 1920×1080，仅在临时副本补齐缺省配置，不修改项目；已有方向和已保存窗口设置优先。
公共资源在多个 source 中转引同一资源时，预览会校验本轮索引并显示警告，不再误判为构建失败；真正的资源冲突、其他 Builder 错误及不完整产物仍阻止启动。
“文档 / Skill”页按分类浏览 Maker 内置及当前项目资料，支持目录搜索与 Markdown 阅读。
任务执行中可切换项目，日志和后续操作仍归属原项目；首次点击本地预览可在确认安装 Runtime 后继续启动。
主操作区提供“测试二维码”，缺少名称、分类或首次发布方向时在确认框补齐；需要同步配置时明确确认提交、推送本地改动，再由二维码工具完成构建上传，不额外重复构建。
Lua 检查开关与构建结果集中在远端构建区域，窗口设置默认折叠，通栏日志支持清理、复制与自动换行。
任务列表默认显示摘要，最新失败与运行中任务展开；二维码结果及日志按项目展示。
需要选择开发者时弹窗确认；成功后弹出大图二维码，关闭后可从任务中重新查看。取消不执行操作。
本地预览出问题时，可以提交问题反馈，自动附带脱敏日志和环境信息，并按出错环节分类；自动上传复用现有 GitHub CLI，需要本机已安装并登录；提交状态与 Issue 链接显示在原任务中。
控制台链接无需 token，服务运行时直接打开本机地址即可使用，支持刷新、新标签和项目选择。
标题旁提供 Maker MCP 版本选择，支持查看最近 5 个版本并确认更新；独立发行复用 CLI 更新流程，插件发行仍通过插件市场更新，安装后重新连接 MCP 生效。
控制台提供 16:9、21:9、4:3 窗口预设及可保存的自定义尺寸；横竖屏默认读取项目配置，未配置时使用横屏，也可随时手动选择。设置按项目保存，下次启动或刷新预览时生效，不修改发布配置。
受管理 Runtime 在安装和启动时会自动补齐引擎所需目录与中文兜底字体；项目自带字体仍按项目隔离，不会写入所有项目共用的 Runtime。

相同 Maker 版本从不同 AI IDE 打开时复用同一个控制台，由 Node 直接启动，不要求手动打开 Host。
停止预览只针对当前已登记会话，不会误取消并发启动的新预览；无会话时不会留下停止标记。
用户预览由控制台直接持有 Runtime，发起请求的 AI 命令结束不影响游戏；AI 调试则由前台 Node 会话直接持有 Runtime，结束后清理本轮进程。正常路径没有 WMI/CIM 或预览中转进程。
控制台和 AI 调试结果显示最近的游戏日志；需要完整分页时使用 preview logs，读取末尾可加 --tail。日志错误会保留，不把窗口启动成功当成游戏验证通过。
Windows 安装器已隔离下载子进程与取消通道，避免子进程等待输入导致安装卡住。
退出整个 IDE 仍可能触发宿主的进程树回收；不自动绕过这一边界。
FrameCrate 控制台集成已改为通用插件注册与持久内嵌标签页（2026-09-16，本地验证及独立复核完成），不再以独立浏览器标签作为控制台入口。显式设置 FRAMECRATE_STUDIO_DIR 指向已安装的 framepacker Studio，按已登记项目嵌入完整本地编辑器与 AI 工作流；切换项目或标签应保留编辑现场。
从 Maker 控制台打开画布时，自动将当前 Maker bundle 作为生图/视频入口交给 Studio，不需要单独填写 Maker 入口，也不传递 PAT；独立运行 Studio 仍需配置该入口。
控制台不安装或下载 Studio，不提供 ZIP 安装或插件市场。协议与验收边界见本地控制台文档。

Maker 创作画布

入口：打开完整控制台，选择当前游戏项目 →「序列帧动画」。该栏目同时支持静态素材、视频、动画和 3D 模型，不仅用于序列帧。
使用已安装的 Maker CLI，不临时切换版本：

taptap-maker console open --target-dir "<游戏项目绝对路径>" --json

画布页面的内嵌脚本按原文写入并使用内容哈希 CSP；注入时会清理 tsx 生成的服务端模块前缀，保证浏览器初始化不依赖服务端命名空间。模型缩略图可使用本地 blob 图片，不开放外部脚本、媒体或网络连接。
动画卡对首次播放和页面重绘的时间边界做保护，避免出现负帧索引。

功能清单

画布 CLI 的图集解析支持“网格预览 → 显式确认 → 导出独立 PNG”：使用 preview-image-assets / confirm-image-assets，等待确认与最终生成结果分开返回。
用法见 图集解析说明。

| 功能 | 支持内容 |
| 画布管理 | 空白新建、重命名、保存、搜索全部画布、多页签切换；按游戏项目隔离保存。 |
| 画布操作 | 平移、缩放、适配全图、拖动卡片、框选/多选、复制、删除、撤销/重做、整张画布导出 PNG。 |
| 卡片与分组 | 图片、视频、序列帧、动画、游戏资产、多视图、模型、便签及分组；卡片移入/移出分组、取消分组保留内容。 |
| 素材导入 | 本地 PNG/JPEG/WebP 图片、MP4/MOV/WebM 视频；图片或视频可直接作为后续流程输入。 |
| 图片生成 | 文生图、参考图变体/快速编辑、扩展画面；变体和扩图保留编辑指令，不追加通用去阴影约束；可设置模型、分辨率和比例。 |
| 图片引用 | 选择、移除、清空及有序设置参考图片；通过引用关系连接上游与下游，换参考不自动生成。 |
| 图片本地处理 | 去纯色背景、颜色容差、边缘过渡、去溢色、全图/边缘连通范围；画笔、橡皮、透明填充，保存 PNG。 |
| 视频生成 | 首帧、首尾帧、多图参考；导入参考图、调整提示词、模型、时长、分辨率及比例；画布时长为 4～8 秒。首尾帧变身模板固定两张必填图。 |
| 视频恢复 | 按项目查看视频历史、任务 ID、状态和本地结果；查询并取回原任务、停止本地等待，不重复提交生成。 |
| 视频抽帧 | 选择起止时间、采样 FPS、输出尺寸；本地抽帧、去背景、重复帧确认、缩放及图集保存，最多 120 帧。 |
| 帧编辑与整理 | 单帧修图及批量应用，多选/Shift 连选、删除、复制、排序、去重；完整显示/裁切/拉伸、像素模式、输出 FPS；已有图集可重新编辑。 |
| 动画预览 | 编辑器播放、调速、前后帧叠影；从已保存帧集创建独立动画卡，播放/暂停、手动刷新来源快照。 |
| 静态图集解析 | 设置行列、边距、间距并确认网格；规则切图、生成游戏资产卡、导出独立 PNG 包或 Maker 静态图集包。 |
| 游戏资产 | 预览已拆分的独立 PNG；卡片右上角「⋯ → 下载素材」打包下载，来源删除不删除已保存素材。 |
| 二合图标参数 | 图片卡「快速编辑 → 编辑升级阶段」；设置 1～3 个系列、每系列 2～33 阶段和逐级描述，再生成升级图集。 |
| 3D 模型 | 角色图 → 多视图 → 明确确认全部视图 → 模型；三档质量、原任务查询、本地记录与路径查看、模型缩略图及旋转/缩放/复位预览。 |
| 模板库 | 分类搜索、结果封面；「预览」弹窗查看完整流程，支持缩放/平移/全景，卡片只读；「添加」创建独立副本，不自动生成。 |
| 自定义模板 | 至少两张相连卡片保存为模板；编辑、重命名、替换、另存、删除；支持连同素材导出 ZIP、导入为新模板（最多 128 MiB），仅保存在本机。 |
| 工作流与队列 | 上游变化后保留旧结果并标记下游待处理；调整参数、处理并继续、分组完成剩余流程；串行队列排序、暂停及停止后续，不倒置依赖。 |
| 状态与日志 | 显示处理中、待处理、失败、结果待确认；运行日志展开/筛选/清空，查看接口返回的本次积分。未返回积分不代表免费。 |
| 资源导出 | 图片 PNG/JPG、原视频、独立 PNG 素材包、静态图集、动画图集/单帧包、含材质贴图的模型 ZIP；不触发生成。 |
| AI 操作 | Canvas CLI 查询、编辑、导入、参考设置、模板添加、单卡/分组执行、原任务查询、模型确认/预览及导出到指定本地目录。 |

内置模板（11 个）

| 模板 | 输入 → 结果 |
| 序列帧动画 | 图片 → 视频 → 抽帧 → 动画及游戏资源包。 |
| 角色四方向 | 角色原图 → 正/背/左/右站姿参考 → 各方向视频与动画；先核对朝向再生成视频。 |
| 首尾帧变身 | 必填首图＋尾图 → 变身视频 → 抽帧与动画。 |
| 角色模型 | 角色图 → 多视图审核确认 → 3D 模型包；模板库模型仅供示例预览。 |
| 道具生成 | 完整游戏风格图 → 4 列 × 3 行道具图集 → 12 张独立透明 PNG。 |
| 种植生长 | 作物参考 → 播种至枯萎的四/五阶段图集 → 独立 PNG；按作物调整阶段。 |
| 游戏UI制作 | 香蕉物流设计稿 → 分析拆图 → 分层 PNG 资源包；导出后提示由 AI 接续组装 UI.json。 |
| NPC 批量生成 | 角色风格参考 → 同画风、不同职业的 8 个 NPC → 独立透明 PNG。 |
| 二合图标生成 | 风格参考＋系列/阶段描述 → 多级升级图集 → 独立 PNG。 |
| UI 风格裂变 | 同一 UI 参考 → 温暖手绘、暗黑奇幻、科幻终端三张完整设计稿。 |
| 角色概念设计 | 角色参考 → 动作立绘、正侧背三视图、六种表情的完整展示图。 |

AI 使用与交付边界

「游戏UI制作」模板结束于资源包；接入 Maker MCP 的 AI 可按内置 maker-ui-workflow Skill 继续导入当前游戏项目、生成 meta、组装 UI.json，并打开 UI 编辑器对照调整。
官方示例素材经无损压缩后由 CDN 下载、GitHub 兜底；用户自定义模板及素材保存在本机，不会自动上传到官方资源库。

- 先发现再操作：taptap-maker canvas capabilities 查看当前版本的命令、参数和限制；list / templates / pages 查询画布、模板和页面，inspect 读取卡片、引用与状态。
- 编辑与执行：create / open / rename 管理画布；add-node / update-nodes / delete-nodes / duplicate / group 编辑卡片；import / set-references / connect / disconnect 管理输入；add-template / run / stop / query 操作流程；models / confirm-model / preview-model 操作模型；status / wait 查询命令结果；export / download 保存资源。
- 明确项目与页面：命令使用游戏项目绝对路径；编辑绑定 page-id、canvas-id 和最新 revision，页面须保持打开。已保存快照和列表可离线查询；不要直接改 .maker 下的 JSON 或覆盖人工草稿。
- 界面与 CLI 不等价：逐帧画笔、人工去重、网格解析及模板库保存/替换等交互使用界面；CLI 以 capabilities 为准，支持 mergeIcons 阶段参数编辑，不支持无页面后台执行。
- 生成须授权：打开画布、添加模板及本地处理不扣生成积分；生图、生视频、生模须明确授权，CLI 另传 --allow-paid。模型全部视图须经用户明确批准，不能由队列自动确认。
- 中断先查询：失败或结果未知时先暂停；停止只结束本地等待和后续步骤，不取消远端任务。刷新不会自动重提付费请求；视频原任务在提交后 6 小时内可手动查询（本地策略），模型查询不受此期限限制。
- 按产物接入游戏：动画图集包含 spritesheet.png＋spritesheet.json，单帧包含连续 PNG＋animation.lua；均附接入说明。静态图集供 UI.Sprite 引用，独立 PNG 可供 UI.Panel.backgroundImage 使用；模型包保留材质贴图相对路径。CLI 用 --output-dir 指定目录，不覆盖同名文件，不自动修改游戏代码。
- 结果仍需看图：去背景是本地纯色处理，不是 AI 主体分割；切图只处理规则网格，不识别物品语义。生成尺寸、文字、朝向、阶段顺序和透明边缘须核对；UI/角色设计稿不是可运行界面、动画或模型。3D 预览仅静态外观，不播放骨骼动画。

详细操作见 画布 README，CLI 参数优先查当前版本的 capabilities。

TapTap Maker 客户端插件

plugins/taptap-maker 是插件专属安装与下载页面。Codex 和 WorkBuddy 插件共用独立插件版本，当前值读取 config/maker-plugin-version.json；内置 Maker MCP 版本读取 config/maker-version-policy.json，两条版本线互不覆盖。插件内置 Maker MCP 单文件运行时、CLI、 Skills 和排障文档，不通过 npm/npx 下载或启动 Maker。

对外安装应把对应渠道的 GitHub Release 页面交给 AI，由页面中的统一安装指南选择客户端 ZIP、校验并执行安装前后的旧 MCP 兼容检查。下面的仓库 marketplace 命令仅用于维护者从源码验证；执行 marketplace add 前，必须用刚生成的插件 CLI 完成下文同样的安装前检查和迁移。

npm run maker:codex-plugin:prepare
node plugins/taptap-maker/dist/maker.js plugin inspect --client codex --json
node plugins/taptap-maker/dist/maker.js plugin migrate --client codex --confirm --json
node plugins/taptap-maker/dist/maker.js plugin inspect --client codex --json
codex plugin marketplace add taptap/instant-games-open-mcp --ref main \
--sparse .agents/plugins --sparse plugins/taptap-maker
codex plugin add taptap-maker@taptap-maker
node plugins/taptap-maker/dist/maker.js plugin migrate --client codex --confirm --json
node plugins/taptap-maker/dist/maker.js plugin inspect --client codex --json

插件 manifest 和 marketplace 版本读取 config/maker-plugin-version.json；bundle 运行时身份继续读取 config/maker-version-policy.json。运行 GitHub Actions 中的 Prepare Maker Plugin Release 会自动把插件 patch 加一、重新生成两端产物并创建 PR；合并后 Publish Maker Plugin 自动发布两份 ZIP、 INSTALL.md、SHA256SUMS 和机器可读发布清单，不触发 npm 发布。

旧用户安装插件前，先用 ZIP 解压目录或本地生成目录中的插件 CLI 执行 taptap-maker plugin inspect --client codex --json。如果旧的独立 Maker MCP 仍启用，向用户说明已发现重复注册并直接执行 taptap-maker plugin migrate --client codex --confirm --json。迁移只写入 enabled = false，保留原配置、最近备份、PAT、项目绑定和游戏文件；插件安装请求即为这次兼容迁移的授权，不再单独询问，重复执行也是幂等的。检查返回 ambiguous 时必须在安装前停止；安装完成后必须再次迁移并检查，只有状态为 disabled 或 not_found 才能报告插件可用。需要卸载插件并恢复旧 MCP 时，仍要先取得明确确认，再执行 taptap-maker plugin restore --client codex --confirm --json。
如果本次安装中任一次迁移实际禁用了旧注册，但插件安装或验证失败，则用同一 restore 命令自动回滚；回滚前先移除本次已安装的插件并确认其不再启用，不能在插件仍启用时恢复旧 MCP。原本已禁用、未找到或不是本次迁移的注册不恢复。安装前迁移失败时立即停止，不进入插件安装。

插件模式初始化使用 taptap-maker init --skip-mcp-install，避免 CLI 再写一份独立 MCP 配置。
插件更新通过插件内专用 update-taptap-mcp Skill 和 Codex marketplace 完成，不执行 npm/npx 或独立 taptap-maker upgrade。旧 MCP 恢复前会核对迁移时记录的注册指纹，同名注册已被替换时保持禁用并返回 not_owned。插件故障上报读取插件自己的 .mcp.json 并验证当前 bundle；独立 Maker MCP 仍沿用原有用户配置和 self runtime 诊断。

WorkBuddy 插件是独立产物，位于 plugins/workbuddy/taptap-maker，通过共享的 CodeBuddy 插件规范聚合 Maker MCP、CLI、Skills 和两个快捷命令：

/taptap-maker:create-project
/taptap-maker:sync-project
两个入口都要求当前 WorkBuddy workspace 是空目录。插件启动器优先解析 WorkBuddy managed Node.js（包括 Windows 上未加入 PATH 的 node.exe），必要时才回退系统 Node.js；运行插件内 ${CODEBUDDY_PLUGIN_ROOT}/dist/maker.js，不依赖 npm/npx。仓库 marketplace 位于 .codebuddy-plugin/marketplace.json：

/plugin marketplace add <REPOSITORY_ROOT>
/plugin install taptap-maker@taptap-maker
/reload-plugins

上述 marketplace 只用于从仓库源码验证。正式 WorkBuddy 市场发布 ZIP 直接以插件内容为根，不包含额外的 taptap-maker/ 或 plugins/workbuddy/taptap-maker/ 目录；根目录包含 .codebuddy-plugin/plugin.json、.mcp.json、README.md 和 SKILL.md，所有文件的父目录深度最多为两层。普通用户通过 WorkBuddy 官方插件市场安装，不把发布 ZIP 当成本地 marketplace。

WorkBuddy 旧独立 MCP 的迁移使用 --client workbuddy，只把旧注册的 disabled 设为 true，同时支持幂等检查和确认式恢复。插件更新通过 WorkBuddy /plugin 完成。

🦞 OpenClaw Plugin（实验中）

仓库内提供了一个可独立使用的 OpenClaw plugin 子包：

- packages/openclaw-dc-plugin

这个子包的设计目标是：

- 让 OpenClaw 用户只安装一个 plugin
- plugin 内部复用 @taptap/instant-games-open-mcp 运行时
- 对 OpenClaw 暴露 raw JSON 工具
- 同时内置 taptap-dc-ops-brief skill，让模型自己做简报解读

说明：

- 主包里的 _raw tools 默认不会暴露给普通 MCP 客户端
- 只有设置 TAPTAP_MCP_ENABLE_RAW_TOOLS=true 时才会注册
- OpenClaw plugin 会自动打开这个开关，因此插件用户不需要额外配置

详见：

- OpenClaw Plugin 说明

🛠️ TapTap Maker 本地开发（CLI-first）

本地 run-lua-validate Skill 可通过 preview validate 调用已有 Runtime 的报告、日志、截图和断言能力，复用本地预览的项目准备与资源加载。验证流程和游戏结论仍由 Skill/Agent 执行，不修改引擎。参数、运行条件与失败处理见 本地验证说明。
控制台 Validate 以可滚动过程列表展示多轮调用，最新结果在最上面，日志/JSON 缩起显示 3 行、截图显示小图；验证不依赖控制台运行。过早的黑屏/引擎加载截图可有界重试，游戏 loading 仍须 AI 看图确认。
支持 Agent 按需求重复验证，每项目保留最近 3 次已结束验证，每轮结束执行清理；活跃或进程状态不明的记录额外保留，无后台定时任务。控制台“构建与测试”分别显示全部项目与当前项目预览占用，包含旧用户目录缓存及项目内固定副本，提供当前项目／全部项目清理按钮。未知归属、运行中内容和 Runtime 下载资源保留并说明；统计占用不等于可清理大小。--output-dir 可长期归档验收材料。
原 Skill 文件缺失时，即使本地未配置排除规则也会提示更新 ai-dev-kit；归档保留最终清理告警。

Maker 本地开发独立发布为 @taptap/maker。首次配置推荐直接运行：

npx -y @taptap/maker init

CLI 负责一次性流程：Git 检查、Python 和 maker-lua-lsp 本地 Lua 诊断环境检查、CLI 登录、TapTap token 换取、app 列表选择或新建 Maker 项目、Maker Git clone、AI dev kit 准备、MCP 配置写入与基础验证。Python 环境准备连续 3 次失败时，初始化会暂停在登录、项目拉取和 MCP 配置之前；修复后重新运行 taptap-maker init。首次安装，或 Maker MCP 包/静态工具 schema 发生变化后，Claude Code / Codex / Cursor / Trae / OpenCode / WorkBuddy 通常需要重连或刷新一次 MCP，才能加载新的 MCP tools；DeepSeek Harness（DSH）会监听用户补丁并热重载，不要求重启 IDE。单纯绑定或切换 Maker 项目不会修改用户级 MCP 配置，也不需要重启会话或新开对话。当前终端里的 CLI 初始化流程可以继续完成到 PAT 鉴权和项目绑定。

常用 CLI：

taptap-maker init
taptap-maker login
taptap-maker doctor
taptap-maker apps --json
taptap-maker install
taptap-maker agents update
taptap-maker upgrade
taptap-maker mcp verify
npx -y --package @taptap/maker@<exact-version> taptap-maker mcp report --ide <client> --target-dir <project> --context-stdin --consent --json
taptap-maker dev-kit update
taptap-maker user-skills pull --target-dir <project>

普通初始化、clone、下载或拉取远端项目的标准命令是 taptap-maker init，CLI 会展示 app 列表，让用户选择已有 app 或 0/new。--create 只用于用户明确要求创建新 Maker 项目的场景。
需要创建新 Maker 项目时，仍从 taptap-maker init 进入。app 列表底部会固定显示 0. Create a new Maker project，输入 0 或 new 后填写项目名称；自动化场景可用 taptap-maker init --create --name "my-local-game"。当前目录已绑定 Maker 项目时，不允许在同一目录创建并覆盖绑定；请先切到一个新的独立目录再运行 taptap-maker init。

taptap-maker login 是命令行登录入口；它会按需打开 Maker 授权页，命令行轮询授权结果并完成本地鉴权配置。
taptap-maker init 缺 PAT 时会自动进入该流程。taptap-maker pat set 保留为兼容入口；自动化场景可用 --pat-stdin 从标准输入读取。taptap-maker install 是 taptap-maker mcp install 的快捷别名。二者都会先用最终启动命令完成 MCP initialize 和 tools/list，验证成功后才写入 AI 客户端 MCP 配置；失败不会改动配置或备份。
默认 launcher 会把当前精确版本的 Maker bundle、skills 和排障文档复制到用户 Maker 目录下的版本化 mcp-runtime，配置使用绝对 Node 路径直接启动，不依赖 npx 缓存、网络或客户端 PATH。
只有明确需要 npm 启动链路时才使用 --launcher npx；该模式固定当前包版本并使用专用可写缓存。
taptap-maker init 写入多个客户端配置时会继续尝试其余目标；只要任一目标失败，init 就记录 mcp_install_failed、以非零状态结束且不报告初始化完成。已经成功写入的客户端配置会保留，修复失败项后重新运行 taptap-maker install 即可自动检测并幂等重试。
默认会写入 Codex、Cursor、Claude，并自动检测本机已有的 Trae、OpenCode、WorkBuddy、DSH 配置文件；命中后会合并安装 taptap-maker。Trae Solo 是重点支持目标，命令行会在 Solo 或 Solo CN 的 User/ 目录存在时创建或合并 User/mcp.json；普通 Trae/Trae CN 仍作为候选路径保留，但只有 mcp.json 已存在时才合并写入。WorkBuddy 在 macOS 和 Windows 都优先检测并合并用户目录下已有的 .workbuddy/mcp.json。legacy .workbuddy/.mcp.json 仅在官方配置文件不存在且自身已存在时作为 fallback 合并；写入的 WorkBuddy MCP server 会包含 disabled: false。
WorkBuddy 账号维度的启用/信任状态在 .workbuddy/connectors/<account-id>/connector-states.json 中维护，不在 mcp.json 中；命令行只做只读诊断，并在安装结果中提示你到 WorkBuddy MCP 设置里启用/信任 taptap-maker，不会自动修改账号信任状态。
普通 doctor 不会因为发现 .workbuddy 就输出 WorkBuddy 诊断。OpenCode 只在 ~/.config/opencode/opencode.jsonc 已存在时写入。
DSH 使用 @deepseek-ai/dsh-mcp-client 插件，不使用 mcp.json。检测到 $DSH_HOME （默认 ~/.dsh）后，普通 taptap-maker install 会自动创建或合并用户级 cordis.patch.yml，写入稳定 self launcher、failOnStartupError: true 和 1 小时 toolCallTimeoutMs，并保留其它插件。
新增项使用 DSH Cordis insert patch；若已经存在 profile 级 Maker registration，命令行会就地更新对应 profile，避免全局和 profile 出现重复 serverName。
默认 home 级补丁适用于 DSH 的不同 profile；检测到已有 profile 级注册时则只更新对应 profile。
两者都可由 DSH HMR 热重载。配置不写项目 cwd；DSH 当前不广播 MCP Roots，因此 AI 必须在具体 Maker tool 调用中把当前游戏项目作为 target_dir 传入。
需要把 Maker 技能（工作流 + 广告/云存档/排行榜指南）一并打包进 DSH 时，可用 bundle 插件 @taptap/dsh-maker（源码 packages/dsh-maker/），通过 1024Store 对应的公开 npm 包一键安装，详见 docs/DSH_PLUGIN.md。稳定版从 npm 获取；dsh-maker-v GitHub Release 继续提供预览版和离线安装 tarball。该插件与 L1 的裸 MCP 行不要同时启用。
其它 AI 编辑器应优先让本地 AI 复用 taptap-maker mcp install 已验证的绝对 command/args。
只有无法复用安装器时，才使用下面固定精确版本的 npx 兼容片段：

{
"mcpServers": {
"taptap-maker": {
"command": "npx",
"args": ["-y", "-p", "@taptap/maker@<exact-version>", "taptap-maker"]
}
}
}

TapTap Maker 的用户配置不需要设置服务环境。预览、构建、测试二维码和本地开发都使用官方服务配置。

taptap-maker init、mcp install 和 upgrade 写入的用户级 MCP 配置永远不包含项目 cwd，避免多个客户端、对话或 Maker 项目争用同一个全局路径。支持 MCP Roots 的客户端会用当前 workspace root 识别项目；不支持 Roots 时，由 Agent 在具体 Maker tool 调用中传入 target_dir。
MCP 进程自身的 cwd 只作为最后兜底和诊断信息，不应通过重写用户配置来切换项目。
若 cwd fallback 没有绑定项目，Maker MCP 仍正常启动并保留 status/tools/list，但项目相关 proxy tool 会快速失败，明确返回实际评估目录和上下文来源，避免把其它目录的 not_initialized 当成当前项目状态。
安装器会先比较现有 taptap-maker 条目；内容一致时不写文件，Claude 也不会重复执行 claude mcp add。因此后续项目 init 或无配置变化的 upgrade 不会触发配置重载。
从旧 beta 升级时，安装器会移除现有 taptap-maker 条目中的历史 cwd，同时保留配置里的其它 MCP server；这次必要迁移完成后，切换项目不再修改用户级配置。
taptap-maker upgrade 会刷新当前机器的 Maker MCP 配置，并在当前目录已绑定 Maker 项目时同步项目 AGENTS.md 的 TapTap Maker 受管策略块。maker://status、maker_status_lite 和 taptap-maker doctor 会检查老项目 AGENTS.md 是否缺失或过期，并提示运行 taptap-maker agents update 或 taptap-maker upgrade。
taptap-maker dev-kit update 会检查当前环境可用的最新 AI dev kit 并更新当前目录。
初始化及 dev-kit 更新会从 .installer/skills 自动补齐 .agents/skills，沿用原始 Skill 名称，已有同名目录不覆盖；链接不可用时回退复制。
taptap-maker user-skills pull 是可选的边缘命令，仅在用户明确要求时从 Maker Server 下载个人 Skill，并覆盖项目 .installer/skills/ 中 ZIP 包含的同名目录，再以原始 Skill 名称安装到项目内 .codex/skills/、.cursor/skills/、.workbuddy/skills/ 和 .agents/skills/；其它本地 Skill 保持不变。
归档下载限制为 64 MiB，最多 1000 个条目、解压后最多 128 MiB。
该命令不属于正常开发或初始化流程，也不会增加 MCP tool。

如果 Maker MCP tools 缺失或出现 -32000 / Connection closed，先按 TapTap Maker MCP 本地连接自检与修复指引 检查本地客户端配置、信任状态、cwd、Node/npm/npx 和启动日志。MCP 未连接时不要依赖 MCP tools 自检。

如果证据指向 Maker MCP、proxy、客户端集成或服务端基础设施异常，taptap-maker-local Skill 会在当前会话对同一种故障只询问一次是否上报。用户同意后，AI 才通过 stdin 调用上报优先复用当前客户端 Maker MCP 配置中的原始 command 和有序 args，并追加 mcp report --ide <client> --target-dir <project> --context-stdin --consent --json。只有确认当前精确版本时才 fallback 到 npx -y --package @taptap/maker@<exact-version> taptap-maker mcp report ...，不要使用无版本包名误启 npm latest； Windows 无法从 PATH 找到 npx 时继续使用配置中的绝对 node.exe 和 npm-cli.js，收集当前客户端的 Maker 配置项、MCP launcher 验证、项目上下文和已脱敏的会话错误，并尽力创建 GitHub Issue。报告不包含完整聊天、项目源码、其它 MCP server、PAT/token 或完整环境变量；用户主目录统一显示为 ~。GitHub 不可达、未登录或提交失败时返回 manual_required，AI 会展示脱敏报告和手动 Issue 地址，然后继续原任务，不把上报失败当作 Maker 故障。

Maker MCP 精简为开发循环里的高频能力：

maker://status # Resource，读取本地 Maker 状态 maker://ads-integration-guide # Resource，广告接入入口与项目引擎文档索引 maker_status_lite # Resource 不可用时的兼容 tool maker_build_current_directory # commit/push/build 合并入口 generate_resource_meta # 显式生成本地资源 .meta 和官方 UUID

generate_resource_meta 接收项目根目录 target_dir 和相对文件/目录列表 paths，使用内置的 UrhoX 官方生成器补齐 .meta，返回资源路径和 UUID；已有有效 .meta 保持不变。调用时机由 AI 决定，Canvas 不自动触发。需要可用的 Python 环境；详见 资源 meta 使用说明。

Maker MCP 初始化时会通过标准 initialize.instructions 向 AI 客户端提供一份精简能力路由，标出状态、构建、Tap 流程和游戏资源生成入口。新项目初始化或执行 taptap-maker agents update / taptap-maker upgrade 时，同一份路由也会写入目标 Maker 项目 AGENTS.md 的受管策略块，供后续会话继续使用；用户自己编写的内容保持不变。升级 @taptap/maker 后，当前 MCP 会话不会被 taptap-maker upgrade 主动中断，已有 proxy tools 继续可用；新版本和新的初始化提示会在下一次 MCP 启动或用户主动 reconnect 后生效。

在已绑定 Maker 项目中，maker_build_current_directory 同时覆盖“构建 / 预览 / 跑一下 / 查看结果 / 看看效果 / 验证游戏效果 / 提交 / 推送”。普通“验证代码 / 跑测试 / lint / 检查实现时，不应自动触发 Maker 远端构建，除非用户明确要求构建、运行或预览 Maker 游戏。
普通构建会先 push 到 Maker 远端，再触发远端 build：本地有改动时提交改动，已有未推送 commit 时直接 push，本地干净且没有未推送 commit 时创建 chore: wake maker build server 空提交来唤醒远端服务。提交前如果本地仅落后于 Maker 远端，会自动执行 fast-forward 后继续提交；如果远端更新会覆盖本地未提交修改，则会在创建 commit 前停止并保留本地文件。分叉、非 main、鉴权或网络失败仍按原有提示处理。push 成功但 build 失败时，会明确说明代码已到 Maker 远端但构建失败。只有用户明确说“不提交，只构建云端版本”时，才传 confirm_remote_build_without_submit=true；该模式只构建 Maker 远端已提交版本，不会自动打开 Maker 页面。

code_submit 或无法分类的构建执行失败会附带 local_execution_check，提醒检查 Windows PowerShell、 CLI、Git 或 MCP 命令是否被 AI 客户端沙盒拦截。只有明确的本地 PowerShell/进程拦截证据才会标记 restriction_signal: detected；远端 Git 返回的 sandbox 文本不会被当成本地信号。远端构建失败优先检查代码和资源诊断，只有本地命令也被拦截时才检查沙盒；已知项目配置、鉴权/上下文或结构错误不提示 Full Access。
Maker MCP 无法读取客户端访问模式，因此该检查不是根因结论。可信项目可开启 Full Access （“完全访问模式”）、重连 MCP 后再重试本地命令。
本地 Tap auth 或 user_id 上下文准备失败会返回 failure_stage: local_build_context 和 remote_build_status: not_started，应直接按 login/init 提示恢复，不会描述成远端构建失败。

远端 Lua/LSP 编译失败属于构建业务错误，MCP 会以工具结果 isError: true 返回，并在 content/remote_result 中保留原始诊断（包括文件、行号和编译器消息）。只有连接断开、会话失效等传输故障才使用 MCP 协议错误；排查构建失败时应优先查看工具结果中的 remote_result，不要把 -32603 直接当作服务不可用。Maker 本地重试只针对连接类故障；带结构化 remote_result 的业务错误不会重复发起构建。明确的 proxy unavailable、连接关闭、请求超时和 HTTP 5xx 会按退避策略重试；重连后重放请求若再次断线，会保留未完成队列并继续下一轮重连。

构建成功后，Maker MCP 会刷新 Maker Web 预览，并启动本地 runtime log watcher。后续如果用户询问游戏运行结果、Lua 报错或调试问题，本地 AI Agent 应优先读取构建返回中的 runtime_logs.local_file；如需判断 watcher 是否正常，读取 runtime_logs.state_file。

Maker MCP 也提供部分远端 proxy 能力，当前包括 generate_image、batch_generate_images、 edit_image、create_video_task、query_video_task、text_to_music、 text_to_sound_effect、batch_sound_effects、text_to_dialogue、 audition_voices_for_character、confirm_character_voice、create_3d_asset、 generate_test_qrcode、add_test_whitelist、get_ad_config 和 get_debug_feedbacks；具体参数以 MCP 客户端展示的 tool schema 为准。
这些 proxy tools 为 Maker 项目提供素材生成和平台工作流能力；其中 get_debug_feedbacks 会拉取线上玩家反馈，并在可下载附件存在时保存日志和截图到当前 Maker 项目的 logs/feed_back/feedback_<id>/，返回 local_dir / local_log_paths / local_screenshot_paths 等本地路径。代理转发、错误透出和白名单细节见 TapTap Maker 本地开发。
create_video_task 仅响应用户明确的视频生成请求；长于 10 秒或使用 Seedance 2.5 时，会先返回积分粗估，用户明确确认后才携带 user_confirmed=true 创建任务。
音频 tools 支持音效、角色试听、音色确认和配音；生成音频以及确认后的参考音频会保存到当前本地 Maker 项目。

生成测试二维码时，Agent 应先直接调用 generate_test_qrcode。如果 .project/project.json 已有 taptap_publish.screen_orientation，本地 MCP 会直接沿用，不能重复设置，也不应再次询问用户。只有该字段从未设置时，Agent 才必须单独询问用户选择横屏（landscape）或竖屏（portrait），并在重试时通过本地私有参数 confirmed_screen_orientation 传入首次选择；本地 MCP 会写入该值，且不会转发给远端 proxy tool。
二维码生成并建立应用身份后，可使用 add_test_whitelist 将用户明确提供的 TapTap user_id 加入测试白名单。

Windows 是默认优先级：CLI 只把当前进程可用的绝对 node.exe 与 npm-cli.js 写入所有客户端配置；找不到该组合时安装失败，不会持久化 .cmd shell 命令或依赖客户端 PATH 的裸 npx.cmd。OpenCode 使用相同已验证 launcher 的 command 数组。用户级 MCP 配置不会写入项目
目录，也禁止生成 cd && npx.cmd；Git 引导优先提示 Git for Windows，
并要求安装选项允许命令行和第三方工具通过 PATH 找到 Git。macOS 用户可通过 git --version 触发 Xcode Command Line Tools，或安装官方 Git。

详见：TapTap Maker 本地开发。面向团队介绍的功能总览见 Maker CLI + MCP + Skill Rework Overview。

本地 Maker MCP 会透明上报本地开发活跃事件，复用 tapmaker_mcp_call，并在 args.source 写入 local_mcp，在 args.mcp_version 写入当前 @taptap/maker 版本；普通开发构建使用 dev，不会用主包版本代替。事件只使用当前绑定项目配置中的 user_id 和 project_id；任一关键字段缺失，或项目上下文无法准确解析时，跳过上报，不用默认值或其它账号信息代替。Tool、maker://status Resource 和 MCP 启动事件都算作活跃行为，上报失败不影响 MCP 工具结果。

🧩 Codex Skills（运营简报）

本仓库内置一个 Codex Skill，面向运营/工作室：taptap-dc-ops-brief。它把「当前游戏 DC 数据」整理成 30 秒可读的结论简报，并在你确认后执行评价点赞、官方回复等动作。

安装到 Codex

在已安装 Codex 的机器上运行：

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
--repo taptap/instant-games-open-mcp \
--path skills/taptap-dc-ops-brief

安装完成后重启 Codex，即可在对话中使用：

使用 $taptap-dc-ops-brief 生成当前游戏的 7 日运营简报，并给出是否建议点赞/回复评价（先出草稿，等我确认再发）。

🚀 快速开始

🐣 完全不懂技术？ 快速开始（零基础版） - 3 分钟搞定 Cursor 配置，复制粘贴就能用。

📖 想了解更多配置？ 详细配置指南 - Cursor、Claude Code、VS Code、Claude Desktop 等多种工具的配置方法。

安装

全局安装
npm install -g @taptap/instant-games-open-mcp

或使用 npx 直接运行（无需安装）
npx @taptap/instant-games-open-mcp

配置（MCP 客户端）

Claude Code / VSCode / Cursor

在项目中创建 .mcp.json:

{
"mcpServers": {
"taptap-minigame": {
"command": "npx",
"args": ["-y", "@taptap/instant-games-open-mcp"],
"env": {
"TAPTAP_MCP_WORKSPACE_ROOT": "${workspaceFolder}"
}
}
}
}

重要说明：

- 零配置 OAuth：首次使用会提示扫码授权，token 自动保存！
- 路径处理：设置 TAPTAP_MCP_WORKSPACE_ROOT 环境变量可以正确解析相对路径（推荐）
- 如果不设置，相对路径会基于用户 HOME 目录（可能不符合预期）
- 建议使用绝对路径，或配置 TAPTAP_MCP_WORKSPACE_ROOT
- Windows 启动报 Received protocol 'c:'：这是旧版本 Windows ESM 动态导入路径兼容问题，请升级到包含该修复的最新版本。

OpenHands（推荐 SSE 模式）

远程部署:

启动 SSE 服务器
TAPTAP_MCP_TRANSPORT=sse TAPTAP_MCP_PORT=3000 \
npx @taptap/instant-games-open-mcp

OpenHands 配置:

{
"mcpServers": {
"taptap-minigame": {
"url": "http://your-server:3000",
"transport": "sse"
}
}
}

✅ SSE 模式支持实时进度推送！

Docker 部署

快速启动（同时运行 Production 和 RND 环境）
cd docker/npm
docker-compose up -d

健康检查
curl http://localhost:5003/health # Production
curl http://localhost:5002/health # RND

详见: Docker 部署文档

📖 功能列表

核心 Tools（含当前游戏 DC 能力）

流程指引 (1)

- get_leaderboard_integration_guide - 排行榜完整接入工作流指引

信息查询 (3)

- get_current_app_info - 获取当前应用信息
- check_environment - 检查环境配置
- get_environment_switch_guide - 获取 production/RND 环境切换配置指引

认证 (3)

- start_oauth_authorization - 开始 OAuth 授权（获取二维码）
- complete_oauth_authorization - 完成 OAuth 授权
- clear_auth_data - 清除认证数据和缓存

应用管理 (3)

- list_developers_and_apps - 列出所有开发者和应用（含关卡与非关卡）
- select_app - 选择当前应用（支持关卡与非关卡）
- create_developer - 创建新开发者

当前游戏 DC 能力 (8)

- get_current_app_store_overview - 获取当前游戏商店统计概览（曝光、下载、预约、下载请求趋势）
- get_current_app_review_overview - 获取当前游戏评价统计概览（评分、好中差评、评分趋势）
- get_current_app_community_overview - 获取当前游戏社区统计概览（帖子、关注、浏览、趋势）
- get_current_app_store_snapshot - 获取当前游戏商店结果型快照
- get_current_app_forum_contents - 获取当前游戏论坛内容
- get_current_app_reviews - 获取当前游戏评价列表
- like_current_app_review - 给当前游戏指定评价点赞
- reply_current_app_review - 以官方身份回复当前游戏评价

排行榜管理 (5)

- create_leaderboard - 创建排行榜
- list_leaderboards - 列出排行榜
- publish_leaderboard - 发布排行榜
- get_user_leaderboard_scores - 获取用户分数
- get_app_status - 获取应用审核状态

H5 游戏管理 (3)

- prepare_h5_upload - 收集 H5 游戏信息（上传前）
- upload_h5_game - 上传 H5 游戏包；首次上传未设置横竖屏时暂停并要求用户选择，提交后校验服务端方向
- get_debug_feedbacks - 拉取用户调试反馈并下载日志/截图

振动 API 文档 (1)

- get_vibrate_integration_guide - 振动 API 完整文档和接入指引

11 个 Resources

完整的排行榜 API 文档：

- docs://leaderboard/overview - 完整概览
- docs://leaderboard/api/get-manager - 初始化
- docs://leaderboard/api/submit-scores - 提交分数
- docs://leaderboard/api/open - 显示 UI
- docs://leaderboard/api/load-scores - 加载数据
- docs://leaderboard/api/load-player-score - 玩家排名
- docs://leaderboard/api/load-centered-scores - 周围玩家

完整的振动 API 文档：

- docs://vibrate/overview - 完整概览
- docs://vibrate/api/vibrate-short - 短振动 API
- docs://vibrate/api/vibrate-long - 长振动 API
- docs://vibrate/patterns - 使用模式和最佳实践

🎯 使用示例

接入排行榜

用户: "我想在游戏中接入排行榜"

AI 调用: get_integration_guide → 返回完整工作流（创建排行榜 → 客户端代码 → 测试）

AI 调用: create_leaderboard → 创建服务端排行榜

AI 读取: docs://leaderboard/api/submit-scores → 获取客户端代码示例

OAuth 授权（首次）

AI 调用: create_leaderboard → 🔐 需要授权，显示二维码链接

用户: 扫码后告知 "已授权"

AI 调用: complete_oauth_authorization → ✅ 授权完成，token 已保存

AI 调用: create_leaderboard → ✅ 排行榜创建成功

🛠️ 开发

环境要求

- Node.js 18.14.1+
- npm 或 pnpm

本地开发

安装依赖
npm install

启动开发服务器
npm run dev

构建
npm run build

运行测试
npm test

Maker 本地开发预览

Maker 本地开发现在以 CLI-first 为准。初始化、PAT、app 选择/创建、dev-kit 和 clone 都走 CLI；MCP 保留状态、同步构建和审核过的 proxy tools：

taptap-maker init
taptap-maker doctor
taptap-maker apps
taptap-maker mcp verify
maker://status
maker_status_lite
maker_build_current_directory

远端 proxy tools 使用版本化的本地完整定义，在首次 tools/list 时立即注册，不等待 cwd、Maker 项目绑定、 PAT/TapTap token 或远端 proxy 连接。项目定位和鉴权只在实际调用 tool 时校验；远端 schema 不会在运行时替换本地定义。schema 变更通过本地 MCP 版本更新发布，远端不可用不会让 proxy tools 从当前会话消失。
唯一例外是 Maker Server 明确返回 BLACKLISTED 的账号：MCP 每个进程启动时只检查一次账号状态， tools/list 只保留 maker_status_lite，任何 tool call 和 maker://status 都直接返回限制提示，不进入本地构建或远端 proxy。PAT 缺失、过期、网络超时和其它非黑名单错误不会隐藏工具；账号状态变化需要重连或重启 MCP 后生效。
Maker 内嵌代理不打开可选的 standalone SSE GET，远端 RPC 响应和构建进度统一通过 POST SSE 返回；这避免 Node.js 26 中长连接占用后续 tools/list 请求而触发固定 60 秒超时。普通 MCP Proxy 默认仍保留 standalone SSE，只有显式设置 disable_standalone_sse 才会关闭。

taptap-maker doctor 会检查 Git、Python 环境、maker-lua-lsp、PAT、TapTap token、项目绑定、 AI dev kit 版本和 MCP 配置。maker://status 和 maker_status_lite 会输出 MCP client roots 和 project_context_source，用来确认当前项目来自客户端 workspace roots，还是 MCP cwd fallback。默认 status 只输出快速本地摘要；需要远端同步、proxy、dev-kit 或完整维护诊断时，调用 maker_status_lite({ detail: true })。若 Git 不可用，clone/push 会直接停止，直到你自行安装 Git 并通过 git --version 验证。
已绑定项目还会执行轻量的统一项目结构检查：分别检查 .project/project.json、.project/resources.json、.project/settings.json，识别实际存在的配置被 AI 写坏或移动到项目根目录、

以及已知 assets/project.json 错位的情况。根目录候选只有在匹配 Maker $schema 或完整的 project.json 发布字段组合时才会判定为错位；普通同名业务文件不会阻断构建。.project 目录是否存在不代表项目已经初始化；目录为空、只含本地音色 mapping/其它辅助文件，或主配置不完整时，项目保持 not_initialized 且允许显式构建。dist 是构建产物，不参与源配置有效性判断。
构建会在 commit/push 前阻断实际存在配置的明确路径或 JSON 错误，generate_test_qrcode、 get_ad_config 和测试白名单会在远端调用前检查主配置，但不会自动搬运或覆盖本地文件。
广告接入先读 maker://ads-integration-guide：确认项目 → 获取配置 → 核对远端/本地配置 → 阅读 SDK → 实现 → 真机验证；远端同步成功不代表本机广告配置已更新。
健康检查本身保持只读；需要修复时，AI 应优先从 Git 或完整的错位副本恢复文件。只有在 settings.json 仍是可解析 object 时，才可恢复 $schema 和构建固定字段（资源 tag 仅从完整副本恢复），并保留 @runtime 与未知字段；不要凭默认值重建 project_id、入口、版本、发布信息或资源分组。
在用户确认后，可以只补入缺失且不会覆盖意图的 settings 默认字段：output_dir=../dist、
asset_dirs=["../assets","../scripts"]、generate_fs_path=true、asset_ignores=[]，
以及 schema 中的 assets_7z_threshold=50、preload_include_refs=true、
trim_remote_refs=true、legacy_binary=false、tags={}；已有非默认值不得覆盖。
sources.*.tag、项目身份、版本、入口、发布信息和 resources 分组只允许从完整副本恢复。
taptap-maker mcp verify 默认使用安装器的稳定 self runtime 完成 MCP initialize 和 tools/list；显式 --mode npx 才验证精确版本 npm launcher。失败结果会标明 stage、failure_type、最终 command 和 stderr，并返回非零退出码；不要把本地启动或 stdio 握手失败误判为 PAT 或 Maker 业务接口错误。

测试时优先运行 taptap-maker login；CLI 会按需打开 Maker 授权页，授权完成后自动完成本地鉴权配置。
当前目录未绑定时，APP_ID 应通过 taptap-maker init 或 taptap-maker apps 返回的 app 列表让用户选择；创建新项目时使用 taptap-maker init 列表底部的 0. Create a new Maker project，或运行 taptap-maker init --create --name "my-local-game"；checkout 完成后会补齐 assets/image、 assets/sprites、assets/video、assets/audio 和 scripts 基础目录；当前目录已绑定时不要再次引导 clone 或创建新项目。

npm run build
npx @modelcontextprotocol/inspector node dist/maker.js

详细说明见 docs/MAKER.md。

环境变量

OAuth 认证（推荐）:

- 无需配置！自动保存 token 到 ~/.config/taptap-minigame/

手动配置（可选）:

- TAPTAP_MCP_MAC_TOKEN - MAC Token（JSON 格式）
- TAPTAP_MCP_CLIENT_ID - 客户端 ID（非必需，不配置会导致部分工具无法使用）
- TAPTAP_MCP_CLIENT_SECRET - 签名密钥（非必需，不配置会导致部分工具无法使用）

其他:

- TAPTAP_MCP_ENV - 环境：production（默认）或 rnd
- TAPTAP_MCP_DC_CURRENT_APP_BASE_URL - 当前游戏 DC 接口 host 覆盖（可选，路径仍为 /mcp/v1/current-app/...）
- TAPTAP_MCP_TRANSPORT - 传输模式：stdio（默认）、sse、http
- TAPTAP_MCP_PORT - 端口（默认 3000）
- TAPTAP_MAKER_CRASH_LOG_MAX_BYTES - Maker MCP 崩溃日志 ~/.taptap-maker/mcp-crash.log 上限，默认 1 MiB
- TAPTAP_MAKER_CRASH_LOG_MAX_ENTRY_BYTES - Maker MCP 单条崩溃日志上限，默认 16 KiB
- TAPTAP_MCP_VERBOSE - 详细日志：true 或 false
- TAPTAP_MCP_CACHE_DIR - 缓存目录（默认 /tmp/taptap-mcp/cache）
- TAPTAP_MCP_TEMP_DIR - 临时文件目录（默认 /tmp/taptap-mcp/temp）

日志配置:

- TAPTAP_MCP_LOG_ROOT - 日志根目录（默认 /tmp/taptap-mcp/logs）
- TAPTAP_MCP_LOG_FILE - 启用文件日志：true 或 false（默认 false）
- TAPTAP_MCP_LOG_LEVEL - 日志级别（RFC 5424）：debug、info、notice、warning、error、critical、alert、emergency（默认 info）
- TAPTAP_MCP_LOG_MAX_DAYS - 日志保留天数（默认 7）

详细说明请参考 docs/LOG_SYSTEM.md

环境切换帮助

如果需要在 AI 对话中切换测试环境，可以让 AI 调用 get_environment_switch_guide 查看配置示例，再更新 MCP 客户端配置中的 env 字段。
RND 环境需要显式配置 TAPTAP_MCP_CLIENT_ID 和 TAPTAP_MCP_CLIENT_SECRET， production 通常使用内置 native signer，无需额外配置。

添加新功能

使用脚手架 ./scripts/create-feature.sh

按提示输入功能信息自动生成模块结构到 src/features/yourFeature/

🤖 AI Agent 智能引导

本服务器经过精心设计，通过工具描述引导 AI Agent 提供更智能的用户体验：

自动前置条件检查

AI Agent 会在执行排行榜操作前，自动检查是否已选择应用：

用户: "创建一个排行榜"

AI: 让我先检查当前是否已选择应用... [调用 get_current_app_info]

发现尚未选择应用，我来帮您列出可用的应用： [调用 list_developers_and_apps]

请问您想为哪个应用创建排行榜？
共 200 个应用，当前先展示前 40 个；如果没有看到目标应用，可以继续查看更多，或提供 App ID/名称关键词继续定位。
如果客户端宽度足够，可以把预览整理成两列紧凑布局；窄屏保持单列。
1. 游戏 A (Developer: 开发者A, App ID: 12345)
2. 游戏 B (Developer: 开发者B, App ID: 67890)

主动询问用户选择

当有多个选项时，AI Agent 会主动展示列表并询问用户：

用户: "查看排行榜"

AI: 您有以下几个排行榜：
1. 每日高分榜 (ID: lb_001)
2. 周排行榜 (ID: lb_002)
3. 全服总榜 (ID: lb_003)

请问您想查看哪一个？

工作流程自动优化

AI Agent 会自动引导用户完成必要的步骤，避免操作失败：

graph LR
A[用户请求] --> B{检查应用选择}
B -->|未选择| C[列出应用]
C --> D[询问用户]
D --> E[选择应用]
E --> F[执行操作]
B -->|已选择| F

受益场景：

- 创建/查询排行榜
- 发布排行榜
- 上传 H5 游戏
- 所有需要应用上下文的操作

技术实现： 通过在工具描述中使用 PREREQUISITE:、CRITICAL:、IMPORTANT: 等关键词，以及明确的步骤指导，让 AI Agent 理解何时需要检查前置条件、何时应该询问用户。

详见：CLAUDE.md - AI Agent 工具使用指导

📚 文档

用户文档

- docs/USER_GUIDE.md - 🐣 新手配置指南（Cursor/VS Code/Claude Code）
- CONTRIBUTING.md - 贡献指南
- CHANGELOG.md - 版本变更历史

技术文档

- docs/ARCHITECTURE.md - 架构文档
- docs/DEPLOYMENT.md - 部署指南（本地、Docker、开发者测试）
- docs/PROXY.md - MCP Proxy 开发指南（面向 TapCode 等平台）。
通用 Proxy 默认不添加 local 来源标记；本地 Maker 嵌入入口显式启用，服务端无需修改配置。
- docs/PATH_RESOLUTION.md - 路径解析系统

Maker 持久化 Proxy 与多项目

Maker MCP 在本地 server 进程内按活动项目维护一个 embedded proxy 和远端 MCP session。
多个本地 Maker 项目可以并行使用，项目、环境和授权上下文彼此隔离；一个项目断线只会触发该项目的自动恢复，不需要重新安装或重启 Maker MCP。MCP 包版本升级或本地 proxy 工具白名单/schema 变化后，需要重新连接本地 MCP 以加载新的本地定义。同项目认证或环境变化时，新连接立即接管，旧连接会在已开始的请求结束后关闭，不会中断正在执行的构建或远端工具。proxy tools 不依赖运行时 tools/list_changed 刷新。runtime-log watcher 保持独立的轮询连接生命周期，不与远端 proxy session 共享。

Windows 本地 stdio 代理隐藏命令行窗口；代理异常退出会结束当前请求的等待，后续操作可重建连接。
已提交的图片或视频生成仍按结果未知处理，不自动重复付费生成。关闭仅确认本实例直属子进程的退出，不按旧 PID 强杀进程树，也不将本地管道关闭当作孙进程已回收。详见控制台代理进程说明。
控制台清理失败时禁止新操作，但保留关闭重试入口；通过 console status 查看错误，再运行 console stop 重试。停止命令接受请求不代表进程已经退出，不会自动重复生成。

🤝 贡献

欢迎贡献！请遵循：

1. Fork 仓库并创建 feature 分支
2. 使用 Conventional Commits 规范
3. 创建 PR，等待 CI 检查
4. Review 通过后合并

📄 许可证

MIT

🔗 相关链接

- TapTap 开发者中心
- 官方 API 文档
- MCP 协议规范
- Issues

Windows 本地预览分两种：AI 调试用 taptap-maker preview run --target-dir <项目绝对路径> --json，保持前台会话，按 session 查询日志或停止；默认最多 10 分钟，--duration-ms 可缩短。
给用户预览用 preview start 或 console open 后点击预览；控制台自动启动并直接管理游戏，不再要求手动启动 Host。两种用途共用准备、日志和停止逻辑；常驻窗口截图及游戏断言 JSON 尚不支持，一次性引擎验证报告和截图使用 preview validate，再按 run-lua-validate Skill 检查。
正常路径不调用 WMI；仅显式 --legacy-wmi 使用旧入口。详见 docs/MAKER_LOCAL_PREVIEW.md。

Preview preparation now runs asynchronously without changing launch ownership. Agent refresh keeps
the session alive and returns final-round evidence; Runtime exit drains pending Lua logs within
bounds. Process/window creation alone does not establish that a game loaded or is playable.