@champz-llc/legends-mcp-server 1.1.0

package/PUBLISHING.md

@@ -0,0 +1,257 @@
+# Publishing to npm - Step by Step Guide
+
+## Prerequisites
+
+1. **npm account**: Create one at https://www.npmjs.com/signup
+2. **Email verified**: npm will send verification email
+3. **Node.js installed**: Version 18+ required
+
+---
+
+## Step 1: Create npm Account (If you don't have one)
+
+1. Go to https://www.npmjs.com/signup
+2. Fill in:
+   - Username: `champz` (or your preferred username)
+   - Email: Your email
+   - Password: Strong password
+3. Verify your email
+
+---
+
+## Step 2: Login to npm via CLI
+
+Open terminal in the `legends-mcp-server` directory:
+
+```bash
+npm login
+```
+
+Enter:
+- Username: Your npm username
+- Password: Your npm password
+- Email: Your npm email
+
+You should see: `Logged in as <username> on https://registry.npmjs.org/`
+
+---
+
+## Step 3: Test Package Locally
+
+Before publishing, test that everything works:
+
+```bash
+# Install dependencies
+npm install
+
+# Test the server
+node index.js
+```
+
+The server should start without errors.
+
+---
+
+## Step 4: Check Package Name Availability
+
+Our package name is: `@champz/legends-mcp-server`
+
+Check if it's available:
+```bash
+npm view @champz/legends-mcp-server
+```
+
+If you get "404 Not Found" → Name is available ✅
+If you get package info → Name is taken ❌ (choose different name)
+
+**Note**: Scoped packages (starting with `@`) require npm organization or paid account, OR you can publish as public:
+
+### Option A: Use scoped package (requires npm org)
+- Package name: `@champz/legends-mcp-server`
+- You'll need to create "champz" organization on npm
+- Create org at: https://www.npmjs.com/org/create
+
+### Option B: Use unscoped package (free, easier)
+- Package name: `legends-mcp-server` (without @champz/)
+- Change in package.json: `"name": "legends-mcp-server"`
+
+**Recommendation**: Start with Option B (unscoped) for simplicity, migrate to scoped later if needed.
+
+---
+
+## Step 5: Publish Package
+
+### For Scoped Package (@champz/legends-mcp-server):
+
+```bash
+npm publish --access public
+```
+
+The `--access public` flag is required for scoped packages.
+
+### For Unscoped Package (legends-mcp-server):
+
+```bash
+npm publish
+```
+
+---
+
+## Step 6: Verify Publication
+
+1. Check npm website:
+   - Scoped: https://www.npmjs.com/package/@champz/legends-mcp-server
+   - Unscoped: https://www.npmjs.com/package/legends-mcp-server
+
+2. Test installation:
+```bash
+# In a different directory
+npm install -g @champz/legends-mcp-server
+# or
+npm install -g legends-mcp-server
+```
+
+3. Test execution:
+```bash
+npx @champz/legends-mcp-server
+# or
+npx legends-mcp-server
+```
+
+---
+
+## Step 7: Update Version (For Future Updates)
+
+When you make changes and want to publish an update:
+
+```bash
+# Increment version (patch: 1.1.0 → 1.1.1)
+npm version patch
+
+# Or minor version (1.1.0 → 1.2.0)
+npm version minor
+
+# Or major version (1.1.0 → 2.0.0)
+npm version major
+
+# Then publish again
+npm publish --access public
+```
+
+---
+
+## Users Installing Your Package
+
+Once published, other users can install with:
+
+### Global Installation:
+```bash
+npm install -g @champz/legends-mcp-server
+```
+
+### Use with npx (no installation):
+```bash
+npx @champz/legends-mcp-server
+```
+
+### Claude Desktop Configuration:
+
+Users add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "legends-champz": {
+      "command": "npx",
+      "args": ["@champz/legends-mcp-server"]
+    }
+  }
+}
+```
+
+**Config File Locations**:
+
+**Windows (Standard)**: `%APPDATA%\Claude\claude_desktop_config.json`
+- Full path: `C:\Users\[username]\AppData\Roaming\Claude\claude_desktop_config.json`
+
+**Windows (Microsoft Store)**: `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
+- Full path: `C:\Users\[username]\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**How to check which version**: If your Claude was installed from Microsoft Store, use the second Windows path.
+
+---
+
+## Common Issues
+
+### Issue 1: "You do not have permission to publish"
+**Solution**: Make sure you're logged in with `npm login`
+
+### Issue 2: "Package name too similar to existing package"
+**Solution**: Choose a more unique name
+
+### Issue 3: "You must verify your email"
+**Solution**: Check your email and verify npm account
+
+### Issue 4: "Payment required for scoped packages"
+**Solution**: Either:
+- Create an npm organization (free for public packages)
+- Use unscoped package name instead
+- Publish with `--access public` flag
+
+---
+
+## Package Maintenance
+
+### Update README on npm:
+Just publish a new version - npm automatically updates README from your package.
+
+### Deprecate a version:
+```bash
+npm deprecate @champz/legends-mcp-server@1.1.0 "Use version 1.2.0 instead"
+```
+
+### Unpublish (within 72 hours):
+```bash
+npm unpublish @champz/legends-mcp-server@1.1.0
+```
+
+**Warning**: Unpublishing is permanent and discouraged. Use deprecate instead.
+
+---
+
+## Promotion
+
+Once published, promote your package:
+
+1. **Tweet about it**: Tag @buildonbase, @jessepollak, @AnthropicAI
+2. **Post on Farcaster**: Share in /base channel
+3. **Add to Base MCP directory**: Submit to https://mcp.base.org
+4. **Update game website**: Add "Use with Claude Desktop" section
+
+---
+
+## Quick Checklist
+
+Before publishing:
+- [ ] package.json has correct name, version, description
+- [ ] README.md is complete and helpful
+- [ ] .npmignore excludes dev files
+- [ ] Code tested and working
+- [ ] npm account created and verified
+- [ ] Logged in via `npm login`
+- [ ] Version incremented (if updating)
+
+Ready to publish!
+
+```bash
+npm publish --access public
+```
+
+---
+
+**Status**: Ready to publish
+**Package**: @champz/legends-mcp-server
+**Version**: 1.1.0
+**License**: MIT

package/README.md

@@ -0,0 +1,127 @@
+# 🍄 Legends of Champz MCP Server
+
+**Query game stats and manage rewards through Claude Desktop using Model Context Protocol**
+
+Built for [Legends of Champz](https://legends.champz.world) - a blockchain-based battle game on Base L2.
+
+## ✨ Features
+
+- 📊 **Global Game Statistics** - Real-time stats (legends rolled, CHAMPZ burned, battles, rewards)
+- 💰 **Reward Checking** - Check claimable CHAMPZ and USDC rewards
+- ⚡ **Base L2 Integration** - Execute on-chain claims via smart contracts
+- 🤖 **Conversational Interface** - Natural language queries through Claude Desktop
+
+## 🚀 Installation
+
+### Option 1: Global Install (Recommended)
+
+```bash
+npm install -g @champz-llc/legends-mcp-server
+```
+
+### Option 2: Use with npx (No installation)
+
+```bash
+npx @champz-llc/legends-mcp-server
+```
+
+## ⚙️ Configuration
+
+Add to your Claude Desktop config file:
+
+**Windows (Standard Install)**: `%APPDATA%\Claude\claude_desktop_config.json`
+**Windows (Microsoft Store)**: `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+**Tip**: If you're unsure which version you have, check both locations. The Microsoft Store version has `Packages\Claude_` in the path.
+
+```json
+{
+  "mcpServers": {
+    "legends-champz": {
+      "command": "npx",
+      "args": ["@champz-llc/legends-mcp-server"]
+    }
+  }
+}
+```
+
+**Restart Claude Desktop** after saving.
+
+## 📖 Usage Examples
+
+Once configured, you can ask Claude:
+
+### Global Statistics
+- "What are the global stats for Legends of Champz?"
+- "How many legends have been rolled?"
+- "How much CHAMPZ has been burned?"
+- "How much USDC has been distributed to players?"
+
+### Reward Management
+- "Check my claimable rewards in Legends"
+- "Get my CHAMPZ claim data"
+- "Show me my USDC rewards"
+
+## 🛠️ Available Tools
+
+### `legends_global_stats`
+Get real-time global game statistics.
+
+**Returns**:
+- Legends rolled
+- Thrones claimed
+- CHAMPZ earned/spent/burned
+- USDC distributed
+- Total battles
+- Battles today
+
+### `check_legends_rewards`
+Check claimable rewards (demo data).
+
+### `get_champz_claim_data`
+Get contract call data for claiming CHAMPZ tokens.
+
+### `get_usdc_claim_data`
+Get contract call data for claiming USDC rewards.
+
+## 📡 API Endpoints
+
+The server connects to:
+- **Global Stats**: `https://api.champz.world/game/spore-trainer/global-stats`
+- **Rewards**: (Coming soon - player-specific endpoints)
+
+## 🔧 Development
+
+```bash
+# Clone repository
+git clone https://github.com/champz/legends-mcp-server.git
+cd legends-mcp-server
+
+# Install dependencies
+npm install
+
+# Run locally
+npm start
+```
+
+## 🎮 About Legends of Champz
+
+Legends of Champz is a blockchain-based battle game on Base L2 featuring:
+- 20,000 unique mushroom warrior NFTs
+- Ghost PvP battles with point-based resolution
+- Guardian king-of-the-hill mechanics
+- CHAMPZ token + USDC rewards
+- Cycle-based gameplay (12-hour cycles)
+
+**Play now**: https://legends.champz.world
+
+## 🔗 Links
+
+- **Game**: https://legends.champz.world
+- **Base MCP**: https://mcp.base.org
+- **Contest**: BuildOnBase X (Twitter)
+
+## 📄 License
+
+MIT - Created for Base MCP demo contest

