@mikoto_zero/minigame-open-mcp 1.2.0-beta.7 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (150) hide show
  1. package/README.md +266 -153
  2. package/dist/{auth → core/auth}/deviceFlow.d.ts +28 -2
  3. package/dist/core/auth/deviceFlow.d.ts.map +1 -0
  4. package/dist/{auth → core/auth}/deviceFlow.js +130 -12
  5. package/dist/core/auth/deviceFlow.js.map +1 -0
  6. package/dist/core/handlers/appHandlers.d.ts +9 -0
  7. package/dist/core/handlers/appHandlers.d.ts.map +1 -0
  8. package/dist/core/handlers/appHandlers.js +9 -0
  9. package/dist/core/handlers/appHandlers.js.map +1 -0
  10. package/dist/core/handlers/environmentHandlers.d.ts.map +1 -0
  11. package/dist/core/handlers/environmentHandlers.js +57 -0
  12. package/dist/core/handlers/environmentHandlers.js.map +1 -0
  13. package/dist/{network → core/network}/httpClient.d.ts +4 -0
  14. package/dist/core/network/httpClient.d.ts.map +1 -0
  15. package/dist/{network → core/network}/httpClient.js +66 -22
  16. package/dist/core/network/httpClient.js.map +1 -0
  17. package/dist/core/types/index.d.ts +96 -0
  18. package/dist/core/types/index.d.ts.map +1 -0
  19. package/dist/core/types/index.js.map +1 -0
  20. package/dist/core/utils/cache.d.ts.map +1 -0
  21. package/dist/core/utils/cache.js.map +1 -0
  22. package/dist/core/utils/docHelpers.d.ts +92 -0
  23. package/dist/core/utils/docHelpers.d.ts.map +1 -0
  24. package/dist/core/utils/docHelpers.js +138 -0
  25. package/dist/core/utils/docHelpers.js.map +1 -0
  26. package/dist/core/utils/logger.d.ts +102 -0
  27. package/dist/core/utils/logger.d.ts.map +1 -0
  28. package/dist/core/utils/logger.js +353 -0
  29. package/dist/core/utils/logger.js.map +1 -0
  30. package/dist/features/app/api.d.ts +144 -0
  31. package/dist/features/app/api.d.ts.map +1 -0
  32. package/dist/features/app/api.js +231 -0
  33. package/dist/features/app/api.js.map +1 -0
  34. package/dist/{handlers/appHandlers.d.ts → features/app/handlers.d.ts} +9 -7
  35. package/dist/features/app/handlers.d.ts.map +1 -0
  36. package/dist/{handlers/appHandlers.js → features/app/handlers.js} +46 -2
  37. package/dist/{handlers/appHandlers.js.map → features/app/handlers.js.map} +1 -1
  38. package/dist/features/app/index.d.ts +10 -0
  39. package/dist/features/app/index.d.ts.map +1 -0
  40. package/dist/features/app/index.js +14 -0
  41. package/dist/features/app/index.js.map +1 -0
  42. package/dist/features/app/tools.d.ts +11 -0
  43. package/dist/features/app/tools.d.ts.map +1 -0
  44. package/dist/features/app/tools.js +169 -0
  45. package/dist/features/app/tools.js.map +1 -0
  46. package/dist/features/h5Game/api.d.ts +20 -0
  47. package/dist/features/h5Game/api.d.ts.map +1 -0
  48. package/dist/features/h5Game/api.js +16 -0
  49. package/dist/features/h5Game/api.js.map +1 -0
  50. package/dist/features/h5Game/handlers.d.ts +49 -0
  51. package/dist/features/h5Game/handlers.d.ts.map +1 -0
  52. package/dist/features/h5Game/handlers.js +321 -0
  53. package/dist/features/h5Game/handlers.js.map +1 -0
  54. package/dist/features/h5Game/index.d.ts +7 -0
  55. package/dist/features/h5Game/index.d.ts.map +1 -0
  56. package/dist/features/h5Game/index.js +11 -0
  57. package/dist/features/h5Game/index.js.map +1 -0
  58. package/dist/features/h5Game/messages.d.ts +79 -0
  59. package/dist/features/h5Game/messages.d.ts.map +1 -0
  60. package/dist/features/h5Game/messages.js +141 -0
  61. package/dist/features/h5Game/messages.js.map +1 -0
  62. package/dist/features/h5Game/tools.d.ts +14 -0
  63. package/dist/features/h5Game/tools.d.ts.map +1 -0
  64. package/dist/features/h5Game/tools.js +181 -0
  65. package/dist/features/h5Game/tools.js.map +1 -0
  66. package/dist/features/h5Game/types.d.ts +113 -0
  67. package/dist/features/h5Game/types.d.ts.map +1 -0
  68. package/dist/features/h5Game/types.js +2 -0
  69. package/dist/features/h5Game/types.js.map +1 -0
  70. package/dist/{network/leaderboardApi.d.ts → features/leaderboard/api.d.ts} +1 -64
  71. package/dist/features/leaderboard/api.d.ts.map +1 -0
  72. package/dist/{network/leaderboardApi.js → features/leaderboard/api.js} +3 -151
  73. package/dist/features/leaderboard/api.js.map +1 -0
  74. package/dist/{tools/leaderboardTools.d.ts → features/leaderboard/docTools.d.ts} +6 -1
  75. package/dist/features/leaderboard/docTools.d.ts.map +1 -0
  76. package/dist/{tools/leaderboardTools.js → features/leaderboard/docTools.js} +125 -51
  77. package/dist/features/leaderboard/docTools.js.map +1 -0
  78. package/dist/features/leaderboard/docs.d.ts +11 -0
  79. package/dist/features/leaderboard/docs.d.ts.map +1 -0
  80. package/dist/{data/leaderboardDocs.js → features/leaderboard/docs.js} +5 -127
  81. package/dist/features/leaderboard/docs.js.map +1 -0
  82. package/dist/{handlers/leaderboardHandlers.d.ts → features/leaderboard/handlers.d.ts} +1 -1
  83. package/dist/features/leaderboard/handlers.d.ts.map +1 -0
  84. package/dist/{handlers/leaderboardHandlers.js → features/leaderboard/handlers.js} +37 -20
  85. package/dist/features/leaderboard/handlers.js.map +1 -0
  86. package/dist/features/leaderboard/index.d.ts +10 -0
  87. package/dist/features/leaderboard/index.d.ts.map +1 -0
  88. package/dist/features/leaderboard/index.js +27 -0
  89. package/dist/features/leaderboard/index.js.map +1 -0
  90. package/dist/features/leaderboard/resources.d.ts +11 -0
  91. package/dist/features/leaderboard/resources.d.ts.map +1 -0
  92. package/dist/features/leaderboard/resources.js +68 -0
  93. package/dist/features/leaderboard/resources.js.map +1 -0
  94. package/dist/features/leaderboard/tools.d.ts +11 -0
  95. package/dist/features/leaderboard/tools.d.ts.map +1 -0
  96. package/dist/features/leaderboard/tools.js +146 -0
  97. package/dist/features/leaderboard/tools.js.map +1 -0
  98. package/dist/server.js +389 -143
  99. package/dist/server.js.map +1 -1
  100. package/dist/version.d.ts +2 -0
  101. package/dist/version.d.ts.map +1 -0
  102. package/dist/version.js +15 -0
  103. package/dist/version.js.map +1 -0
  104. package/package.json +12 -9
  105. package/dist/auth/deviceFlow.d.ts.map +0 -1
  106. package/dist/auth/deviceFlow.js.map +0 -1
  107. package/dist/config/promptDefinitions.d.ts +0 -19
  108. package/dist/config/promptDefinitions.d.ts.map +0 -1
  109. package/dist/config/promptDefinitions.js +0 -28
  110. package/dist/config/promptDefinitions.js.map +0 -1
  111. package/dist/config/resourceDefinitions.d.ts +0 -19
  112. package/dist/config/resourceDefinitions.d.ts.map +0 -1
  113. package/dist/config/resourceDefinitions.js +0 -93
  114. package/dist/config/resourceDefinitions.js.map +0 -1
  115. package/dist/config/toolDefinitions.d.ts +0 -10
  116. package/dist/config/toolDefinitions.d.ts.map +0 -1
  117. package/dist/config/toolDefinitions.js +0 -250
  118. package/dist/config/toolDefinitions.js.map +0 -1
  119. package/dist/data/leaderboardDocs.d.ts +0 -37
  120. package/dist/data/leaderboardDocs.d.ts.map +0 -1
  121. package/dist/data/leaderboardDocs.js.map +0 -1
  122. package/dist/handlers/appHandlers.d.ts.map +0 -1
  123. package/dist/handlers/environmentHandlers.d.ts.map +0 -1
  124. package/dist/handlers/environmentHandlers.js +0 -21
  125. package/dist/handlers/environmentHandlers.js.map +0 -1
  126. package/dist/handlers/leaderboardHandlers.d.ts.map +0 -1
  127. package/dist/handlers/leaderboardHandlers.js.map +0 -1
  128. package/dist/handlers/promptHandlers.d.ts +0 -26
  129. package/dist/handlers/promptHandlers.d.ts.map +0 -1
  130. package/dist/handlers/promptHandlers.js +0 -336
  131. package/dist/handlers/promptHandlers.js.map +0 -1
  132. package/dist/network/httpClient.d.ts.map +0 -1
  133. package/dist/network/httpClient.js.map +0 -1
  134. package/dist/network/leaderboardApi.d.ts.map +0 -1
  135. package/dist/network/leaderboardApi.js.map +0 -1
  136. package/dist/tools/leaderboardTools.d.ts.map +0 -1
  137. package/dist/tools/leaderboardTools.js.map +0 -1
  138. package/dist/types/index.d.ts +0 -18
  139. package/dist/types/index.d.ts.map +0 -1
  140. package/dist/types/index.js.map +0 -1
  141. package/dist/utils/cache.d.ts.map +0 -1
  142. package/dist/utils/cache.js.map +0 -1
  143. package/dist/utils/logger.d.ts +0 -45
  144. package/dist/utils/logger.d.ts.map +0 -1
  145. package/dist/utils/logger.js +0 -192
  146. package/dist/utils/logger.js.map +0 -1
  147. /package/dist/{handlers → core/handlers}/environmentHandlers.d.ts +0 -0
  148. /package/dist/{types → core/types}/index.js +0 -0
  149. /package/dist/{utils → core/utils}/cache.d.ts +0 -0
  150. /package/dist/{utils → core/utils}/cache.js +0 -0
