@champz-llc/legends-mcp-server 1.1.1 → 1.2.1

package/README.md

@@ -58,6 +58,12 @@ Once configured, you can ask Claude:
 - "How much CHAMPZ has been burned?"
 - "How much USDC has been distributed to players?"
 
+### Leaderboards
+- "Show me the current cycle leaderboard for Legends"
+- "Who's winning the weekly battle leaderboard?"
+- "What are the all-time leaderboards for Legends of Champz?"
+- "Show me the top 20 players in the current cycle"
+
 ### Reward Management
 - "Check my claimable rewards in Legends"
 - "Get my CHAMPZ claim data"
@@ -85,10 +91,50 @@ Get contract call data for claiming CHAMPZ tokens.
 ### `get_usdc_claim_data`
 Get contract call data for claiming USDC rewards.
 
+### `legends_leaderboard_current`
+Get current cycle battle leaderboard (top players in active 12-hour cycle).
+
+**Parameters**:
+- `limit` (optional): Number of players to show (1-100, default: 10)
+
+**Returns**:
+- Current cycle ID and letter
+- Cycle end time
+- Top players with wins/losses, win rate, streaks
+- Player tier badges and legend rarity
+
+### `legends_leaderboard_weekly`
+Get weekly battle leaderboard with USDC prize distribution.
+
+**Parameters**:
+- `limit` (optional): Number of players to show (1-100, default: 10)
+
+**Returns**:
+- Week number and cycle range
+- Total USDC prize pool ($100)
+- Top players with battle stats and USDC rewards
+- Cycles remaining in current week
+
+### `legends_leaderboard_alltime`
+Get all-time leaderboards across 10 categories.
+
+**Parameters**:
+- `limit` (optional): Players per category (1-50, default: 10)
+
+**Returns**:
+- Most CHAMPZ earned
+- Most USDC earned
+- Most total wins
+- Most guardian wins
+- Highest win rate (min 100 battles)
+- Longest win streak
+- Elemental Charge high scores and stats
+
 ## 📡 API Endpoints
 
 The server connects to:
 - **Global Stats**: `https://api.champz.world/game/spore-trainer/global-stats`
+- **Leaderboards**: `https://api.champz.world/game/spore-trainer/public-leaderboard`
 - **Rewards**: (Coming soon - player-specific endpoints)
 
 ## 🔧 Development

package/index.js

@@ -137,6 +137,69 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           properties: {},
           required: []
         },
+      },
+      {
+        name: 'legends_leaderboard_current',
+        description: 'Get current cycle leaderboard for Legends of Champz. Shows top players in the active 12-hour cycle across battles, guardian (throne), or Elemental Charge mini-game.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            category: {
+              type: 'string',
+              description: 'Leaderboard category: battles (default), guardian (throne holders), or ec (Elemental Charge)',
+              enum: ['battles', 'guardian', 'ec']
+            },
+            limit: {
+              type: 'number',
+              description: 'Number of top players to show (default: 10, max: 100)',
+              minimum: 1,
+              maximum: 100
+            }
+          },
+          required: []
+        },
+      },
+      {
+        name: 'legends_leaderboard_weekly',
+        description: 'Get weekly leaderboard for Legends of Champz. Shows top players for the current week (21 cycles) across battles (with USDC rewards) or guardian (throne competition).',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            category: {
+              type: 'string',
+              description: 'Leaderboard category: battles (default - with USDC rewards) or guardian (throne holders). Note: ec not available for weekly.',
+              enum: ['battles', 'guardian']
+            },
+            limit: {
+              type: 'number',
+              description: 'Number of top players to show (default: 10, max: 100)',
+              minimum: 1,
+              maximum: 100
+            }
+          },
+          required: []
+        },
+      },
+      {
+        name: 'legends_leaderboard_alltime',
+        description: 'Get all-time leaderboards for Legends of Champz. Can show all categories or filter by battles, guardian, or ec (Elemental Charge) stats.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            category: {
+              type: 'string',
+              description: 'Filter by category: all (default - shows everything), battles (wins/earnings/streaks), guardian (throne wins), or ec (Elemental Charge scores)',
+              enum: ['all', 'battles', 'guardian', 'ec']
+            },
+            limit: {
+              type: 'number',
+              description: 'Number of top players per category (default: 10, max: 50)',
+              minimum: 1,
+              maximum: 50
+            }
+          },
+          required: []
+        },
       }
     ],
   };
