npm package: @gavin_zhou/tap-web-game-uploader
Description: MCP server for Tap Web Game Uploader
Author: Gavin Zhou
Latest version: 0.0.36

# TDS MCP Server

## 简介

TDS MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器，专门用于将 H5 游戏发布和上传到 TapTap 平台。该服务器提供了完整的游戏发布流程，包括游戏信息收集、文件上传、状态查询等功能。

## 功能特性

- 🎮 **H5 游戏上传**: 支持将 H5 游戏项目压缩并上传到 TapTap 平台
- 📋 **游戏信息收集**: 自动收集和验证游戏项目信息
- 🎯 **状态查询**: 实时查询游戏审核状态
- 🏗️ **游戏创建**: 在 TapTap 平台创建新游戏项目
- 👥 **开发者管理**: 支持创建和管理开发者身份
- 📝 **游戏信息编辑**: 支持编辑游戏的详细信息（描述、横竖屏、沟通群等）
- 📊 **批量查询**: 支持查询所有游戏列表

## 安装

### 从 npm 安装（推荐）

```bash
npm install -g @gavin_zhou/tap-web-game-uploader
```

### 从源码安装

1. 克隆项目：

```bash
git clone git@github.com:taptap/tapcode-mcp-h5.git
cd tapcode-mcp-h5
```

2. 安装依赖并构建：

```bash
bun install
deno task build
```

## MCP 配置

### 使用 npm 全局安装

如果通过 npm 全局安装，配置如下：

```json
{
  "mcpServers": {
    "tds-mcp-server": {
      "command": "npx",
      "args": ["-y", "@gavin_zhou/tap-web-game-uploader"]
    }
  }
}
```

### 使用本地路径

如果您是从本地项目运行，请使用绝对路径：

```json
{
  "mcpServers": {
    "tds-mcp-server": {
      "command": "npx",
      "args": ["/完整的绝对路径/tds-mcp-server/"]
    }
  }
}
```

### 配置验证

配置完成后，应该能看到以下工具：

- `tap_web_game_info_gatherer` - 游戏信息收集
- `tap_web_game_uploader` - 游戏上传
- `tap_get_app_status` - 查询游戏状态
- `tap_create_app` - 创建游戏
- `tap_create_developer` - 创建开发者身份
- `tap_edit_app` - 编辑游戏信息
- `tap_get_all_app` - 获取所有游戏列表
- `tap_logout` - 退出登录

## 使用方法

### 1. 游戏发布流程

使用 IDE 打开游戏项目目录，然后直接对话即可：

```
帮我将这个 H5 游戏发布到 TapTap
```

或者

```
我想上传游戏到 TapTap 平台
```

### 2. 查询游戏状态

```
查询游戏 ID 12345 的审核状态
```

### 3. 创建新游戏

```
在 TapTap 上创建一个名为"我的新游戏"的项目
```

### 4. 退出登录

```
退出 TapTap 登录
```

## 游戏项目要求

上传的游戏项目必须满足：

- 📁 **目录结构**: 包含 `index.html` 文件作为游戏入口
- 🌐 **H5 兼容**: 基于 HTML5 技术开发
- 📦 **完整性**: 包含所有必要的资源文件（图片、音频、脚本等）
- 📏 **大小限制**: 遵循 TapTap 平台的文件大小限制

### 示例项目结构

```
my-game/
├── index.html          # 必需：游戏入口文件
├── css/
│   └── style.css
├── js/
│   ├── game.js
│   └── lib/
├── assets/
│   ├── images/
│   └── sounds/
└── README.md
```

## 开发

### 使用 Dev Container（推荐）

项目包含完整的 Dev Container 配置，提供一致的开发环境：

1. **快速开始**（VS Code）
   ```bash
   # 打开项目
   code .
   # 按 F1 → 输入 "Reopen in Container"
   ```

2. **功能特性**
   - 预装所有开发工具（Node.js 20、Deno、Bun）
   - 集成 Claude Code、GitHub CLI 等工具
   - Git Worktree 完整支持
   - 自动安装项目依赖

详细配置说明请参考 [.devcontainer/README.md](.devcontainer/README.md)

### 手动配置环境

如果不使用 Dev Container，需要手动安装以下环境：

- **Node.js**: 版本 20.x
- **Deno**: 版本 2.x
- **Bun**: 版本 1.2.x
- **Git**: 版本 ≥ 2.44（支持相对路径 worktree）

#### Git Worktree 配置要求

本项目使用 Git worktree 进行多分支开发，**必须**满足以下要求：

1. **Git 版本必须 ≥ 2.44**

   ```bash
   # 检查 Git 版本
   git --version
   ```

2. **启用相对路径配置**

   ```bash
   # 全局启用 worktree 相对路径
   git config --global worktree.useRelativePaths true
   ```