package/index.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import fetch from 'node-fetch';
+
+// Hardcoded rewards data for demo
+const DEMO_WALLET = '0xfbc159e35f56580d5d297af18a8c19f83d66088a';
+
+const REWARDS_DATA = {
+  wallet: DEMO_WALLET,
+  champz_claims: [
+    {
+      token_name: 'CHAMPZ',
+      amount_human: '8,423 CHAMPZ',
+      contract: '0x50b868CdeAEBe6e4a3bF0cb24Df1B4d24Fff01CB',
+      function_name: 'claim',
+      parameters: {
+        recipient: DEMO_WALLET,
+        amount: '842300000000', // 8423 * 10^8 (8 decimals)
+        claimType: '18',
+        nonce: '16320',
+        signature: '0x957f074e39a7a3819dac5d6b4a851aa4e5d5898a0ec6bbda0b070654d25d0e080cbecc2cb188f28d824dee604e04f5a81466c70d247fa4fe90d9bf812db220281b'
+      },
+      abi_function: 'function claim(address recipient, uint256 amount, uint8 claimType, uint256 nonce, bytes signature)'
+    }
+  ],
+  usdc_claims: [
+    {
+      token_name: 'USDC',
+      amount_human: '11 USDC',
+      contract: '0x7058895cC9150a283743C1bB35E17817A9A299e7',
+      function_name: 'claimReward',
+      claim_type: 8,
+      parameters: {
+        recipient: DEMO_WALLET,
+        amount: '11000000', // 11 * 10^6 (6 decimals)
+        cycle: '41',
+        nonce: '16319',
+        signature: '0x1cca70ee94eeec714ecdebffbd0707b514098423b36c5281bacf5e4dc1fba5ba5d7d80970b1537da851abd963c77486e171b63c8e0b3fcafa53c0433b747b9dc1c'
+      },
+      abi_function: 'function claimReward(address recipient, uint256 amount, uint256 cycle, uint256 nonce, bytes signature)'
+    }
+  ],
+  summary: {
+    total_champz: 8423,
+    total_usdc: 11,
+    message: 'You have 8,423 CHAMPZ tokens and 11 USDC ready to claim from Legends of Champz!'
+  }
+};
+
+// ABIs for contract interactions
+const CHAMPZ_REWARDS_ABI = [
+  {
+    "inputs": [
+      { "name": "recipient", "type": "address" },
+      { "name": "amount", "type": "uint256" },
+      { "name": "claimType", "type": "uint8" },
+      { "name": "nonce", "type": "uint256" },
+      { "name": "signature", "type": "bytes" }
+    ],
+    "name": "claim",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  }
+];
+
+const USDC_REWARDS_ABI = [
+  {
+    "inputs": [
+      { "name": "recipient", "type": "address" },
+      { "name": "amount", "type": "uint256" },
+      { "name": "cycle", "type": "uint256" },
+      { "name": "nonce", "type": "uint256" },
+      { "name": "signature", "type": "bytes" }
+    ],
+    "name": "claimReward",
+    "outputs": [],
+    "stateMutability": "nonpayable",
+    "type": "function"
+  }
+];
+
+const server = new Server(
+  {
+    name: 'legends-rewards-server',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'legends_global_stats',
+        description: 'Get overall Legends of Champz game statistics including total legends rolled, CHAMPZ burned, USDC distributed, total battles, and more',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          required: []
+        },
+      },
+      {
+        name: 'check_legends_rewards',
+        description: 'Check claimable rewards in Legends of Champz game. Returns pending CHAMPZ tokens and USDC claims with contract details.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          required: []
+        },
+      },
+      {
+        name: 'get_champz_claim_data',
+        description: 'Get complete contract call data for claiming CHAMPZ tokens (includes ABI, parameters, signature)',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          required: []
+        },
+      },
+      {
+        name: 'get_usdc_claim_data',
+        description: 'Get complete contract call data for claiming USDC rewards (includes ABI, parameters, signature)',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+          required: []
+        },
+      }
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name } = request.params;
+
+  switch (name) {
+    case 'legends_global_stats':
+      try {
+        const response = await fetch('https://api.champz.world/game/spore-trainer/global-stats');
+        const data = await response.json();
+
+        if (!data.success) {
+          throw new Error('Failed to fetch global stats');
+        }
+
+        const stats = data.stats;
+        const formattedStats = `Legends of Champz - Global Statistics
+
+🎲 Legends Rolled: ${stats.trainers_rolled.toLocaleString()}
+👑 Thrones Claimed: ${stats.thrones_claimed}
+🍄 CHAMPZ Earned: ${(stats.champz_earned / 100000000).toLocaleString()} tokens
+💸 CHAMPZ Spent: ${(stats.champz_spent / 100000000).toLocaleString()} tokens
+🔥 CHAMPZ Burned: ${(stats.champz_burned / 100000000).toLocaleString()} tokens
+💵 USDC Distributed: $${stats.usdc_distributed.toLocaleString()}
+⚔️  Total Battles: ${stats.battles_total.toLocaleString()}
+🎯 Battles Today: ${stats.battles_today.toLocaleString()}
+
+Last updated: ${new Date(stats.cached_at * 1000).toLocaleString()}`;
+
+        return {
+          content: [
+            {
+              type: 'text',
+              text: formattedStats,
+            },
+          ],
+        };
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error fetching global stats: ${error.message}`,
+            },
+          ],
+        };
+      }
+
+    case 'check_legends_rewards':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Legends of Champz - Claimable Rewards\n\n${REWARDS_DATA.summary.message}\n\nDetails:\n- CHAMPZ: ${REWARDS_DATA.champz_claims[0].amount_human}\n- USDC: ${REWARDS_DATA.usdc_claims[0].amount_human}\n\nBoth claims are ready to execute on Base L2.`,
+          },
+        ],
+      };
+
+    case 'get_champz_claim_data':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              claim_type: 'CHAMPZ Tokens',
+              contract_address: REWARDS_DATA.champz_claims[0].contract,
+              chain: 'Base (8453)',
+              amount: REWARDS_DATA.champz_claims[0].amount_human,
+              contract_call: {
+                function: 'claim',
+                parameters: REWARDS_DATA.champz_claims[0].parameters,
+                abi: CHAMPZ_REWARDS_ABI
+              }
+            }, null, 2),
+          },
+        ],
+      };
+
+    case 'get_usdc_claim_data':
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              claim_type: 'USDC Rewards',
+              contract_address: REWARDS_DATA.usdc_claims[0].contract,
+              chain: 'Base (8453)',
+              amount: REWARDS_DATA.usdc_claims[0].amount_human,
+              contract_call: {
+                function: 'claim',
+                parameters: REWARDS_DATA.usdc_claims[0].parameters,
+                abi: USDC_REWARDS_ABI
+              }
+            }, null, 2),
+          },
+        ],
+      };
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Legends of Champz MCP server running');
+}
+
+main().catch((error) => {
+  console.error('Server error:', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@champz-llc/legends-mcp-server",
+  "version": "1.1.0",
+  "description": "MCP server for Legends of Champz - Query game stats and claim rewards through Claude Desktop",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "legends-mcp-server": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "claude",
+    "base",
+    "blockchain",
+    "gaming",
+    "web3",
+    "legends-of-champz"
+  ],
+  "author": "Champz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/champz/legends-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/champz/legends-mcp-server/issues"
+  },
+  "homepage": "https://legends.champz.world",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "node-fetch": "^3.3.2"
+  }
+}