package/README.md CHANGED
@@ -1,272 +1,385 @@
1
- # TapTap Minigame Open API MCP Server
1
+ # TapTap Open API MCP 服务器
2
2
 
3
- > Model Context Protocol (MCP) server for TapTap minigame leaderboard documentation and management APIs.
3
+ > 基于 Model Context Protocol (MCP) **TapTap 小游戏和 H5 游戏**服务器 - 提供排行榜文档和管理 API,支持 **OAuth 2.0 零配置认证**。
4
4
 
5
- 🚀 **Auto-fetch IDs** | 📚 **Complete Docs** | 🔧 **Server-side Management**
5
+ 🔐 **零配置 OAuth** | 📚 **完整文档** | 🎯 **模块化架构** | 🌍 **小游戏 & H5**
6
6
 
7
- ## Features
7
+ ## 功能特性
8
8
 
9
- ### 📖 LeaderboardManager API Documentation
9
+ ### 🔐 零配置 OAuth 认证
10
10
 
11
- Complete documentation for all 5 LeaderboardManager APIs:
12
- - `tap.getLeaderboardManager()` - Initialize leaderboard system
13
- - `openLeaderboard()` - Display leaderboard UI
14
- - `submitScores()` - Submit player scores
15
- - `loadLeaderboardScores()` - Fetch leaderboard data
16
- - `loadCurrentPlayerLeaderboardScore()` - Get player's rank
17
- - `loadPlayerCenteredScores()` - Load nearby players
11
+ - **无需手动配置 token!**
12
+ - Device Code Flow - 扫码即可授权
13
+ - 自动保存 token `~/.config/taptap-minigame/token.json`
14
+ - 支持 Cursor、Claude Code、VSCode
15
+ - 懒加载 - 服务器秒级启动,需要时才触发认证
18
16
 
