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 是 CLI 登录入口；它会按需打开 Maker 授权页，CLI 轮询授权结果并完成本地鉴权配置。 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 是重点支持目标，CLI 会在 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 中；CLI 只做只读诊断，并在安装结果中提示用户到 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，CLI 会就地更新 对应 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 获取； GitHub Release 继续提供预览版和离线安装 tarball。该插件与 L1 的裸 MCP 行不要同时启用。 其它 AI 编辑器应优先让本地 AI 复用 已验证的绝对 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.