@mikoto_zero/minigame-open-mcp 1.4.13 → 1.5.1

package/README.md

@@ -2,531 +2,263 @@
 
 > 基于 Model Context Protocol (MCP) 的 **TapTap 小游戏和 H5 游戏**服务器 - 提供排行榜文档和管理 API，支持 **OAuth 2.0 零配置认证**。
 
-🔐 **零配置 OAuth** | 📚 **完整文档** | 🎯 **模块化架构** | 🌍 **小游戏 & H5**
+🔐 **零配置 OAuth** | 📚 **完整文档** | 🎯 **17 Tools + 7 Resources** | 🌍 **小游戏 & H5**
 
-## 功能特性
+## ✨ 核心特性
 
-### 🔐 零配置 OAuth 认证
+- **🔐 零配置认证** - OAuth 2.0 Device Code Flow，扫码即用
+- **📖 完整 API 文档** - 6 个排行榜 API + 详细代码示例
+- **⚙️ 服务端管理** - 创建/管理排行榜，自动处理 ID
+- **🎮 H5 游戏支持** - 上传、发布、状态查询
+- **🚀 三种传输模式** - stdio（本地）、SSE（远程/实时）、HTTP（兼容）
+- **🔌 多客户端并发** - 独立会话管理，无限并发
 