19
- Each API includes:
20
- - Method signature
21
- - Parameter descriptions
22
- - Return values
23
- - Complete code examples
24
- - Error handling
17
+ ### 📖 完整的 API 文档
25
18
 
26
- ### ⚙️ Server-side Management
19
+ 6 LeaderboardManager API 及详细文档:
20
+ - `tap.getLeaderboardManager()` - 初始化排行榜
21
+ - `submitScores()` - 提交玩家分数
22
+ - `openLeaderboard()` - 显示排行榜 UI
23
+ - `loadLeaderboardScores()` - 获取排行榜数据
24
+ - `loadCurrentPlayerLeaderboardScore()` - 获取玩家排名
25
+ - `loadPlayerCenteredScores()` - 加载周围玩家
27
26
 
28
- - **Create Leaderboards** - Create new leaderboards via TapTap API
29
- - **List Leaderboards** - Query existing leaderboards
30
- - **Auto ID Management** - Automatically fetch and cache developer_id and app_id
31
- - **Smart Workflow** - Intelligent guidance for leaderboard integration
27
+ **⚠️ 关键提示:无需安装任何 SDK!**
28
+ - `tap` 是全局对象(类似 `window`)
29
+ - 不需要 `npm install`
30
+ - 不需要 import
32
31
 
33
- ### 🎯 Intelligent Workflow
32
+ ### ⚙️ 服务端管理
34
33
 
35
- The `start_leaderboard_integration` tool provides step-by-step guidance:
36
- 1. Check existing leaderboards
37
- 2. Create if needed
38
- 3. Guide implementation with docs
34
+ - **创建排行榜** - 服务端创建排行榜
35
+ - **列出排行榜** - 查询现有排行榜
36
+ - **自动 ID 管理** - 自动获取 developer_id、app_id、miniapp_id
37
+ - **完整集成指南** - 分步骤工作流
39
38
 
40
- ## Quick Start
39
+ ### 🎯 模块化架构
41
40
 
