@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.
- package/README.md +266 -153
- package/dist/{auth → core/auth}/deviceFlow.d.ts +28 -2
- package/dist/core/auth/deviceFlow.d.ts.map +1 -0
- package/dist/{auth → core/auth}/deviceFlow.js +130 -12
- package/dist/core/auth/deviceFlow.js.map +1 -0
- package/dist/core/handlers/appHandlers.d.ts +9 -0
- package/dist/core/handlers/appHandlers.d.ts.map +1 -0
- package/dist/core/handlers/appHandlers.js +9 -0
- package/dist/core/handlers/appHandlers.js.map +1 -0
- package/dist/core/handlers/environmentHandlers.d.ts.map +1 -0
- package/dist/core/handlers/environmentHandlers.js +57 -0
- package/dist/core/handlers/environmentHandlers.js.map +1 -0
- package/dist/{network → core/network}/httpClient.d.ts +4 -0
- package/dist/core/network/httpClient.d.ts.map +1 -0
- package/dist/{network → core/network}/httpClient.js +66 -22
- package/dist/core/network/httpClient.js.map +1 -0
- package/dist/core/types/index.d.ts +96 -0
- package/dist/core/types/index.d.ts.map +1 -0
- package/dist/core/types/index.js.map +1 -0
- package/dist/core/utils/cache.d.ts.map +1 -0
- package/dist/core/utils/cache.js.map +1 -0
- package/dist/core/utils/docHelpers.d.ts +92 -0
- package/dist/core/utils/docHelpers.d.ts.map +1 -0
- package/dist/core/utils/docHelpers.js +138 -0
- package/dist/core/utils/docHelpers.js.map +1 -0
- package/dist/core/utils/logger.d.ts +102 -0
- package/dist/core/utils/logger.d.ts.map +1 -0
- package/dist/core/utils/logger.js +353 -0
- package/dist/core/utils/logger.js.map +1 -0
- package/dist/features/app/api.d.ts +144 -0
- package/dist/features/app/api.d.ts.map +1 -0
- package/dist/features/app/api.js +231 -0
- package/dist/features/app/api.js.map +1 -0
- package/dist/{handlers/appHandlers.d.ts → features/app/handlers.d.ts} +9 -7
- package/dist/features/app/handlers.d.ts.map +1 -0
- package/dist/{handlers/appHandlers.js → features/app/handlers.js} +46 -2
- package/dist/{handlers/appHandlers.js.map → features/app/handlers.js.map} +1 -1
- package/dist/features/app/index.d.ts +10 -0
- package/dist/features/app/index.d.ts.map +1 -0
- package/dist/features/app/index.js +14 -0
- package/dist/features/app/index.js.map +1 -0
- package/dist/features/app/tools.d.ts +11 -0
- package/dist/features/app/tools.d.ts.map +1 -0
- package/dist/features/app/tools.js +169 -0
- package/dist/features/app/tools.js.map +1 -0
- package/dist/features/h5Game/api.d.ts +20 -0
- package/dist/features/h5Game/api.d.ts.map +1 -0
- package/dist/features/h5Game/api.js +16 -0
- package/dist/features/h5Game/api.js.map +1 -0
- package/dist/features/h5Game/handlers.d.ts +49 -0
- package/dist/features/h5Game/handlers.d.ts.map +1 -0
- package/dist/features/h5Game/handlers.js +321 -0
- package/dist/features/h5Game/handlers.js.map +1 -0
- package/dist/features/h5Game/index.d.ts +7 -0
- package/dist/features/h5Game/index.d.ts.map +1 -0
- package/dist/features/h5Game/index.js +11 -0
- package/dist/features/h5Game/index.js.map +1 -0
- package/dist/features/h5Game/messages.d.ts +79 -0
- package/dist/features/h5Game/messages.d.ts.map +1 -0
- package/dist/features/h5Game/messages.js +141 -0
- package/dist/features/h5Game/messages.js.map +1 -0
- package/dist/features/h5Game/tools.d.ts +14 -0
- package/dist/features/h5Game/tools.d.ts.map +1 -0
- package/dist/features/h5Game/tools.js +181 -0
- package/dist/features/h5Game/tools.js.map +1 -0
- package/dist/features/h5Game/types.d.ts +113 -0
- package/dist/features/h5Game/types.d.ts.map +1 -0
- package/dist/features/h5Game/types.js +2 -0
- package/dist/features/h5Game/types.js.map +1 -0
- package/dist/{network/leaderboardApi.d.ts → features/leaderboard/api.d.ts} +1 -64
- package/dist/features/leaderboard/api.d.ts.map +1 -0
- package/dist/{network/leaderboardApi.js → features/leaderboard/api.js} +3 -151
- package/dist/features/leaderboard/api.js.map +1 -0
- package/dist/{tools/leaderboardTools.d.ts → features/leaderboard/docTools.d.ts} +6 -1
- package/dist/features/leaderboard/docTools.d.ts.map +1 -0
- package/dist/{tools/leaderboardTools.js → features/leaderboard/docTools.js} +125 -51
- package/dist/features/leaderboard/docTools.js.map +1 -0
- package/dist/features/leaderboard/docs.d.ts +11 -0
- package/dist/features/leaderboard/docs.d.ts.map +1 -0
- package/dist/{data/leaderboardDocs.js → features/leaderboard/docs.js} +5 -127
- package/dist/features/leaderboard/docs.js.map +1 -0
- package/dist/{handlers/leaderboardHandlers.d.ts → features/leaderboard/handlers.d.ts} +1 -1
- package/dist/features/leaderboard/handlers.d.ts.map +1 -0
- package/dist/{handlers/leaderboardHandlers.js → features/leaderboard/handlers.js} +37 -20
- package/dist/features/leaderboard/handlers.js.map +1 -0
- package/dist/features/leaderboard/index.d.ts +10 -0
- package/dist/features/leaderboard/index.d.ts.map +1 -0
- package/dist/features/leaderboard/index.js +27 -0
- package/dist/features/leaderboard/index.js.map +1 -0
- package/dist/features/leaderboard/resources.d.ts +11 -0
- package/dist/features/leaderboard/resources.d.ts.map +1 -0
- package/dist/features/leaderboard/resources.js +68 -0
- package/dist/features/leaderboard/resources.js.map +1 -0
- package/dist/features/leaderboard/tools.d.ts +11 -0
- package/dist/features/leaderboard/tools.d.ts.map +1 -0
- package/dist/features/leaderboard/tools.js +146 -0
- package/dist/features/leaderboard/tools.js.map +1 -0
- package/dist/server.js +389 -143
- package/dist/server.js.map +1 -1
- package/dist/version.d.ts +2 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +15 -0
- package/dist/version.js.map +1 -0
- package/package.json +12 -9
- package/dist/auth/deviceFlow.d.ts.map +0 -1
- package/dist/auth/deviceFlow.js.map +0 -1
- package/dist/config/promptDefinitions.d.ts +0 -19
- package/dist/config/promptDefinitions.d.ts.map +0 -1
- package/dist/config/promptDefinitions.js +0 -28
- package/dist/config/promptDefinitions.js.map +0 -1
- package/dist/config/resourceDefinitions.d.ts +0 -19
- package/dist/config/resourceDefinitions.d.ts.map +0 -1
- package/dist/config/resourceDefinitions.js +0 -93
- package/dist/config/resourceDefinitions.js.map +0 -1
- package/dist/config/toolDefinitions.d.ts +0 -10
- package/dist/config/toolDefinitions.d.ts.map +0 -1
- package/dist/config/toolDefinitions.js +0 -250
- package/dist/config/toolDefinitions.js.map +0 -1
- package/dist/data/leaderboardDocs.d.ts +0 -37
- package/dist/data/leaderboardDocs.d.ts.map +0 -1
- package/dist/data/leaderboardDocs.js.map +0 -1
- package/dist/handlers/appHandlers.d.ts.map +0 -1
- package/dist/handlers/environmentHandlers.d.ts.map +0 -1
- package/dist/handlers/environmentHandlers.js +0 -21
- package/dist/handlers/environmentHandlers.js.map +0 -1
- package/dist/handlers/leaderboardHandlers.d.ts.map +0 -1
- package/dist/handlers/leaderboardHandlers.js.map +0 -1
- package/dist/handlers/promptHandlers.d.ts +0 -26
- package/dist/handlers/promptHandlers.d.ts.map +0 -1
- package/dist/handlers/promptHandlers.js +0 -336
- package/dist/handlers/promptHandlers.js.map +0 -1
- package/dist/network/httpClient.d.ts.map +0 -1
- package/dist/network/httpClient.js.map +0 -1
- package/dist/network/leaderboardApi.d.ts.map +0 -1
- package/dist/network/leaderboardApi.js.map +0 -1
- package/dist/tools/leaderboardTools.d.ts.map +0 -1
- package/dist/tools/leaderboardTools.js.map +0 -1
- package/dist/types/index.d.ts +0 -18
- package/dist/types/index.d.ts.map +0 -1
- package/dist/types/index.js.map +0 -1
- package/dist/utils/cache.d.ts.map +0 -1
- package/dist/utils/cache.js.map +0 -1
- package/dist/utils/logger.d.ts +0 -45
- package/dist/utils/logger.d.ts.map +0 -1
- package/dist/utils/logger.js +0 -192
- package/dist/utils/logger.js.map +0 -1
- /package/dist/{handlers → core/handlers}/environmentHandlers.d.ts +0 -0
- /package/dist/{types → core/types}/index.js +0 -0
- /package/dist/{utils → core/utils}/cache.d.ts +0 -0
- /package/dist/{utils → core/utils}/cache.js +0 -0
package/README.md
CHANGED
|
@@ -1,272 +1,385 @@
|
|
|
1
|
-
# TapTap
|
|
1
|
+
# TapTap Open API MCP 服务器
|
|
2
2
|
|
|
3
|
-
> Model Context Protocol (MCP)
|
|
3
|
+
> 基于 Model Context Protocol (MCP) 的 **TapTap 小游戏和 H5 游戏**服务器 - 提供排行榜文档和管理 API,支持 **OAuth 2.0 零配置认证**。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
🔐 **零配置 OAuth** | 📚 **完整文档** | 🎯 **模块化架构** | 🌍 **小游戏 & H5**
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## 功能特性
|
|
8
8
|
|
|
9
|
-
###
|
|
9
|
+
### 🔐 零配置 OAuth 认证
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
-
|
|
15
|
-
-
|
|
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
|
-
|
|
20
|
-
- Method signature
|
|
21
|
-
- Parameter descriptions
|
|
22
|
-
- Return values
|
|
23
|
-
- Complete code examples
|
|
24
|
-
- Error handling
|
|
17
|
+
### 📖 完整的 API 文档
|
|
25
18
|
|
|
26
|
-
|
|
19
|
+
6 个 LeaderboardManager API 及详细文档:
|
|
20
|
+
- `tap.getLeaderboardManager()` - 初始化排行榜
|
|
21
|
+
- `submitScores()` - 提交玩家分数
|
|
22
|
+
- `openLeaderboard()` - 显示排行榜 UI
|
|
23
|
+
- `loadLeaderboardScores()` - 获取排行榜数据
|
|
24
|
+
- `loadCurrentPlayerLeaderboardScore()` - 获取玩家排名
|
|
25
|
+
- `loadPlayerCenteredScores()` - 加载周围玩家
|
|
27
26
|
|
|
28
|
-
|
|
29
|
-
-
|
|
30
|
-
-
|
|
31
|
-
-
|
|
27
|
+
**⚠️ 关键提示:无需安装任何 SDK!**
|
|
28
|
+
- `tap` 是全局对象(类似 `window`)
|
|
29
|
+
- 不需要 `npm install`
|
|
30
|
+
- 不需要 import
|
|
32
31
|
|
|
33
|
-
###
|
|
32
|
+
### ⚙️ 服务端管理
|
|
34
33
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
34
|
+
- **创建排行榜** - 服务端创建排行榜
|
|
35
|
+
- **列出排行榜** - 查询现有排行榜
|
|
36
|
+
- **自动 ID 管理** - 自动获取 developer_id、app_id、miniapp_id
|
|
37
|
+
- **完整集成指南** - 分步骤工作流
|
|
39
38
|
|
|
40
|
-
|
|
39
|
+
### 🎯 模块化架构
|
|
41
40
|
|
|
42
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
68
|
+
### 配置
|
|
69
|
+
|
|
70
|
+
#### 在 Claude Code / VSCode / Cursor 中使用(零配置 OAuth)
|
|
55
71
|
|
|
56
|
-
|
|
72
|
+
**推荐**:使用 OAuth Device Code Flow - 无需手动配置 token!
|
|
57
73
|
|
|
58
|
-
|
|
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
|
-
"
|
|
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
|
-
|
|
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
|
-
"
|
|
88
|
-
"
|
|
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
|
-
####
|
|
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
|
-
"
|
|
107
|
-
"
|
|
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
|
-
###
|
|
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
|
-
|
|
119
|
-
- `TDS_MCP_MAC_TOKEN` - MAC Token
|
|
120
|
-
- `TDS_MCP_CLIENT_ID` -
|
|
121
|
-
- `TDS_MCP_CLIENT_TOKEN` -
|
|
198
|
+
**手动配置(可选):**
|
|
199
|
+
- `TDS_MCP_MAC_TOKEN` - MAC Token JSON 格式(可选,不设置则使用 OAuth)
|
|
200
|
+
- `TDS_MCP_CLIENT_ID` - 客户端 ID(已内置默认值,可覆盖)
|
|
201
|
+
- `TDS_MCP_CLIENT_TOKEN` - 签名密钥(已内置默认值,可覆盖)
|
|
122
202
|
|
|
123
|
-
|
|
124
|
-
- `TDS_MCP_ENV` -
|
|
125
|
-
- `TDS_MCP_PROJECT_PATH` -
|
|
126
|
-
- `
|
|
203
|
+
**其他配置:**
|
|
204
|
+
- `TDS_MCP_ENV` - 环境选择:`production`(默认)或 `rnd`
|
|
205
|
+
- `TDS_MCP_PROJECT_PATH` - 项目路径,用于本地缓存
|
|
206
|
+
- `TDS_MCP_VERBOSE` - 详细日志:`true` 或 `false`(默认)
|
|
127
207
|
|
|
128
|
-
|
|
208
|
+
**调试模式:**
|
|
129
209
|
|
|
130
|
-
|
|
210
|
+
启用详细日志查看所有工具调用、HTTP 请求/响应:
|
|
131
211
|
|
|
132
212
|
```bash
|
|
133
|
-
export
|
|
213
|
+
export TDS_MCP_VERBOSE=true
|
|
134
214
|
npm start
|
|
135
215
|
```
|
|
136
216
|
|
|
137
|
-
|
|
138
|
-
- 📥
|
|
139
|
-
- 📤 HTTP
|
|
140
|
-
- 📥 HTTP
|
|
141
|
-
- 🔒
|
|
217
|
+
详细日志包含:
|
|
218
|
+
- 📥 工具调用的输入和输出
|
|
219
|
+
- 📤 HTTP 请求头和请求体
|
|
220
|
+
- 📥 HTTP 响应状态和数据
|
|
221
|
+
- 🔒 敏感数据自动脱敏
|
|
142
222
|
|
|
143
|
-
##
|
|
223
|
+
## 使用示例
|
|
144
224
|
|
|
145
|
-
###
|
|
225
|
+
### 场景 1: 接入排行榜功能
|
|
146
226
|
|
|
147
227
|
```
|
|
148
|
-
|
|
228
|
+
用户: "我想在游戏中接入排行榜功能"
|
|
149
229
|
|
|
150
|
-
AI
|
|
230
|
+
AI 调用: get_integration_guide
|
|
151
231
|
|
|
152
|
-
|
|
153
|
-
✅
|
|
154
|
-
✅
|
|
155
|
-
✅
|
|
156
|
-
✅
|
|
232
|
+
返回: 完整的分步骤工作流
|
|
233
|
+
✅ 强调无需安装 SDK
|
|
234
|
+
✅ 步骤 1: 检查/创建服务端排行榜
|
|
235
|
+
✅ 步骤 2: 客户端代码(使用全局 tap 对象)
|
|
236
|
+
✅ 步骤 3: 测试检查清单
|
|
237
|
+
✅ 列出所有 Resources 供详细阅读
|
|
157
238
|
```
|
|
158
239
|
|
|
159
|
-
###
|
|
240
|
+
### 场景 2: 获取 API 文档
|
|
160
241
|
|
|
242
|
+
**在 Claude Code 中**(AI 自动读取):
|
|
161
243
|
```
|
|
162
|
-
|
|
244
|
+
用户: "如何提交分数?"
|
|
163
245
|
|
|
164
|
-
AI
|
|
246
|
+
AI 读取: docs://leaderboard/api/submit-scores
|
|
165
247
|
|
|
166
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
270
|
+
步骤:
|
|
271
|
+
1. 点击链接在浏览器打开
|
|
272
|
+
2. 用 TapTap App 扫码
|
|
273
|
+
3. 调用 complete_oauth_authorization
|
|
274
|
+
4. 重新执行
|
|
195
275
|
|
|
196
|
-
|
|
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
|
-
|
|
205
|
-
- `create_leaderboard` - Create new leaderboards
|
|
206
|
-
- `list_leaderboards` - Query existing leaderboards
|
|
278
|
+
AI 调用: complete_oauth_authorization
|
|
207
279
|
|
|
208
|
-
|
|
209
|
-
- `search_leaderboard_docs` - Search documentation
|
|
210
|
-
- `get_leaderboard_overview` - System overview
|
|
211
|
-
- `get_leaderboard_patterns` - Best practices
|
|
280
|
+
返回: ✅ 授权完成!Token 已保存
|
|
212
281
|
|
|
213
|
-
|
|
214
|
-
- `check_environment` - Environment check
|
|
215
|
-
- `start_leaderboard_integration` - Workflow guidance
|
|
282
|
+
用户: "创建排行榜"
|
|
216
283
|
|
|
217
|
-
|
|
218
|
-
- `get_user_leaderboard_scores` - Query user scores (requires token)
|
|
284
|
+
AI 调用: create_leaderboard
|
|
219
285
|
|
|
220
|
-
|
|
286
|
+
返回: ✅ 排行榜创建成功!
|
|
287
|
+
🎮 客户端 ID: xxx
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
## 🏗️ 架构
|
|
221
291
|
|
|
222
|
-
###
|
|
292
|
+
### 模块化设计
|
|
223
293
|
|
|
224
|
-
|
|
294
|
+
v1.2.0-beta 引入了**完全模块化的架构**,每个功能都是自包含的:
|
|
225
295
|
|
|
226
296
|
```
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
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
|
-
|
|
347
|
+
## 📚 文档
|
|
237
348
|
|
|
238
|
-
|
|
349
|
+
- **README.md** - 本文件(用户指南)
|
|
350
|
+
- **CLAUDE.md** - Claude Code 集成指南
|
|
351
|
+
- **CONTRIBUTING.md** - 开发者贡献指南(添加新功能)
|
|
352
|
+
- **CHANGELOG.md** - 版本变更历史
|
|
239
353
|
|
|
240
|
-
|
|
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
|
-
|
|
356
|
+
想要添加新功能(云存档、分享等)?
|
|
247
357
|
|
|
248
|
-
|
|
249
|
-
-
|
|
358
|
+
查看 **CONTRIBUTING.md** 了解:
|
|
359
|
+
- 分步骤指南
|
|
360
|
+
- 代码结构
|
|
361
|
+
- 设计原则
|
|
362
|
+
- 快速脚手架:`./scripts/create-feature.sh`
|
|
250
363
|
|
|
251
|
-
|
|
364
|
+
## 📖 相关资源
|
|
252
365
|
|
|
253
|
-
|
|
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
|
-
|
|
256
|
-
- Valid TapTap user token
|
|
257
|
-
- Client ID and secret for API access
|
|
370
|
+
## 📊 版本
|
|
258
371
|
|
|
259
|
-
|
|
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
|
-
|
|
262
|
-
- https://developer.taptap.cn/minigameapidoc/dev/api/open-api/leaderboard/
|
|
375
|
+
推荐使用 **beta 版本**获得最佳体验!
|
|
263
376
|
|
|
264
|
-
##
|
|
377
|
+
## 📄 许可证
|
|
265
378
|
|
|
266
379
|
MIT
|
|
267
380
|
|
|
268
|
-
##
|
|
381
|
+
## 🔗 链接
|
|
269
382
|
|
|
270
|
-
- [TapTap
|
|
271
|
-
- [MCP
|
|
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
|
-
*
|
|
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"}
|