3. **目录结构要求**

   - 所有 worktree 目录必须与 bare 仓库目录（默认 `.bare`）平行
   - 正确的目录结构：
     ```
     /path/to/project/
     ├── .bare/              # Git bare 仓库
     ├── main/               # main 分支 worktree
     ├── feature-x/          # 功能分支 worktree
     └── bugfix-y/           # 修复分支 worktree
     ```

4. **创建 worktree 示例**

   ```bash
   cd /path/to/project
   # 初始化 bare 仓库（仅首次）
   git clone --bare <repository-url> .bare

   # 创建 worktree
   git -C .bare worktree add ../main main
   git -C .bare worktree add -b feature-new ../feature-new
   ```

#### 安装 Deno 和 Bun

Linux / macOS

```bash
curl -fsSL https://deno.land/install.sh | sh
curl -fsSL https://bun.sh/install | bash
```

Windows

```powershell
irm https://deno.land/install.ps1 | iex
irm bun.sh/install.ps1 | iex
```

### 使用 Dev Container（推荐）

本项目提供了完整的 Dev Container 配置，支持在隔离的容器环境中进行开发。

详细的 Dev Container 使用说明请参考：[.devcontainer/README.md](.devcontainer/README.md)

#### 快速开始

1. 安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/) 和 [VS Code](https://code.visualstudio.com/)
2. 安装 [Dev Containers 扩展](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
3. 打开项目并选择 "Reopen in Container"

或使用 GitHub Codespaces：

- 点击仓库的 "Code" → "Codespaces" → "Create codespace"

### 项目结构

```
tds-mcp-server/
├── src/
│   ├── index.ts       # 主服务器入口
│   ├── network.ts     # 网络请求和认证模块
│   ├── tools.ts       # 工具函数和常量
│   ├── models.ts      # TypeScript 类型定义
│   └── mcp-tools.ts   # MCP 工具定义
├── dist/              # 构建输出目录
├── package.json       # npm 配置
├── deno.jsonc         # Deno 配置（开发工具）
├── tsconfig.json      # TypeScript 配置
└── .github/           # GitHub Actions 工作流
    └── workflows/
        ├── test.yml   # 测试工作流
        ├── publish.yml # 发布工作流
        └── release.yml # Release 创建工作流
```

### 开发命令

```bash
# 构建项目
deno task build

# 监听文件变化
deno task watch

# 代码检查（格式化、lint、类型检查）
deno task chk

# 自动修复代码问题
deno task fix

# 单独运行各种检查
deno fmt --check    # 检查格式
deno lint          # 代码检查
deno check src/**/*.ts  # 类型检查
```

### 技术选型

本项目采用混合开发模式：

- **开发工具**: Deno - 提供原生 TypeScript 支持、内置格式化和 lint 工具
- **构建工具**: Bun - 快速的 JavaScript 打包器
- **运行环境**: Node.js - 确保最广泛的兼容性
- **发布平台**: npm - 方便用户安装和使用

### 项目配置文件说明

- **package.json** - npm 包配置，只包含发布相关的必要信息
- **deno.jsonc** - 开发环境配置，包含所有开发任务和工具配置
- **tsconfig.json** - TypeScript 配置，用于类型检查
- **.github/workflows/** - CI/CD 自动化流程

## 常见问题

### Q: 配置后在 IDE 中看不到工具？

A: 请检查：

1. 配置文件路径是否正确
2. JSON 格式是否有误

### Q: 上传失败怎么办？

A: 请确认：

1. 游戏目录包含 `index.html` 文件
2. 网络连接正常
3. TapTap 开发者账号已认证
4. 游戏文件大小在限制范围内

### Q: 路径配置问题？

A: 使用绝对路径，避免以下常见错误：

- ❌ `~/tds-mcp-server/` (波浪号)
- ❌ `./tds-mcp-server/` (相对路径)
- ✅ `/Users/username/tds-mcp-server/` (绝对路径)

## 贡献指南

### 提交代码前

1. 确保代码通过所有检查：

   ```bash
   deno task chk
   ```

2. 构建并测试：
   ```bash
   deno task build
   ```

### 提交规范

- 使用清晰的提交信息
- 遵循项目的代码风格
- 添加必要的测试和文档

## 技术栈

- **TypeScript**: 主要开发语言
- **MCP SDK**: Model Context Protocol 支持
- **Node.js**: 运行环境
- **Archiver**: 文件压缩
- **Crypto-js**: 加密和签名
- **Deno**: 开发工具链
- **Bun**: 构建工具

## 许可证

MIT License

## 相关链接

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [TapTap 开发者平台](https://developer.taptap.cn/)
- [GitHub Issues](https://github.com/taptap/tds-mcp-server/issues)