42
- ### Installation
41
+ - **17 个 Tools** - 完整的工具集(应用管理 + 排行榜 + H5 游戏)
42
+ - **7 个 Resources** - 详细 API 文档
43
+ - **模块化设计** - 易于添加新功能(云存档、分享等)
44
+ - **完全兼容** - Claude Code ✅、VSCode ✅、Cursor ✅、OpenHands ✅
45
+
46
+ ### 🚀 v1.2.0-beta.23 新特性
47
+
48
+ - **多客户端并发支持** - 无限客户端同时连接,独立会话管理
49
+ - **智能自动授权(SSE 模式)** - 一步完成授权,无需手动调用 `complete_oauth_authorization`
50
+ - **三种传输模式** - stdio(本地)、SSE(远程/实时)、HTTP JSON(兼容)
51
+ - **客户端连接日志** - verbose 模式下完整记录连接事件
52
+ - **实时进度推送** - SSE 模式下支持授权、上传、压缩等操作的实时进度
53
+
54
+ ## 快速开始
55
+
56
+ ### 安装
43
57
 
44
58
  ```bash
45
- npm install -g minigame-open-mcp
59
+ npm install -g @mikoto_zero/minigame-open-mcp
46
60
  ```
47
61
 
48
- Or use directly with npx (no installation needed):
62
+ 或使用 npx 直接运行(无需安装):
49
63
 
50
64
  ```bash
51
- npx minigame-open-mcp
65
+ npx @mikoto_zero/minigame-open-mcp@beta
52
66
  ```
53
67
 
54
- ### Configuration
68
+ ### 配置
69
+
70
+ #### 在 Claude Code / VSCode / Cursor 中使用(零配置 OAuth)
55
71
 
56
- #### For Claude Desktop
72
+ **推荐**:使用 OAuth Device Code Flow - 无需手动配置 token!
57
73
 
58
- Add to `~/.config/claude-desktop/config.json`:
74
+ 在项目中创建 `.mcp.json`:
59
75
 
60
76
  ```json
61
77
  {
62
78
  "mcpServers": {
63
79
  "taptap-minigame": {
64
80
  "command": "npx",
65
- "args": ["@mikoto_zero/minigame-open-mcp"],
81
+ "args": ["-y", "@mikoto_zero/minigame-open-mcp@beta"],
66
82
  "env": {
67
- "TDS_MCP_MAC_TOKEN": "{\"kid\":\"your_kid\",\"token_type\":\"mac\",\"mac_key\":\"your_key\",\"mac_algorithm\":\"hmac-sha-1\"}",
68
- "TDS_MCP_CLIENT_ID": "your_client_id",
69
- "TDS_MCP_CLIENT_TOKEN": "your_client_secret",
70
- "TAPTAP_MINIGAME_MCP_VERBOSE": "false"
83
+ "TDS_MCP_ENV": "production"
71
84
  }
72
85
  }
73
86
  }
74
87
  }
75
88
  ```
76
89
 
77
- **With debugging enabled:**
90
+ **首次使用流程(stdio 模式 - 默认)**:
91
+ 1. 服务器秒级启动
92
+ 2. 使用需要认证的功能时,会显示授权二维码链接
93
+ 3. 用 TapTap App 扫码授权
94
+ 4. 调用 `complete_oauth_authorization` 工具完成授权
95
+ 5. Token 自动保存,后续使用自动加载!
96
+
97
+ **SSE 模式(OpenHands 等)**:
98
+ - 步骤 2-4 自动完成,无需手动调用 `complete_oauth_authorization`
99
+ - 实时显示授权进度(每 10 秒更新)
100
+
101
+ **手动配置 Token**(可选):
102
+
103
+ 如果你想手动配置:
78
104
 
79
105
  ```json
80
106
  {
81
107
  "mcpServers": {
82
108
  "taptap-minigame": {
83
109
  "command": "npx",
84
- "args": ["@mikoto_zero/minigame-open-mcp"],
110
+ "args": ["@mikoto_zero/minigame-open-mcp@beta"],
85
111
  "env": {
86
112
  "TDS_MCP_MAC_TOKEN": "{\"kid\":\"your_kid\",\"token_type\":\"mac\",\"mac_key\":\"your_key\",\"mac_algorithm\":\"hmac-sha-1\"}",
87
- "TDS_MCP_CLIENT_ID": "your_client_id",
88
- "TDS_MCP_CLIENT_TOKEN": "your_client_secret",
89
- "TAPTAP_MINIGAME_MCP_VERBOSE": "true"
113
+ "TDS_MCP_ENV": "production",
114
+ "TDS_MCP_VERBOSE": "false"
90
115
  }
91
116
  }
92
117
  }
93
118
  }
94
119
  ```
95
120
 