-- **无需手动配置 token！**
-- Device Code Flow - 扫码即可授权
-- 自动保存 token 到 `~/.config/taptap-minigame/token.json`
-- 支持 Cursor、Claude Code、VSCode
-- 懒加载 - 服务器秒级启动，需要时才触发认证
+**当前版本**: v1.4.13 | **NPM**: [@mikoto_zero/minigame-open-mcp](https://www.npmjs.com/package/@mikoto_zero/minigame-open-mcp)
 
-### 📖 完整的 API 文档
+## 🚀 快速开始
 
-6 个 LeaderboardManager API 及详细文档：
-- `tap.getLeaderboardManager()` - 初始化排行榜
-- `submitScores()` - 提交玩家分数
-- `openLeaderboard()` - 显示排行榜 UI
-- `loadLeaderboardScores()` - 获取排行榜数据
-- `loadCurrentPlayerLeaderboardScore()` - 获取玩家排名
-- `loadPlayerCenteredScores()` - 加载周围玩家
-
-**⚠️ 关键提示：无需安装任何 SDK！**
-- `tap` 是全局对象（类似 `window`）
-- 不需要 `npm install`
-- 不需要 import
-
-### ⚙️ 服务端管理
-
-- **创建排行榜** - 服务端创建排行榜
-- **列出排行榜** - 查询现有排行榜
-- **自动 ID 管理** - 自动获取 developer_id、app_id、miniapp_id
-- **完整集成指南** - 分步骤工作流
-
-### 🎯 模块化架构
-
-- **17 个 Tools** - 完整的工具集（应用管理 + 排行榜 + H5 游戏）
-- **7 个 Resources** - 详细 API 文档
-- **模块化设计** - 易于添加新功能（云存档、分享等）
-- **完全兼容** - Claude Code ✅、VSCode ✅、Cursor ✅、OpenHands ✅
-
-### 🚀 v1.4.0 新特性 - Context Resolver & 多租户隔离
-
-- **ContextResolver 系统** - 集中式上下文解析（[详细文档](docs/MCP_PROXY_GUIDE.md)）
-  - 统一的 `contextResolver.resolve()` 替代分散的 `ensureAppInfo()` 调用
-  - 优先级机制：私有参数 > 上下文 > 缓存
-  - 纯内存/缓存查询，避免重复 API 调用
-  - 支持多租户隔离部署
-
-- **多租户隔离** - 通过 `_project_path` 实现租户隔离（[v1.4.1+ 架构优化](docs/ARCHITECTURE.md)）
-  - 每个租户独立的工作空间路径
-  - **缓存目录独立**：`/tmp/taptap-mcp/cache/{userId}/{projectId}/`
-  - **临时目录独立**：`/tmp/taptap-mcp/temp/{userId}/{projectId}/`
-  - **支持只读 workspace**：缓存和临时文件不写入用户代码目录
-  - MCP Proxy 注入租户上下文
-  - 支持 RuntimeContainer 架构
-
-- **扩展私有参数** - 新增应用上下文和追踪字段
-  - `_developer_id`, `_app_id`: 应用上下文注入
-  - `_project_path`: 租户隔离的关键
-  - `_tenant_id`, `_trace_id`, `_request_id`: 追踪支持
-
-- **架构优化**
-  - 消除模块间循环依赖
-  - 统一所有 `HandlerContext` 接口定义
-  - 更清晰的错误提示（不暴露私有参数给 AI）
-  - API 层使用统一的 ContextResolver
-
-### 🚀 v1.3.0 特性 - 私有参数协议
-
-- **私有参数协议** - 支持 MCP Proxy 模式多账号认证（[详细文档](docs/PRIVATE_PROTOCOL.md)）
-  - 对 AI Agent 完全透明（Tool Definition 不声明私有参数）
-  - 双模式注入：arguments 或 HTTP Header
-  - 四层认证优先级：自动选择最合适的 Token
-  - 业务层完全隔离：不感知私有参数
-  - [MCP Proxy 开发指引](docs/MCP_PROXY_GUIDE.md) - 完整的 Proxy 实现指南
-
-- **多客户端并发支持** - 无限客户端同时连接，独立会话管理
-- **智能自动授权（SSE 模式）** - 一步完成授权，无需手动调用 `complete_oauth_authorization`
-- **三种传输模式** - stdio（本地）、SSE（远程/实时）、HTTP JSON（兼容）
-- **客户端连接日志** - verbose 模式下完整记录连接事件
-- **实时进度推送** - SSE 模式下支持授权、上传、压缩等操作的实时进度
-
-## 快速开始
-
-### 本地安装
+### 安装
 
 ```bash
+# 全局安装
 npm install -g @mikoto_zero/minigame-open-mcp
-```
-
-或使用 npx 直接运行（无需安装）：
 
-```bash
+# 或使用 npx 直接运行（无需安装）
 npx @mikoto_zero/minigame-open-mcp
 ```
 
-### Docker 部署
+### 配置（MCP 客户端）
 
-**快速启动（docker-compose）**：
-```bash
-# 1. 配置环境变量
-cp .env.docker .env
-# 编辑 .env，填入 CLIENT_ID 和 CLIENT_TOKEN
-
-# 2. 启动服务
-docker-compose up -d
+#### Claude Code / VSCode / Cursor
 
-# 3. 验证服务
-curl http://localhost:5003/health
-```
-
-**自动化部署脚本**：
-```bash
-# 使用部署脚本（支持参数化配置）
-./scripts/deploy-docker.sh [version] [env] [port]
-
-# 示例
-./scripts/deploy-docker.sh latest production 3000
-```
-
-详见 [Docker 部署文档](docs/DOCKER_DEPLOYMENT.md)
-
-### 配置
-
-#### 在 Claude Code / VSCode / Cursor 中使用（零配置 OAuth）
-
-**推荐**：使用 OAuth Device Code Flow - 无需手动配置 token！
-
-在项目中创建 `.mcp.json`：
+在项目中创建 `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "taptap-minigame": {
       "command": "npx",
-      "args": ["-y", "@mikoto_zero/minigame-open-mcp"],
-      "env": {
-        "TDS_MCP_ENV": "production"
-      }
+      "args": ["-y", "@mikoto_zero/minigame-open-mcp"]
     }
   }
 }
 ```
 
-**首次使用流程（stdio 模式 - 默认）**：
-1. 服务器秒级启动
-2. 使用需要认证的功能时，会显示授权二维码链接
-3. 用 TapTap App 扫码授权
-4. 调用 `complete_oauth_authorization` 工具完成授权
-5. Token 自动保存，后续使用自动加载！
-
-**SSE 模式（OpenHands 等）**：
-- 步骤 2-4 自动完成，无需手动调用 `complete_oauth_authorization`
-- 实时显示授权进度（每 10 秒更新）
+**零配置 OAuth**：首次使用会提示扫码授权，token 自动保存！
 
-**手动配置 Token**（可选）：
+#### OpenHands（推荐 SSE 模式）
 
-如果你想手动配置：
-
-```json
-{
-  "mcpServers": {
-    "taptap-minigame": {
-      "command": "npx",
-      "args": ["@mikoto_zero/minigame-open-mcp"],
-      "env": {
-        "TDS_MCP_MAC_TOKEN": "{\"kid\":\"your_kid\",\"token_type\":\"mac\",\"mac_key\":\"your_key\",\"mac_algorithm\":\"hmac-sha-1\"}",
-        "TDS_MCP_ENV": "production",
-        "TDS_MCP_VERBOSE": "false"
-      }
-    }
-  }
-}
-```
-
-#### 在 OpenHands 中使用（推荐 SSE 模式）
-
-**方式 1：SSE 远程模式（推荐 - 支持自动授权和实时进度）**
+**远程部署**:
 
 ```bash
-# 1. 在服务器上启动 MCP 服务
-TDS_MCP_TRANSPORT=sse TDS_MCP_PORT=3000 TDS_MCP_VERBOSE=true \
+# 启动 SSE 服务器
+TDS_MCP_TRANSPORT=sse TDS_MCP_PORT=3000 \
 npx @mikoto_zero/minigame-open-mcp
-
-# 2. OpenHands 配置
-{
-  "mcpServers": {
-    "taptap-minigame": {
-      "url": "http://your-server:3000",
-      "transport": "sse"
-    }
-  }
-}
 ```
 
-**特性**：
-- ✅ 一步式自动授权（无需手动调用 `complete_oauth_authorization`）
-- ✅ 实时进度推送（授权、上传、压缩等）
-- ✅ 多客户端并发支持
-- ✅ 连接日志和监控
-
-**方式 2：stdio 本地模式（兼容模式）**
+**OpenHands 配置**:
 
 ```json
 {
   "mcpServers": {
     "taptap-minigame": {
-      "command": "npx",
-      "args": ["@mikoto_zero/minigame-open-mcp@beta"],
-      "env": {
-        "TDS_MCP_MAC_TOKEN": "${CURRENT_USER_MAC_TOKEN}",
-        "TDS_MCP_ENV": "production"
-      }
+      "url": "http://your-server:3000",
+      "transport": "sse"
     }
   }
 }
 ```
 
-### 传输模式
+✅ SSE 模式支持自动授权和实时进度推送！
 
-服务器支持三种传输模式：
-
-| 模式 | 配置 | 授权方式 | 进度反馈 | 适用场景 |
-|------|------|---------|---------|---------|
-| **stdio** | 默认 | 两步式 | ❌ | Claude Desktop、Cursor、本地单客户端 |
-| **sse** | `TDS_MCP_TRANSPORT=sse` | **一步式自动** | ✅ 实时 | **OpenHands**、Claude Code、远程/多客户端 |
-| **http** | `TDS_MCP_TRANSPORT=http` | 两步式 | ❌ | 普通 HTTP 客户端 |
-
-### 部署和运行
-
-#### npm scripts 方式（推荐）
-
-```bash
-# stdio 模式（默认，本地开发）
-npm start                  # 或 npm run dev
-
-# SSE 模式（远程部署，推荐用于 OpenHands）
-npm run serve:sse          # 基础模式（端口 3000）
-npm run serve:sse:dev      # 开发模式（详细日志）
-
-# HTTP JSON 模式（兼容普通 HTTP 客户端）
-npm run serve:http         # 端口 3000
-```
-
-#### 直接启动方式
-
-```bash
-# SSE 模式（推荐用于 OpenHands）
-TDS_MCP_TRANSPORT=sse TDS_MCP_PORT=3000 TDS_MCP_VERBOSE=true \
-npx @mikoto_zero/minigame-open-mcp
-
-# HTTP JSON 模式
-TDS_MCP_TRANSPORT=http TDS_MCP_PORT=3000 \
-npx @mikoto_zero/minigame-open-mcp
-
-# stdio 模式（默认）
-npx @mikoto_zero/minigame-open-mcp
-```
-
-#### 自定义端口和环境
-
-```bash
-# 通过环境变量覆盖端口
-TDS_MCP_PORT=8080 npm run serve:sse
-
-# 启用详细日志
-TDS_MCP_VERBOSE=true npm start
-
-# 切换环境
-TDS_MCP_ENV=rnd npm run serve:sse
-```
-
-#### 生产部署
-
-**使用 PM2 进程管理器**：
-
-```bash
-# 安装 PM2
-npm install -g pm2
-
-# 启动服务
-pm2 start npm --name "taptap-mcp" -- run serve:sse
-
-# 查看日志
-pm2 logs taptap-mcp
-
-# 重启/停止
-pm2 restart taptap-mcp
-pm2 stop taptap-mcp
-
-# 开机自启
-pm2 startup
-pm2 save
-```
-
-**使用 Docker 部署脚本**：
+### Docker 部署
 
 ```bash
-# 1. 配置环境变量
-export TDS_MCP_CLIENT_ID=your_client_id
-export TDS_MCP_CLIENT_TOKEN=your_client_token
-
-# 2. 执行部署脚本
-./scripts/deploy-docker.sh [version] [env] [port]
-
-# 示例
-./scripts/deploy-docker.sh latest production 3000
+# 快速启动
+docker-compose up -d
 
-# 3. 验证服务
-curl http://localhost:3000/health
+# 健康检查
+curl http://localhost:5003/health
 ```
 
-详见 [Docker 部署文档](docs/DOCKER_DEPLOYMENT.md)
-
-#### 健康检查
+详见: [Docker 部署文档](docs/DOCKER_DEPLOYMENT.md)
 
-```bash
-# 检查服务器状态
-curl http://localhost:3000/health
+## 📖 功能列表
 
-# 预期响应
-{
-  "status": "ok",
-  "version": "1.4.8",
-  "transport": "streamable-http",
-  "tools": 17,
-  "resources": 7,
-  "activeSessions": 0
-}
-```
+### 17 个 Tools
 
-### 环境变量
+#### 流程指引 (1)
+- `get_integration_guide` - 完整接入工作流指引
 
-**OAuth 认证（推荐 - 零配置）：**
-- ✅ 无需配置环境变量！
-- Token 自动保存到 `~/.config/taptap-minigame/token.json`
-- **SSE 模式**：自动授权，实时进度推送
-- **stdio/http 模式**：两步式授权
+#### 信息查询 (2)
+- `get_current_app_info` - 获取当前应用信息
+- `check_environment` - 检查环境配置
 
-**手动配置（可选）：**
-- `TDS_MCP_MAC_TOKEN` - MAC Token JSON 格式（可选，不设置则使用 OAuth）
-- `TDS_MCP_CLIENT_ID` - 客户端 ID（已内置默认值，可覆盖）
-- `TDS_MCP_CLIENT_TOKEN` - 签名密钥（已内置默认值，可覆盖）
+#### 认证 (1)
+- `complete_oauth_authorization` - 完成 OAuth 授权
 
-**其他配置：**
-- `TDS_MCP_ENV` - 环境选择：`production`（默认）或 `rnd`
-- `WORKSPACE_ROOT` - 工作空间根路径（默认：`process.cwd()`），用于路径解析
-- `TDS_MCP_VERBOSE` - 详细日志：`true` 或 `false`（默认）
+#### 应用管理 (2)
+- `list_developers_and_apps` - 列出所有应用
+- `select_app` - 选择当前应用
 
-**调试模式：**
+#### 排行榜管理 (4)
+- `create_leaderboard` - 创建排行榜
+- `list_leaderboards` - 列出排行榜
+- `publish_leaderboard` - 发布排行榜
+- `get_user_leaderboard_scores` - 获取用户分数
 
-启用详细日志查看所有工具调用、HTTP 请求/响应：
+#### H5 游戏管理 (7)
+- `list_h5_games` - 列出 H5 游戏
+- `create_h5_game` - 创建 H5 游戏
+- `update_h5_game` - 更新游戏信息
+- `upload_h5_game` - 上传游戏包
+- `publish_h5_game` - 发布游戏
+- `get_h5_game_status` - 查询发布状态
+- `get_h5_game_share_url` - 获取分享链接
 
-```bash
-export TDS_MCP_VERBOSE=true
-npm start
-```
+### 7 个 Resources
 
-详细日志包含：
-- 📥 工具调用的输入和输出
-- 📤 HTTP 请求头和请求体
-- 📥 HTTP 响应状态和数据
-- 🔒 敏感数据自动脱敏
+完整的排行榜 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` - 周围玩家
 
-## 使用示例
+## 🎯 使用示例
 
-### 场景 1: 接入排行榜功能
+### 接入排行榜
 
 ```
-用户: "我想在游戏中接入排行榜功能"
+用户: "我想在游戏中接入排行榜"
 
 AI 调用: get_integration_guide
+→ 返回完整工作流（创建排行榜 → 客户端代码 → 测试）
 
-返回: 完整的分步骤工作流
-✅ 强调无需安装 SDK
-✅ 步骤 1: 检查/创建服务端排行榜
-✅ 步骤 2: 客户端代码（使用全局 tap 对象）
-✅ 步骤 3: 测试检查清单
-✅ 列出所有 Resources 供详细阅读
-```
-
-### 场景 2: 获取 API 文档
-
-**在 Claude Code 中**（AI 自动读取）：
-```
-用户: "如何提交分数？"
+AI 调用: create_leaderboard
+→ 创建服务端排行榜
 
 AI 读取: docs://leaderboard/api/submit-scores
-
-返回: submitScores() 完整文档（参数、示例、错误码）
-```
-
-**在 VSCode 中**（调用工具）：
+→ 获取客户端代码示例
 ```
-用户: "如何提交分数？"
 
-AI 调用: get_integration_guide
+### OAuth 授权（首次）
 
-返回: 完整工作流（包含代码示例）
 ```
+AI 调用: create_leaderboard
+→ 🔐 需要授权，显示二维码链接
 
-### 场景 3: OAuth 授权流程
+用户: 扫码后告知 "已授权"
 
-```
-用户: "创建排行榜"
+AI 调用: complete_oauth_authorization
+→ ✅ 授权完成，token 已保存
 
 AI 调用: create_leaderboard
+→ ✅ 排行榜创建成功
+```
 
-返回: 🔐 需要授权
-      🔗 https://www.taptap.cn/tap-qrcode?...
+## 🛠️ 开发
 
-      步骤:
-      1. 点击链接在浏览器打开
-      2. 用 TapTap App 扫码
-      3. 调用 complete_oauth_authorization
-      4. 重新执行
+### 环境要求
 
-用户: "我已经授权了"
+- Node.js 16+
+- npm 或 pnpm
 
-AI 调用: complete_oauth_authorization
+### 本地开发
 
-返回: ✅ 授权完成！Token 已保存
+```bash
+# 安装依赖
+npm install
 
-用户: "创建排行榜"
+# 启动开发服务器
+npm run dev
 
-AI 调用: create_leaderboard
+# 构建
+npm run build
 
-返回: ✅ 排行榜创建成功！
-      🎮 客户端 ID: xxx
+# 运行测试
+npm test
 ```
 
-## 🏗️ 架构
+### 环境变量
 
-### 模块化设计
+**OAuth 认证（推荐）**:
+- 无需配置！自动保存 token 到 `~/.config/taptap-minigame/`
 
-v1.2.0-beta 引入了**完全模块化的架构**，每个功能都是自包含的：
+**手动配置（可选）**:
+- `TDS_MCP_MAC_TOKEN` - MAC Token（JSON 格式）
+- `TDS_MCP_CLIENT_ID` - 客户端 ID（已内置）
+- `TDS_MCP_CLIENT_TOKEN` - 签名密钥（已内置）
 
-```
-src/
-├── features/              # 功能模块（自包含）
-│   ├── app/              # 应用管理模块（基础功能）
-│   │   ├── index.ts      # 模块定义和注册
-│   │   ├── tools.ts      # 5 个工具（应用选择、环境检查等）
-│   │   ├── handlers.ts   # 业务逻辑
-│   │   └── api.ts        # API 调用
-│   │
-│   └── leaderboard/      # 排行榜模块
-│       ├── index.ts      # 模块定义和注册
-│       ├── tools.ts      # 5 个工具 + 处理器
-│       ├── resources.ts  # 7 个 Resources + 处理器
-│       ├── docs.ts       # 文档内容
-│       ├── docTools.ts   # 文档工具
-│       ├── handlers.ts   # 业务逻辑
-│       └── api.ts        # API 调用
-│
-├── core/                  # 共享核心功能
-│   ├── auth/             # OAuth Device Code Flow
-│   ├── network/          # HTTP 客户端
-│   ├── handlers/         # 通用处理器（environment）
-│   ├── utils/            # 缓存、日志、文档助手
-│   └── types/            # 类型定义
-│
-└── server.ts              # 主服务器（自动注册）
-```
+**其他**:
+- `TDS_MCP_ENV` - 环境：`production`（默认）或 `rnd`
+- `TDS_MCP_TRANSPORT` - 传输模式：`stdio`（默认）、`sse`、`http`
+- `TDS_MCP_PORT` - 端口（默认 3000）
+- `TDS_MCP_VERBOSE` - 详细日志：`true` 或 `false`
+- `TDS_MCP_CACHE_DIR` - 缓存目录（默认 `/tmp/taptap-mcp/cache`）
+- `TDS_MCP_TEMP_DIR` - 临时文件目录（默认 `/tmp/taptap-mcp/temp`）
 
-**模块说明**：
-- **app**: 基础应用管理（开发者/应用选择、OAuth 授权、环境检查）
-- **leaderboard**: 排行榜功能（依赖 app 模块）
-- 未来: cloudSave, share 等（都可以复用 app 模块）
+### 添加新功能
 
-**添加新功能**：
-```typescript
-// 1. 使用脚手架创建新模块
+```bash
+# 使用脚手架
 ./scripts/create-feature.sh
 
-// 2. 按照提示输入功能信息
-// Feature Key: cloud-save
-// Feature Name: 云存档
-// Resources: yes
-// Prompts: no
-
-// 3. 在 server.ts 导入
-import { cloudSaveModule } from './features/cloudSave/index.js';
-const allModules = [appModule, leaderboardModule, cloudSaveModule];
-
-// 完成！自动注册 ✅
+# 按提示输入功能信息
+# 自动生成模块结构到 src/features/yourFeature/
 ```
 
 ## 📚 文档
 
-- **README.md** - 本文件（用户指南）
-- **CLAUDE.md** - Claude Code 集成指南
-- **CONTRIBUTING.md** - 开发者贡献指南（添加新功能）
-- **CHANGELOG.md** - 版本变更历史
+- **[CLAUDE.md](CLAUDE.md)** - AI Agent 开发指引
+- **[CHANGELOG.md](CHANGELOG.md)** - 版本变更历史
+- **[docs/DOCKER_DEPLOYMENT.md](docs/DOCKER_DEPLOYMENT.md)** - Docker 部署指南
+- **[docs/MCP_PROXY_GUIDE.md](docs/MCP_PROXY_GUIDE.md)** - MCP Proxy 开发指南
+- **[docs/PRIVATE_PROTOCOL.md](docs/PRIVATE_PROTOCOL.md)** - 私有参数协议
 
-## 🤝 贡献
+## 🔄 CI/CD
+
+基于 Conventional Commits 的完全自动化发布：
 
-想要添加新功能（云存档、分享等）？
+```bash
+# 创建功能分支
+git checkout -b feat/awesome-feature
+
+# 提交代码
+git commit -m "feat: add awesome feature"
 
-查看 **CONTRIBUTING.md** 了解：
-- 分步骤指南
-- 代码结构
-- 设计原则
-- 快速脚手架：`./scripts/create-feature.sh`
+# 创建 PR 并合并
+gh pr create && gh pr merge
 
-## 📖 相关资源
+# 自动发布到 npm（版本：1.4.13 → 1.5.0）
+```
 
-- **官方 API 文档**: https://developer.taptap.cn/minigameapidoc/dev/api/open-api/leaderboard/
-- **MCP 规范**: https://modelcontextprotocol.io/
-- **npm 包**: [@mikoto_zero/minigame-open-mcp](https://www.npmjs.com/package/@mikoto_zero/minigame-open-mcp)
+**发布流程**：
+1. PR 合并 → 触发 Actions
+2. 分析 commits 确定版本号
+3. 发布到 npm
+4. 自动创建版本 PR 并合并
+5. 创建 GitHub Release
 
-## 📊 版本
+详见: [CLAUDE.md - CI/CD 章节](CLAUDE.md#cicd-和自动化发布)
 
-- **latest (v1.1.4)**: 纯 Tools 稳定版（17 tools）
-- **beta (v1.2.0-beta.12)**: 模块化架构（app + leaderboard）+ OAuth（10 tools + 7 resources）
+## 🤝 贡献
 
-推荐使用 **beta 版本**获得最佳体验！
+欢迎贡献！请遵循：
+1. Fork 仓库并创建 feature 分支
+2. 使用 Conventional Commits 规范
+3. 创建 PR，等待 CI 检查
+4. Review 通过后合并
 
 ## 📄 许可证
 
 MIT
 
-## 🔗 链接
+## 🔗 相关链接
 
 - [TapTap 开发者中心](https://developer.taptap.cn/)
-- [MCP 协议](https://modelcontextprotocol.io/)
-- [Issues](https://github.com/taptap/taptap-minigame-mcp-server/issues)
+- [官方 API 文档](https://developer.taptap.cn/minigameapidoc/dev/api/open-api/leaderboard/)
+- [MCP 协议规范](https://modelcontextprotocol.io/)
+- [Issues](https://github.com/taptap/taptap_minigame_open_mcp/issues)

package/dist/__tests__/version.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 基础测试 - 确保测试框架正常工作
+ */
+//# sourceMappingURL=version.test.d.ts.map

package/dist/__tests__/version.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/version.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/dist/__tests__/version.test.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * 基础测试 - 确保测试框架正常工作
+ */
+describe('Basic Tests', () => {
+    test('simple math should work', () => {
+        expect(1 + 1).toBe(2);
+    });
+    test('string concatenation should work', () => {
+        expect('hello' + ' ' + 'world').toBe('hello world');
+    });
+    test('array operations should work', () => {
+        const arr = [1, 2, 3];
+        expect(arr.length).toBe(3);
+        expect(arr[0]).toBe(1);
+    });
+});
+//# sourceMappingURL=version.test.js.map

package/dist/__tests__/version.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.test.js","sourceRoot":"","sources":["../../src/__tests__/version.test.ts"],"names":[],"mappings":";AAAA;;GAEG;AAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,IAAI,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,OAAO,GAAG,GAAG,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;QACxC,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACtB,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/mcp-proxy/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/mcp-proxy/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAY,MAAM,YAAY,CAAC;AA0BxD;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CAgDvD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/mcp-proxy/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA0B9C;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CAgDvD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikoto_zero/minigame-open-mcp",
-  "version": "1.4.13",
+  "version": "1.5.1",
   "type": "module",
   "description": "TapTap Open API MCP Server - Documentation and Management APIs for TapTap Minigame and H5 Games (Leaderboard, and more features coming)",
   "main": "dist/server.js",
@@ -51,14 +51,26 @@
     "dotenv": "17.2.3"
   },
   "devDependencies": {
+    "@commitlint/cli": "^18.4.3",
+    "@commitlint/config-conventional": "^18.4.3",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^9.2.6",
+    "@semantic-release/npm": "^11.0.2",
+    "@semantic-release/release-notes-generator": "^12.1.0",
     "@types/crypto-js": "^4.2.0",
     "@types/jest": "^29.0.0",
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
+    "conventional-changelog-cli": "5.0.0",
+    "conventional-changelog-conventionalcommits": "^7.0.2",
     "eslint": "^8.0.0",
     "jest": "^29.0.0",
     "prettier": "^3.0.0",
+    "semantic-release": "^22.0.12",
+    "ts-jest": "^29.1.0",
     "ts-node": "^10.9.0",
     "tsx": "4.20.6",
     "typescript": "^5.0.0"
@@ -70,10 +82,10 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/taptap/minigame-open-mcp.git"
+    "url": "git+https://github.com/taptap/taptap_minigame_open_mcp.git"
   },
-  "homepage": "https://github.com/taptap/minigame-open-mcp#readme",
+  "homepage": "https://github.com/taptap/taptap_minigame_open_mcp#readme",
   "bugs": {
-    "url": "https://github.com/taptap/minigame-open-mcp/issues"
+    "url": "https://github.com/taptap/taptap_minigame_open_mcp/issues"
   }
 }

package/dist/core/handlers/appHandlers.d.ts

@@ -1,9 +0,0 @@
-/**
- * Application Management Handlers (DEPRECATED - moved to features/app)
- * @deprecated Use handlers from features/app/handlers.ts instead
- *
- * This file is kept for backward compatibility only.
- * All app management logic has been moved to the app feature module.
- */
-export { listDevelopersAndApps, selectApp } from '../../features/app/handlers.js';
-//# sourceMappingURL=appHandlers.d.ts.map

package/dist/core/handlers/appHandlers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"appHandlers.d.ts","sourceRoot":"","sources":["../../../src/core/handlers/appHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/core/handlers/appHandlers.js

@@ -1,9 +0,0 @@
-/**
- * Application Management Handlers (DEPRECATED - moved to features/app)
- * @deprecated Use handlers from features/app/handlers.ts instead
- *
- * This file is kept for backward compatibility only.
- * All app management logic has been moved to the app feature module.
- */
-export { listDevelopersAndApps, selectApp } from '../../features/app/handlers.js';
-//# sourceMappingURL=appHandlers.js.map

package/dist/core/handlers/appHandlers.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"appHandlers.js","sourceRoot":"","sources":["../../../src/core/handlers/appHandlers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/features/h5Game/types.d.ts

@@ -1,113 +0,0 @@
-/**
- * Tap 开发者身份信息
- */
-export interface TapDeveloperInfo {
-    /** 游戏列表 */
-    levels: TapAppItem[];
-    /** 开发者 ID */
-    developer_id: number;
-    /** 开发者名称 */
-    developer_name: string;
-    /** 是否已认证 */
-    is_certified: boolean;
-}
-/**
- * H5 游戏信息
- */
-export interface TapAppItem {
-    /** 游戏 ID */
-    app_id: number;
-    /** 分类 */
-    category: string;
-    /** 游戏标题 */
-    app_title: string;
-    /** 是否已发布 */
-    is_published: boolean;
-}
-/**
- * 上传参数
- */
-export interface UploadParams {
-    /** 上传包 ID */
-    h5_package_id: number;
-    /** 上传 URL */
-    url: string;
-    /** 上传方法 */
-    method: string;
-    /** 上传头 */
-    headers: Record<string, string>;
-}
-/**
- * 创建开发者身份响应
- */
-export interface CreateDeveloperResponse {
-    /** 开发者名称 */
-    developer_name: string;
-    /** 开发者 ID */
-    developer_id: number;
-}
-/**
- * 创建游戏响应
- */
-export interface CreateAppResponse {
-    /** 应用 ID */
-    app_id: number;
-    /** 应用标题 */
-    app_title: string;
-    /** 显示应用标题 */
-    display_app_title: string;
-}
-/**
- * 编辑游戏响应
- */
-export interface EditAppResponse {
-    /** 游戏标题 */
-    app_title?: string;
-    /** 显示应用标题 */
-    display_app_title?: string;
-}
-/**
- * 游戏详情响应
- */
-export interface AppDetailAPIResponse {
-    /** 游戏详情 */
-    level?: {
-        /** 显示应用标题 */
-        display_app_title?: string;
-        /** 开发者 ID */
-        developer_id?: number;
-        /** 开发者名称 */
-        developer_name?: string;
-    };
-    /** 上传游戏详情 */
-    upload_level?: {
-        /** 游戏 ID */
-        app_id: number;
-        /** 表单数据 */
-        form_data: {
-            /** 游戏信息 */
-            info: {
-                /** 游戏标题 */
-                title: string;
-            };
-        };
-    };
-}
-/**
- * 游戏状态响应
- */
-export interface AppStatusResponse {
-    /** 审核状态：0-未发布，1-审核中，2-审核失败，3-已上线 */
-    review_status: number;
-}
-/**
- * App 详情
- */
-export interface AppDetail {
-    appId: number;
-    appTitle: string;
-    displayAppTitle: string;
-    developerId: number;
-    developerName: string;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/features/h5Game/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/features/h5Game/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW;IACX,MAAM,EAAE,UAAU,EAAE,CAAC;IAErB,aAAa;IACb,YAAY,EAAE,MAAM,CAAC;IAErB,YAAY;IACZ,cAAc,EAAE,MAAM,CAAC;IAEvB,YAAY;IACZ,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,YAAY;IACZ,MAAM,EAAE,MAAM,CAAC;IAEf,SAAS;IACT,QAAQ,EAAE,MAAM,CAAC;IAEjB,WAAW;IACX,SAAS,EAAE,MAAM,CAAC;IAElB,YAAY;IACZ,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa;IACb,aAAa,EAAE,MAAM,CAAC;IAEtB,aAAa;IACb,GAAG,EAAE,MAAM,CAAC;IAEZ,WAAW;IACX,MAAM,EAAE,MAAM,CAAC;IAEf,UAAU;IACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,YAAY;IACZ,cAAc,EAAE,MAAM,CAAC;IAEvB,aAAa;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,YAAY;IACZ,MAAM,EAAE,MAAM,CAAC;IAEf,WAAW;IACX,SAAS,EAAE,MAAM,CAAC;IAElB,aAAa;IACb,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,aAAa;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,WAAW;IACX,KAAK,CAAC,EAAE;QACN,aAAa;QACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAE3B,aAAa;QACb,YAAY,CAAC,EAAE,MAAM,CAAC;QAEtB,YAAY;QACZ,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IAEF,aAAa;IACb,YAAY,CAAC,EAAE;QACb,YAAY;QACZ,MAAM,EAAE,MAAM,CAAC;QAEf,WAAW;QACX,SAAS,EAAE;YACT,WAAW;YACX,IAAI,EAAE;gBACJ,WAAW;gBACX,KAAK,EAAE,MAAM,CAAC;aACf,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/features/h5Game/types.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.js.map

package/dist/features/h5Game/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/features/h5Game/types.ts"],"names":[],"mappings":""}

package/dist/mcp-proxy/tokenStore.d.ts

@@ -1,17 +0,0 @@
-import type { MacToken } from './types.js';
-/**
- * 基于文件的 Token 存储
- */
-export declare class FileTokenStore {
-    private tokenFile;
-    constructor(tokenFile: string);
-    /**
-     * 获取 MAC Token
-     */
-    get(): Promise<MacToken | null>;
-    /**
-     * 检查 Token 文件是否存在
-     */
-    has(): boolean;
-}
-//# sourceMappingURL=tokenStore.d.ts.map

package/dist/mcp-proxy/tokenStore.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tokenStore.d.ts","sourceRoot":"","sources":["../../src/mcp-proxy/tokenStore.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAS;gBAEd,SAAS,EAAE,MAAM;IAI7B;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA2BrC;;OAEG;IACH,GAAG,IAAI,OAAO;CAGf"}

package/dist/mcp-proxy/tokenStore.js

@@ -1,42 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-/**
- * 基于文件的 Token 存储
- */
-export class FileTokenStore {
-    constructor(tokenFile) {
-        this.tokenFile = tokenFile;
-    }
-    /**
-     * 获取 MAC Token
-     */
-    async get() {
-        try {
-            if (!this.has()) {
-                return null;
-            }
-            const content = await readFile(this.tokenFile, 'utf-8');
-            const token = JSON.parse(content);
-            // 验证 Token 格式
-            if (!token.kid ||
-                !token.mac_key ||
-                token.token_type !== 'mac' ||
-                token.mac_algorithm !== 'hmac-sha-1') {
-                console.error('[TokenStore] Invalid token format');
-                return null;
-            }
-            return token;
-        }
-        catch (error) {
-            console.error('[TokenStore] Failed to read token:', error);
-            return null;
-        }
-    }
-    /**
-     * 检查 Token 文件是否存在
-     */
-    has() {
-        return existsSync(this.tokenFile);
-    }
-}
-//# sourceMappingURL=tokenStore.js.map

package/dist/mcp-proxy/tokenStore.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tokenStore.js","sourceRoot":"","sources":["../../src/mcp-proxy/tokenStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGrC;;GAEG;AACH,MAAM,OAAO,cAAc;IAGzB,YAAY,SAAiB;QAC3B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,GAAG;QACP,IAAI,CAAC;YACH,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;gBAChB,OAAO,IAAI,CAAC;YACd,CAAC;YAED,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACxD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAa,CAAC;YAE9C,cAAc;YACd,IACE,CAAC,KAAK,CAAC,GAAG;gBACV,CAAC,KAAK,CAAC,OAAO;gBACd,KAAK,CAAC,UAAU,KAAK,KAAK;gBAC1B,KAAK,CAAC,aAAa,KAAK,YAAY,EACpC,CAAC;gBACD,OAAO,CAAC,KAAK,CAAC,mCAAmC,CAAC,CAAC;gBACnD,OAAO,IAAI,CAAC;YACd,CAAC;YAED,OAAO,KAAK,CAAC;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,oCAAoC,EAAE,KAAK,CAAC,CAAC;YAC3D,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,GAAG;QACD,OAAO,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACpC,CAAC;CACF"}