@@ -158,19 +221,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
         const stats = data.stats;
 
-        // CHAMPZ values are already in raw token units (with 8 decimals applied)
-        // Convert to human-readable with millions
-        const champzEarned = stats.champz_earned / 100000000;
-        const champzSpent = stats.champz_spent / 100000000;
-        const champzBurned = stats.champz_burned / 100000000;
-
-        // Format in millions for readability
-        const earnedMillions = (champzEarned / 1000000).toFixed(2);
-        const spentMillions = (champzSpent / 1000000).toFixed(2);
-        const burnedMillions = (champzBurned / 1000000).toFixed(2);
+        // CHAMPZ values are integers in token units (already divided by 10^8)
+        // Just divide by 1,000,000 to display as millions
+        const earnedMillions = (stats.champz_earned / 1000000).toFixed(2);
+        const spentMillions = (stats.champz_spent / 1000000).toFixed(2);
+        const burnedMillions = (stats.champz_burned / 1000000).toFixed(2);
 
         // Calculate percentage of 1 billion supply
-        const burnedPercent = ((champzBurned / 1000000000) * 100).toFixed(2);
+        const burnedPercent = ((stats.champz_burned / 1000000000) * 100).toFixed(2);
 
         const formattedStats = `Legends of Champz - Global Statistics
 
@@ -183,7 +241,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 ⚔️  Total Battles: ${stats.battles_total.toLocaleString()}
 🎯 Battles Today: ${stats.battles_today.toLocaleString()}
 
-Token Economics: CHAMPZ has 1 billion total supply. ${burnedMillions} million tokens (${burnedPercent}%) permanently removed from circulation through burns.
+Token Economics: CHAMPZ has 1 billion total supply. ${burnedMillions}M tokens (${burnedPercent}%) permanently removed from circulation through burns.
 
 Last updated: ${new Date(stats.cached_at * 1000).toLocaleString()}`;
 