96
- #### For OpenHands
121
+ #### OpenHands 中使用(推荐 SSE 模式)
122
+
123
+ **方式 1:SSE 远程模式(推荐 - 支持自动授权和实时进度)**
124
+
125
+ ```bash
126
+ # 1. 在服务器上启动 MCP 服务
127
+ TDS_MCP_TRANSPORT=sse TDS_MCP_PORT=3000 TDS_MCP_VERBOSE=true \
128
+ npx @mikoto_zero/minigame-open-mcp@beta
129
+
130
+ # 2. OpenHands 配置
131
+ {
132
+ "mcpServers": {
133
+ "taptap-minigame": {
134
+ "url": "http://your-server:3000",
135
+ "transport": "sse"
136
+ }
137
+ }
138
+ }
139
+ ```
140
+
141
+ **特性**:
142
+ - ✅ 一步式自动授权(无需手动调用 `complete_oauth_authorization`)
143
+ - ✅ 实时进度推送(授权、上传、压缩等)
144
+ - ✅ 多客户端并发支持
145
+ - ✅ 连接日志和监控
146
+
147
+ **方式 2:stdio 本地模式(兼容模式)**
97
148
 
98
149
  ```json
99
150
  {
100
151
  "mcpServers": {
101
152
  "taptap-minigame": {
102
153
  "command": "npx",
103
- "args": ["@mikoto_zero/minigame-open-mcp"],
154
+ "args": ["@mikoto_zero/minigame-open-mcp@beta"],
104
155
  "env": {
105
156
  "TDS_MCP_MAC_TOKEN": "${CURRENT_USER_MAC_TOKEN}",
106
- "TDS_MCP_CLIENT_ID": "your_client_id",
107
- "TDS_MCP_CLIENT_TOKEN": "your_client_secret",
108
- "TDS_MCP_PROJECT_PATH": "${CURRENT_PROJECT_PATH}",
109
- "TAPTAP_MINIGAME_MCP_VERBOSE": "false"
157
+ "TDS_MCP_ENV": "production",
158
+ "TDS_MCP_PROJECT_PATH": "${CURRENT_PROJECT_PATH}"
110
159
  }
111
160
  }
112
161
  }
113
162
  }
114
163
  ```
115
164
 
116
- ### Environment Variables
165
+ ### 传输模式
166
+
167
+ 服务器支持三种传输模式:
168
+
169
+ | 模式 | 配置 | 授权方式 | 进度反馈 | 适用场景 |
170
+ |------|------|---------|---------|---------|
171
+ | **stdio** | 默认 | 两步式 | ❌ | Claude Desktop、Cursor、本地单客户端 |
172
+ | **sse** | `TDS_MCP_TRANSPORT=sse` | **一步式自动** | ✅ 实时 | **OpenHands**、Claude Code、远程/多客户端 |
173
+ | **http** | `TDS_MCP_TRANSPORT=http` | 两步式 | ❌ | 普通 HTTP 客户端 |
174
+
175
+ **启动示例**:
176
+
177
+ ```bash
178
+ # SSE 模式(推荐用于 OpenHands)
179
+ TDS_MCP_TRANSPORT=sse TDS_MCP_PORT=3000 TDS_MCP_VERBOSE=true \
180
+ npx @mikoto_zero/minigame-open-mcp@beta
181
+
182
+ # HTTP JSON 模式
183
+ TDS_MCP_TRANSPORT=http TDS_MCP_PORT=3000 \
184
+ npx @mikoto_zero/minigame-open-mcp@beta
185
+
186
+ # stdio 模式(默认)
187
+ npx @mikoto_zero/minigame-open-mcp@beta
188
+ ```
189
+
190
+ ### 环境变量
191
+
192
+ **OAuth 认证(推荐 - 零配置):**
193
+ - ✅ 无需配置环境变量!
194
+ - Token 自动保存到 `~/.config/taptap-minigame/token.json`
195
+ - **SSE 模式**:自动授权,实时进度推送
196
+ - **stdio/http 模式**:两步式授权
117
197
 
118
- **Required:**
119
- - `TDS_MCP_MAC_TOKEN` - MAC Token in JSON format for authentication
120
- - `TDS_MCP_CLIENT_ID` - Client ID for API access
121
- - `TDS_MCP_CLIENT_TOKEN` - Client secret for request signing
198
+ **手动配置(可选):**
199
+ - `TDS_MCP_MAC_TOKEN` - MAC Token JSON 格式(可选,不设置则使用 OAuth)
200
+ - `TDS_MCP_CLIENT_ID` - 客户端 ID(已内置默认值,可覆盖)
201
+ - `TDS_MCP_CLIENT_TOKEN` - 签名密钥(已内置默认值,可覆盖)
122
202
 
123
- **Optional:**
124
- - `TDS_MCP_ENV` - Environment: `production` (default) or `rnd`
125
- - `TDS_MCP_PROJECT_PATH` - Project path for local caching
126
- - `TAPTAP_MINIGAME_MCP_VERBOSE` - Detailed logging: `true` or `false` (default)
203
+ **其他配置:**
204
+ - `TDS_MCP_ENV` - 环境选择:`production`(默认)或 `rnd`
205
+ - `TDS_MCP_PROJECT_PATH` - 项目路径,用于本地缓存
206
+ - `TDS_MCP_VERBOSE` - 详细日志:`true` `false`(默认)
127
207
 
