@mikoto_zero/minigame-open-mcp 1.0.0

package/README.md

@@ -0,0 +1,235 @@
+# TapTap Minigame Open API MCP Server
+
+> Model Context Protocol (MCP) server for TapTap minigame leaderboard documentation and management APIs.
+
+🚀 **Auto-fetch IDs** | 📚 **Complete Docs** | 🔧 **Server-side Management**
+
+## Features
+
+### 📖 LeaderboardManager API Documentation
+
+Complete documentation for all 5 LeaderboardManager APIs:
+- `tap.getLeaderboardManager()` - Initialize leaderboard system
+- `openLeaderboard()` - Display leaderboard UI
+- `submitScores()` - Submit player scores
+- `loadLeaderboardScores()` - Fetch leaderboard data
+- `loadCurrentPlayerLeaderboardScore()` - Get player's rank
+- `loadPlayerCenteredScores()` - Load nearby players
+
+Each API includes:
+- Method signature
+- Parameter descriptions
+- Return values
+- Complete code examples
+- Error handling
+
+### ⚙️ Server-side Management
+
+- **Create Leaderboards** - Create new leaderboards via TapTap API
+- **List Leaderboards** - Query existing leaderboards
+- **Auto ID Management** - Automatically fetch and cache developer_id and app_id
+- **Smart Workflow** - Intelligent guidance for leaderboard integration
+
+### 🎯 Intelligent Workflow
+
+The `start_leaderboard_integration` tool provides step-by-step guidance:
+1. Check existing leaderboards
+2. Create if needed
+3. Guide implementation with docs
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g minigame-open-mcp
+```
+
+Or use directly with npx (no installation needed):
+
+```bash
+npx minigame-open-mcp
+```
+
+### Configuration
+
+#### For Claude Desktop
+
+Add to `~/.config/claude-desktop/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "taptap-leaderboard": {
+      "command": "npx",
+      "args": ["minigame-open-mcp"],
+      "env": {
+        "TAPTAP_USER_TOKEN": "your_user_token",
+        "TAPTAP_CLIENT_ID": "your_client_id",
+        "TAPTAP_CLIENT_SECRET": "your_client_secret"
+      }
+    }
+  }
+}
+```
+
+#### For OpenHands
+
+```json
+{
+  "mcpServers": {
+    "taptap-leaderboard": {
+      "command": "npx",
+      "args": ["minigame-open-mcp"],
+      "env": {
+        "TAPTAP_USER_TOKEN": "${CURRENT_USER_TAPTAP_TOKEN}",
+        "TAPTAP_CLIENT_ID": "your_client_id",
+        "TAPTAP_CLIENT_SECRET": "your_client_secret",
+        "TAPTAP_PROJECT_PATH": "${CURRENT_PROJECT_PATH}"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+**Required:**
+- `TAPTAP_USER_TOKEN` - User authentication token
+- `TAPTAP_CLIENT_ID` - Client ID for API access
+- `TAPTAP_CLIENT_SECRET` - Client secret for request signing
+
+**Optional:**
+- `TAPTAP_ENV` - Environment: `production` (default) or `rnd`
+- `TAPTAP_PROJECT_PATH` - Project path for local caching
+
+## Usage
+
+### Scenario 1: Getting Started with Leaderboards
+
+```
+User: "I want to integrate leaderboards into my game"
+
+AI Agent calls: start_leaderboard_integration
+
+System response:
+✅ Checks existing leaderboards
+✅ Guides creation if needed
+✅ Shows available leaderboard features
+✅ Provides next steps
+```
+
+### Scenario 2: Get Implementation Code
+
+```
+User: "How do I submit scores to the leaderboard?"
+
+AI Agent calls: submit_scores
+
+System returns:
+✅ Method signature: leaderboardManager.submitScores(scores, callback)
+✅ Parameter documentation
+✅ Complete code example
+✅ Error handling guide
+```
+
+### Scenario 3: Create a Leaderboard
+
+```
+User: "Create a weekly high score leaderboard"
+
+AI Agent calls: create_leaderboard
+{
+  title: "Weekly High Score",
+  period_type: 1,
+  score_type: 0,
+  score_order: 1,
+  calc_type: 0
+}
+
+System:
+✅ Auto-fetches developer_id and app_id
+✅ Creates leaderboard
+✅ Returns leaderboard_id
+✅ Caches for future use
+```
+
+## Available Tools (14 total)
+
+### Core API Documentation Tools (6)
+- `get_leaderboard_manager`
+- `open_leaderboard`
+- `submit_scores`
+- `load_leaderboard_scores`
+- `load_current_player_score`
+- `load_player_centered_scores`
+
+### Management Tools (2)
+- `create_leaderboard` - Create new leaderboards
+- `list_leaderboards` - Query existing leaderboards
+
+### Helper Tools (3)
+- `search_leaderboard_docs` - Search documentation
+- `get_leaderboard_overview` - System overview
+- `get_leaderboard_patterns` - Best practices
+
+### System Tools (2)
+- `check_environment` - Environment check
+- `start_leaderboard_integration` - Workflow guidance
+
+### User Data Tool (1)
+- `get_user_leaderboard_scores` - Query user scores (requires token)
+
+## Technical Details
+
+### Request Signing
+
+All server-side API requests use HMAC-SHA256 signing:
+
+```
+Signature = HMAC-SHA256(
+  method + "\n" +
+  url + "\n" +
+  x-tap-headers + "\n" +
+  body + "\n",
+  TAPTAP_CLIENT_SECRET
+)
+```
+
+### Auto ID Management
+
+Developer ID and App ID are automatically managed:
+
+1. First call to management tools triggers `/level/v1/list` API
+2. Selects first developer and first app
+3. Caches to `~/.config/taptap-minigame/app.json`
+4. Subsequent calls use cached values
+5. No manual ID input needed
+
+### Multi-Environment Support
+
+- **Production** (default): `https://agent.tapapis.cn`
+- **RND**: `https://agent.api.xdrnd.cn`
+
+Switch via `TAPTAP_ENV` environment variable.
+
+## Requirements
+
+- Node.js >= 16.0.0
+- Valid TapTap user token
+- Client ID and secret for API access
+
+## API Reference
+
+Based on TapTap official documentation:
+- https://developer.taptap.cn/minigameapidoc/dev/api/open-api/leaderboard/
+
+## License
+
+MIT
+
+## Links
+
+- [TapTap Developer Portal](https://developer.taptap.cn/)
+- [MCP Protocol](https://modelcontextprotocol.io/)
+- [Issues](https://github.com/taptap/taptap-minigame-mcp-server/issues)

package/bin/minigame-open-mcp

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+/**
+ * TapTap Minigame Open API MCP Server
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Get package root directory
+const packageRoot = path.join(__dirname, '..');
+
+// Check if compiled version exists
+const distPath = path.join(packageRoot, 'dist', 'server.js');
+const srcPath = path.join(packageRoot, 'src', 'server.ts');
+
+if (fs.existsSync(distPath)) {
+    // Use compiled version
+    require(distPath);
+} else if (fs.existsSync(srcPath)) {
+    // Development mode, use ts-node
+    try {
+        require('ts-node/register');
+        require(srcPath);
+    } catch (error) {
+        console.error('❌ Please install dependencies or build the project:');
+        console.error('   npm install');
+        console.error('   npm run build');
+        process.exit(1);
+    }
+} else {
+    console.error('❌ Server file not found');
+    process.exit(1);
+}

package/dist/data/leaderboardDocs.d.ts

@@ -0,0 +1,37 @@
+/**
+ * TapTap Minigame Leaderboard API Documentation
+ * Based on: https://developer.taptap.cn/minigameapidoc/dev/api/open-api/leaderboard/
+ */
+export interface LeaderboardAPI {
+    name: string;
+    method: string;
+    description: string;
+    parameters?: Record<string, string>;
+    returnValue?: string;
+    example: string;
+}
+export interface LeaderboardCategory {
+    title: string;
+    description: string;
+    apis: LeaderboardAPI[];
+}
+export interface LeaderboardDocumentation {
+    title: string;
+    description: string;
+    apiReference: string;
+    categories: Record<string, LeaderboardCategory>;
+}
+export declare const LEADERBOARD_DOCUMENTATION: LeaderboardDocumentation;
+/**
+ * Search leaderboard documentation by keyword
+ */
+export declare function searchLeaderboardDocs(query: string, category?: string): string[];
+/**
+ * Get overview of leaderboard system
+ */
+export declare function getLeaderboardOverview(): string;
+/**
+ * Get detailed documentation for a specific category
+ */
+export declare function getCategoryDocs(category: string): string;
+//# sourceMappingURL=leaderboardDocs.d.ts.map

package/dist/data/leaderboardDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leaderboardDocs.d.ts","sourceRoot":"","sources":["../../src/data/leaderboardDocs.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,cAAc,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACjD;AAED,eAAO,MAAM,yBAAyB,EAAE,wBA0cvC,CAAC;AAEF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAqChF;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAoC/C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoCxD"}