@@ -256,6 +314,223 @@ Last updated: ${new Date(stats.cached_at * 1000).toLocaleString()}`;
         ],
       };
 
+    case 'legends_leaderboard_current':
+      try {
+        const category = request.params.arguments?.category || 'battles';
+        const limit = request.params.arguments?.limit || 10;
+        const response = await fetch(`https://api.champz.world/game/spore-trainer/public-leaderboard?type=current&category=${category}&limit=${limit}`);
+        const data = await response.json();
+
+        if (!data.success) {
+          throw new Error(data.error || 'Failed to fetch current cycle leaderboard');
+        }
+
+        let output = '';
+        const cycleInfo = `Cycle #${data.cycle_id} (${data.cycle_key}) - Ends: ${new Date(data.ends_at * 1000).toLocaleString()}\n`;
+
+        if (category === 'battles') {
+          output = `🏆 Legends of Champz - Current Cycle Battle Leaderboard\n\n`;
+          output += cycleInfo;
+          output += `Active Players: ${data.total_players.toLocaleString()}\n\n`;
+          output += `Top ${data.showing_top} Players:\n\n`;
+
+          data.leaderboard.forEach((player, index) => {
+            const tierEmoji = player.tier_emoji || '';
+            const name = player.display_name || `${player.wallet.slice(0, 6)}...${player.wallet.slice(-4)}`;
+            const winRate = player.win_rate.toFixed(1);
+            const record = `${player.wins}W-${player.losses}L`;
+
+            output += `${index + 1}. ${tierEmoji} ${name}\n`;
+            output += `   ${record} (${winRate}% win rate)`;
+            if (player.streak > 0) {
+              output += ` 🔥 ${player.streak} streak`;
+            }
+            output += `\n`;
+            if (player.rarity) {
+              output += `   ${player.rarity.charAt(0).toUpperCase() + player.rarity.slice(1)} • ${player.elements.join('/')}\n`;
+            }
+            output += `\n`;
+          });
+        } else if (category === 'guardian') {
+          output = `👑 Legends of Champz - Current Cycle Guardian (Throne) Leaderboard\n\n`;
+          output += cycleInfo;
+          output += `Current Guardian: ${data.current_guardian ? data.current_guardian.slice(0, 6) + '...' : 'None'}\n`;
+          output += `Prize Pool: ${data.prize_pool.toLocaleString()} CHAMPZ\n\n`;
+          output += `Top ${data.showing_top} Guardian Holders:\n\n`;
+
+          data.leaderboard.forEach((player) => {
+            const tierEmoji = player.tier_emoji || '';
+            const name = player.display_name || `${player.wallet.slice(0, 6)}...${player.wallet.slice(-4)}`;
+            const crown = player.is_current ? '👑 ' : '';
+
+            output += `${player.rank}. ${crown}${tierEmoji} ${name}\n`;
+            output += `   Held ${player.times_held}x • Sent ${player.total_sent.toLocaleString()} CHAMPZ\n\n`;
+          });
+        } else if (category === 'ec') {
+          output = `⚡ Legends of Champz - Current Cycle Elemental Charge Leaderboard\n\n`;
+          output += cycleInfo;
+          output += `Top ${data.showing_top} High Scores:\n\n`;
+
+          data.leaderboard.forEach((player) => {
+            const tierEmoji = player.tier_emoji || '';
+            const name = player.display_name || `${player.wallet.slice(0, 6)}...${player.wallet.slice(-4)}`;
+
+            output += `${player.rank}. ${tierEmoji} ${name}\n`;
+            output += `   Score: ${player.best_score} • Rounds: ${player.best_rounds} • Streak: ${player.best_streak}\n\n`;
+          });
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: output,
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error fetching current cycle leaderboard: ${error.message}`,
+            },
+          ],
+        };
+      }
+
+    case 'legends_leaderboard_weekly':
+      try {
+        const category = request.params.arguments?.category || 'battles';
+        const limit = request.params.arguments?.limit || 10;
+        const response = await fetch(`https://api.champz.world/game/spore-trainer/public-leaderboard?type=weekly&category=${category}&limit=${limit}`);
+        const data = await response.json();
+
+        if (!data.success) {
+          throw new Error(data.error || 'Failed to fetch weekly leaderboard');
+        }
+
+        let output = '';
+        const weekInfo = `Week ${data.week_number} (Cycles ${data.week_start_cycle}-${data.week_end_cycle})\nCurrent Cycle: ${data.current_cycle} | Cycles Remaining: ${data.cycles_remaining}\n`;
+
+        if (category === 'battles') {
+          output = `💰 Legends of Champz - Weekly Battle Leaderboard\n\n`;
+          output += weekInfo;
+          output += `Total Prize Pool: $${data.total_pool_usdc} USDC\n`;
+          output += `Active Players: ${data.total_players.toLocaleString()}\n\n`;
+          output += `Top ${data.showing_top} Players:\n\n`;
+
+          data.leaderboard.forEach((player, index) => {
+            const tierEmoji = player.tier_emoji || '';
+            const name = player.display_name || `${player.wallet.slice(0, 6)}...${player.wallet.slice(-4)}`;
+            const winRate = player.win_rate.toFixed(1);
+            const record = `${player.wins}W-${player.losses}L`;
+            const reward = player.usdc_reward > 0 ? ` 💵 $${player.usdc_reward.toFixed(2)}` : '';
+
+            output += `${index + 1}. ${tierEmoji} ${name}\n`;
+            output += `   ${record} in ${player.battles} battles (${winRate}% WR)${reward}\n\n`;
+          });
+        } else if (category === 'guardian') {
+          output = `👑 Legends of Champz - Weekly Guardian (Throne) Leaderboard\n\n`;
+          output += weekInfo;
+          output += `\nTop ${data.showing_top} Guardian Competitors:\n\n`;
+
+          data.leaderboard.forEach((player) => {
+            const tierEmoji = player.tier_emoji || '';
+            const name = player.display_name || `${player.wallet.slice(0, 6)}...${player.wallet.slice(-4)}`;
+
+            output += `${player.rank}. ${tierEmoji} ${name}\n`;
+            output += `   ${player.cycles_participated} cycles • ${player.total_sends} sends • ${player.total_sent.toLocaleString()} CHAMPZ\n\n`;
+          });
+        }
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: output,
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error fetching weekly leaderboard: ${error.message}`,
+            },
+          ],
+        };
+      }
+
+    case 'legends_leaderboard_alltime':
+      try {
+        const category = request.params.arguments?.category || 'all';
+        const limit = request.params.arguments?.limit || 10;
+        const response = await fetch(`https://api.champz.world/game/spore-trainer/public-leaderboard?type=alltime&category=${category}&limit=${limit}`);
+        const data = await response.json();
+
+        if (!data.success) {
+          throw new Error(data.error || 'Failed to fetch all-time leaderboards');
+        }
+
+        const boards = data.leaderboards;
+        let output = `🏅 Legends of Champz - All-Time Leaderboards`;
+        if (category !== 'all') {
+          output += ` (${category.toUpperCase()})`;
+        }
+        output += `\n\n`;
+
+        // Define categories to display based on what's available
+        const allCategories = [
+          { key: 'champz_earned', title: '💰 Most CHAMPZ Earned', format: (v) => `${(v / 1000000).toFixed(2)}M` },
+          { key: 'usdc_earned', title: '💵 Most USDC Earned', format: (v) => `$${v.toFixed(2)}` },
+          { key: 'champz_spent', title: '🔥 Most CHAMPZ Spent', format: (v) => `${(v / 1000000).toFixed(2)}M` },
+          { key: 'total_wins', title: '⚔️ Most Total Wins', format: (v) => v.toLocaleString() },
+          { key: 'win_rate', title: '🎯 Highest Win Rate (100+ battles)', format: (v) => `${v.toFixed(1)}%` },
+          { key: 'longest_streak', title: '🔥 Longest Win Streak', format: (v) => `${v} wins` },
+          { key: 'guardian_wins', title: '👑 Most Guardian (Throne) Wins', format: (v) => v },
+          { key: 'ec_best_score', title: '⚡ Best EC Score', format: (v) => v },
+          { key: 'ec_total_rounds', title: '⚡ Most EC Rounds Completed', format: (v) => v.toLocaleString() },
+          { key: 'ec_games_played', title: '⚡ Most EC Games Played', format: (v) => v },
+        ];
+
+        allCategories.forEach(cat => {
+          const board = boards[cat.key];
+          if (board && board.length > 0) {
+            output += `${cat.title}\n`;
+            board.slice(0, 3).forEach((player, i) => {
+              const name = player.display_name || `${player.wallet.slice(0, 6)}...`;
+              const value = cat.format(player.value);
+              output += `  ${i + 1}. ${name} - ${value}`;
+              if (player.battles) {
+                output += ` (${player.wins}/${player.battles})`;
+              }
+              output += `\n`;
+            });
+            output += `\n`;
+          }
+        });
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: output,
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error fetching all-time leaderboards: ${error.message}`,
+            },
+          ],
+        };
+      }
+
     default:
       throw new Error(`Unknown tool: ${name}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@champz-llc/legends-mcp-server",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "MCP server for Legends of Champz - Query game stats and claim rewards through Claude Desktop",
   "type": "module",
   "main": "index.js",