128
- **Debugging:**
208
+ **调试模式:**
129
209
 
130
- Enable detailed logging to see all tool calls, HTTP requests/responses:
210
+ 启用详细日志查看所有工具调用、HTTP 请求/响应:
131
211
 
132
212
  ```bash
133
- export TAPTAP_MINIGAME_MCP_VERBOSE=true
213
+ export TDS_MCP_VERBOSE=true
134
214
  npm start
135
215
  ```
136
216
 
137
- The verbose mode logs:
138
- - 📥 Tool call inputs and outputs
139
- - 📤 HTTP request headers and body
140
- - 📥 HTTP response status and data
141
- - 🔒 Sensitive data automatically masked
217
+ 详细日志包含:
218
+ - 📥 工具调用的输入和输出
219
+ - 📤 HTTP 请求头和请求体
220
+ - 📥 HTTP 响应状态和数据
221
+ - 🔒 敏感数据自动脱敏
142
222
 
143
- ## Usage
223
+ ## 使用示例
144
224
 
145
- ### Scenario 1: Getting Started with Leaderboards
225
+ ### 场景 1: 接入排行榜功能
146
226
 
147
227
  ```
148
- User: "I want to integrate leaderboards into my game"
228
+ 用户: "我想在游戏中接入排行榜功能"
149
229
 
150
- AI Agent calls: start_leaderboard_integration
230
+ AI 调用: get_integration_guide
151
231
 
152
- System response:
153
- Checks existing leaderboards
154
- Guides creation if needed
155
- Shows available leaderboard features
156
- Provides next steps
232
+ 返回: 完整的分步骤工作流
233
+ 强调无需安装 SDK
234
+ 步骤 1: 检查/创建服务端排行榜
235
+ 步骤 2: 客户端代码(使用全局 tap 对象)
236
+ 步骤 3: 测试检查清单
237
+ ✅ 列出所有 Resources 供详细阅读
157
238
  ```
158
239
 
159
- ### Scenario 2: Get Implementation Code
240
+ ### 场景 2: 获取 API 文档
160
241
 
242
+ **在 Claude Code 中**(AI 自动读取):
161
243
  ```
162
- User: "How do I submit scores to the leaderboard?"
244
+ 用户: "如何提交分数?"
163
245
 
164
- AI Agent calls: submit_scores
246
+ AI 读取: docs://leaderboard/api/submit-scores
165
247
 
166
- System returns:
167
- ✅ Method signature: leaderboardManager.submitScores(scores, callback)
168
- ✅ Parameter documentation
169
- ✅ Complete code example
170
- ✅ Error handling guide
248
+ 返回: submitScores() 完整文档(参数、示例、错误码)
171
249
  ```
172
250
 
173
- ### Scenario 3: Create a Leaderboard
251
+ **在 VSCode 中**(调用工具):
252
+ ```
253
+ 用户: "如何提交分数?"
254
+
255
+ AI 调用: get_integration_guide
174
256
 
257
+ 返回: 完整工作流(包含代码示例)
175
258
  ```
176
- User: "Create a weekly high score leaderboard"
177
259
 
178
- AI Agent calls: create_leaderboard
179
- {
180
- title: "Weekly High Score",
181
- period_type: 1,
182
- score_type: 0,
183
- score_order: 1,
184
- calc_type: 0
185
- }
260
+ ### 场景 3: OAuth 授权流程
186
261
 
187
- System:
188
- ✅ Auto-fetches developer_id and app_id
189
- ✅ Creates leaderboard
190
- ✅ Returns leaderboard_id
191
- ✅ Caches for future use
192
262
  ```
263
+ 用户: "创建排行榜"
264
+
265
+ AI 调用: create_leaderboard
266
+
267
+ 返回: 🔐 需要授权
268
+ 🔗 https://www.taptap.cn/tap-qrcode?...
193
269
 
194
- ## Available Tools (14 total)
270
+ 步骤:
271
+ 1. 点击链接在浏览器打开
272
+ 2. 用 TapTap App 扫码
273
+ 3. 调用 complete_oauth_authorization
274
+ 4. 重新执行
195
275
 
196
- ### Core API Documentation Tools (6)
197
- - `get_leaderboard_manager`
198
- - `open_leaderboard`
199
- - `submit_scores`
200
- - `load_leaderboard_scores`
201
- - `load_current_player_score`
202
- - `load_player_centered_scores`
276
+ 用户: "我已经授权了"
203
277
 
204
- ### Management Tools (2)
205
- - `create_leaderboard` - Create new leaderboards
206
- - `list_leaderboards` - Query existing leaderboards
278
+ AI 调用: complete_oauth_authorization
207
279
 
208
- ### Helper Tools (3)
209
- - `search_leaderboard_docs` - Search documentation
210
- - `get_leaderboard_overview` - System overview
211
- - `get_leaderboard_patterns` - Best practices
280
+ 返回: 授权完成!Token 已保存
212
281
 
213
- ### System Tools (2)
214
- - `check_environment` - Environment check
215
- - `start_leaderboard_integration` - Workflow guidance
282
+ 用户: "创建排行榜"
216
283
 
217
- ### User Data Tool (1)
218
- - `get_user_leaderboard_scores` - Query user scores (requires token)
284
+ AI 调用: create_leaderboard
219
285
 
220
- ## Technical Details
286
+ 返回: 排行榜创建成功!
287
+ 🎮 客户端 ID: xxx
288
+ ```
289
+
290
+ ## 🏗️ 架构
221
291
 
