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 游戏支持 - 上传、发布、状态查询

• 🧭 当前游戏 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

Related MCP server: PersonalizationMCP

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

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）

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

普通初始化、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/，dsh plugin --profile web add @taptap/dsh-maker 一键安装），详见 docs/DSH_PLUGIN.md。该插件与 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 并更新当前目录。

如果 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 合并入口

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 空提交来唤醒远端 服务。push 失败时不会继续 build，会返回本地 commit、ahead 状态、stderr/stdout 和下一步建议， 交给本地 Agent/skill 处理 pull、rebase 或冲突；push 成功但 build 失败时，会明确说明代码已到 Maker 远端但构建失败。只有用户明确说“不提交，只构建云端版本”时，才传 confirm_remote_build_without_submit=true；该模式只构建 Maker 远端已提交版本，不会自动打开 Maker 页面。

远端 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 本地开发。 音频 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 从当前会话消失。

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 和测试白名单会在远端调用前检查主配置，但不会自动搬运或覆盖本地文件。 健康检查本身保持只读；需要修复时，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 等平台）

• 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 共享。

🤝 贡献

欢迎贡献！请遵循：

1. Fork 仓库并创建 feature 分支

2. 使用 Conventional Commits 规范

3. 创建 PR，等待 CI 检查

4. Review 通过后合并

📄 许可证

MIT

🔗 相关链接

• TapTap 开发者中心

• 官方 API 文档

• MCP 协议规范

• Issues