222
- ### Request Signing
292
+ ### 模块化设计
223
293
 
224
- All server-side API requests use HMAC-SHA256 signing:
294
+ v1.2.0-beta 引入了**完全模块化的架构**,每个功能都是自包含的:
225
295
 
226
296
  ```
227
- Signature = HMAC-SHA256(
228
- method + "\n" +
229
- url + "\n" +
230
- x-tap-headers + "\n" +
231
- body + "\n",
232
- TDS_MCP_CLIENT_TOKEN
233
- )
297
+ src/
298
+ ├── features/ # 功能模块(自包含)
299
+ │ ├── app/ # 应用管理模块(基础功能)
300
+ │ │ ├── index.ts # 模块定义和注册
301
+ │ │ ├── tools.ts # 5 个工具(应用选择、环境检查等)
302
+ │ │ ├── handlers.ts # 业务逻辑
303
+ │ │ └── api.ts # API 调用
304
+ │ │
305
+ │ └── leaderboard/ # 排行榜模块
306
+ │ ├── index.ts # 模块定义和注册
307
+ │ ├── tools.ts # 5 个工具 + 处理器
308
+ │ ├── resources.ts # 7 个 Resources + 处理器
309
+ │ ├── docs.ts # 文档内容
310
+ │ ├── docTools.ts # 文档工具
311
+ │ ├── handlers.ts # 业务逻辑
312
+ │ └── api.ts # API 调用
313
+
314
+ ├── core/ # 共享核心功能
315
+ │ ├── auth/ # OAuth Device Code Flow
316
+ │ ├── network/ # HTTP 客户端
317
+ │ ├── handlers/ # 通用处理器(environment)
318
+ │ ├── utils/ # 缓存、日志、文档助手
319
+ │ └── types/ # 类型定义
320
+
321
+ └── server.ts # 主服务器(自动注册)
322
+ ```
323
+
324
+ **模块说明**:
325
+ - **app**: 基础应用管理(开发者/应用选择、OAuth 授权、环境检查)
326
+ - **leaderboard**: 排行榜功能(依赖 app 模块)
327
+ - 未来: cloudSave, share 等(都可以复用 app 模块)
328
+
329
+ **添加新功能**:
330
+ ```typescript
331
+ // 1. 使用脚手架创建新模块
332
+ ./scripts/create-feature.sh
333
+
334
+ // 2. 按照提示输入功能信息
335
+ // Feature Key: cloud-save
336
+ // Feature Name: 云存档
337
+ // Resources: yes
338
+ // Prompts: no
339
+
340
+ // 3. 在 server.ts 导入
341
+ import { cloudSaveModule } from './features/cloudSave/index.js';
342
+ const allModules = [appModule, leaderboardModule, cloudSaveModule];
343
+
344
+ // 完成!自动注册 ✅
234
345
  ```
235
346
 
236
- ### Auto ID Management
347
+ ## 📚 文档
237
348
 
238
- Developer ID and App ID are automatically managed:
349
+ - **README.md** - 本文件(用户指南)
350
+ - **CLAUDE.md** - Claude Code 集成指南
351
+ - **CONTRIBUTING.md** - 开发者贡献指南(添加新功能)
352
+ - **CHANGELOG.md** - 版本变更历史
239
353
 
240
- 1. First call to management tools triggers `/level/v1/list` API
241
- 2. Selects first developer and first app
242
- 3. Caches to `~/.config/taptap-minigame/app.json`
243
- 4. Subsequent calls use cached values
244
- 5. No manual ID input needed
354
+ ## 🤝 贡献
245
355
 
246
- ### Multi-Environment Support
356
+ 想要添加新功能(云存档、分享等)?
247
357
 
248
- - **Production** (default): `https://agent.tapapis.cn`
249
- - **RND**: `https://agent.api.xdrnd.cn`
358
+ 查看 **CONTRIBUTING.md** 了解:
359
+ - 分步骤指南
360
+ - 代码结构
361
+ - 设计原则
362
+ - 快速脚手架:`./scripts/create-feature.sh`
250
363
 
251
- Switch via `TDS_MCP_ENV` environment variable.
364
+ ## 📖 相关资源
252
365
 
253
- ## Requirements
366
+ - **官方 API 文档**: https://developer.taptap.cn/minigameapidoc/dev/api/open-api/leaderboard/
367
+ - **MCP 规范**: https://modelcontextprotocol.io/
368
+ - **npm 包**: [@mikoto_zero/minigame-open-mcp](https://www.npmjs.com/package/@mikoto_zero/minigame-open-mcp)
254
369
 
255
- - Node.js >= 16.0.0
256
- - Valid TapTap user token
257
- - Client ID and secret for API access
370
+ ## 📊 版本
258
371
 
259
- ## API Reference
372
+ - **latest (v1.1.4)**: 纯 Tools 稳定版(17 tools)
373
+ - **beta (v1.2.0-beta.12)**: 模块化架构(app + leaderboard)+ OAuth(10 tools + 7 resources)
260
374
 
261
- Based on TapTap official documentation:
262
- - https://developer.taptap.cn/minigameapidoc/dev/api/open-api/leaderboard/
375
+ 推荐使用 **beta 版本**获得最佳体验!
263
376
 
264
- ## License
377
+ ## 📄 许可证
265
378
 
266
379
  MIT
267
380
 
268
- ## Links
381
+ ## 🔗 链接
269
382
 
270
- - [TapTap Developer Portal](https://developer.taptap.cn/)
271
- - [MCP Protocol](https://modelcontextprotocol.io/)
383
+ - [TapTap 开发者中心](https://developer.taptap.cn/)
384
+ - [MCP 协议](https://modelcontextprotocol.io/)
272
385
  - [Issues](https://github.com/taptap/taptap-minigame-mcp-server/issues)
@@ -3,6 +3,18 @@
3
3
  * Based on tapcode-mcp-h5 implementation
4
4
  */
5
5
  import { MacToken } from '../types/index.js';
6
+ /**
7
+ * Progress callback for authorization polling
8
+ */
9
+ export interface AuthProgressCallback {
10
+ (info: {
11
+ type: 'auth_url' | 'polling' | 'success' | 'timeout' | 'error';
12
+ message: string;
13
+ authUrl?: string;
14
+ elapsed?: number;
15
+ remaining?: number;
16
+ }): void | Promise<void>;
17
+ }
6
18
  /**
7
19
  * Device Code Flow Authentication Manager
8
20
  */
@@ -18,7 +30,11 @@ export declare class DeviceFlowAuth {
18
30
  */
19
31
  initialize(): Promise<MacToken>;
20
32
  /**
21
- * Start Device Code Flow
33
+ * Get authorization URL (for manual auth flow)
34
+ */
35
+ getAuthorizationUrl(): Promise<string>;
36
+ /**
37
+ * Start Device Code Flow (blocking version for terminal use)
22
38
  */
23
39
  private startDeviceFlow;
24
40
  /**
@@ -30,13 +46,23 @@ export declare class DeviceFlowAuth {
30
46
  */
31
47
  private displayAuthorizationInfo;
32
48
  /**
33
- * Poll for access token
49
+ * Poll for access token with progress callback
34
50
  */
35
51
  private pollForToken;
36
52
  /**
37
53
  * Save token to local file
38
54
  */
39
55
  private saveToken;
56
+ /**
57
+ * Start auto authorization with progress callback
58
+ * For SSE mode: polls for authorization and reports progress
59
+ */
60
+ startAutoAuthorization(onProgress?: AuthProgressCallback): Promise<MacToken>;
61
+ /**
62
+ * Complete authorization by polling for token
63
+ * Call this after user has completed authorization in browser
64
+ */
65
+ completeAuthorization(): Promise<MacToken>;
40
66
  /**
41
67
  * Get current MAC token
42
68
  */
@@ -0,0 +1 @@
1
+ {"version":3,"file":"deviceFlow.d.ts","sourceRoot":"","sources":["../../../src/core/auth/deviceFlow.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AA+C7C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,CAAC,IAAI,EAAE;QACL,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;QAC/D,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,UAAU,CAAc;IAChC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,MAAM,CAAa;gBAEf,WAAW,GAAE,MAAqB;IAM9C;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,QAAQ,CAAC;IA6DrC;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC;IAM5C;;OAEG;YACW,eAAe;IAmB7B;;OAEG;YACW,iBAAiB;IA+B/B;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAehC;;OAEG;YACW,YAAY;IAwH1B;;OAEG;IACH,OAAO,CAAC,SAAS;IAmBjB;;;OAGG;IACG,sBAAsB,CAAC,UAAU,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAiClF;;;OAGG;IACG,qBAAqB,IAAI,OAAO,CAAC,QAAQ,CAAC;IAsBhD;;OAEG;IACH,QAAQ,IAAI,QAAQ,GAAG,SAAS;IAIhC;;OAEG;IACH,UAAU,IAAI,IAAI;CAYnB"}