@champz-llc/legends-mcp-server 1.8.0 → 1.8.2

package/docs/ai-magistrate-params-new.md

@@ -0,0 +1,142 @@
+#### 1. Risk Tolerance (0-100)
+**Role**: Direct 30% contribution to attractiveness score
+**How it works**: Higher value = higher base willingness to purchase
+**Range**: 0 (ultra-conservative) to 100 (ultra-aggressive)
+**Effect**:
+- **0-30**: Extreme caution, waits for perfect opportunities
+- **40-60**: Balanced, competes when conditions are favorable
+- **70-100**: Aggressive, pushes hard even in tough conditions
+
+**Tip**: Start at 50 in practice mode, adjust ±10 based on results
+
+---
+
+#### 2. Purchase Threshold (0-100)
+**Role**: Minimum attractiveness score required to trigger purchase
+**How it works**: Agent calculates score (0-100), only buys if score ≥ threshold
+**Range**: 0 (always buy unless hard blocked) to 100 (nearly impossible to buy)
+**Effect**:
+- **Low (20-40)**: Triggers easily, frequent purchases
+- **Medium (50-70)**: Requires favorable conditions
+- **High (80-100)**: Extremely selective, rare purchases
+
+**Relationship**: Works WITH risk tolerance (high risk + low threshold = very aggressive)
+**Tip**: 60 is balanced, lower for more activity, higher for pickier agents
+
+---
+
+#### 3. Entry Timing (0-100%)
+**Role**: Earliest point in cycle (as %) when agent can start competing
+**How it works**: Hard blocker - agent waits until cycle progress ≥ this value
+**Range**: 0% (start immediately) to 100% (never enter)
+**Effect**:
+- **0%**: Early bird, competes from cycle start
+- **25%**: Waits 2 hours (25% of 8-hour cycle)
+- **50%**: Mid-cycle entry (4 hours in)
+- **75%**: Late sniper (6 hours in)
+
+**Strategy**: Late entry = lower prices but less hold time
+**Tip**: 0-20% for active competition, 40-60% for budget preservation
+
+---
+
+#### 4. Late Entry Deterrent (0-100%) - *UI: "Cutoff"*
+**Role**: Latest point in cycle (as %) when agent will still enter
+**How it works**: Hard blocker - agent won't buy if cycle progress > this value
+**Range**: 0% (never enter) to 100% (no cutoff)
+**Effect**:
+- **50%**: Only competes in first half of cycle
+- **75%**: Allows entry up to 6 hours into cycle
+- **90%**: Nearly full cycle access
+- **100%**: No restriction (can buy until executor stops at 7.5 hours)
+
+**Works with**: Entry Timing (e.g., Entry=10%, Cutoff=60% = compete in 10-60% window)
+**Tip**: 80-100% unless testing specific time-window strategies
+
+---
+
+#### 5. Max Spend Per Cycle (USDC)
+**Role**: Hard cap on total USDC spent in one cycle
+**How it works**: Hard blocker - agent stops when cycle_spent + price > this value
+**Range**: 0.01 to your available balance
+**Effect**:
+- **Practice Mode**: 0-10 USDC (you have 10 virtual)
+- **Real Mode**: Depends on your agent wallet balance
+
+**Example**: Set to 7 USDC → Agent stops after spending 7, saves 3 for next cycle
+**Tip**: Practice: 7-9 USDC (save some), Real: 70-90% of balance
+
+---
+
+#### 6. Max Price Per Purchase (USDC)
+**Role**: Hard cap on single Guardian send price
+**How it works**: Hard blocker - agent won't buy if price > this value
+**Also affects**: Price attractiveness score (lower price/max ratio = higher score)
+**Range**: 0.01 to max_spend_per_cycle
+**Effect**: Prevents expensive rage-buys at peak competition
+- **Practice Mode**: 0.5-5 USDC typical
+- **Real Mode**: Depends on strategy and budget
+
+**Relationship**: Should be ≤ max_spend_per_cycle
+**Tip**: Set to 40-60% of max_spend_per_cycle for balanced approach
+
+---
+
+#### 7. Reserve Buffer (USDC)
+**Role**: Safety reserve that agent never spends
+**How it works**: Hard blocker - agent needs (price + reserve) ≤ balance to buy
+**Range**: 0 to your balance
+**Effect**:
+- **0 USDC**: No reserve, can spend everything
+- **2 USDC**: Always keeps 2 USDC untouched
+
+**Example**: Balance=10, Reserve=2, Price=9 → Won't buy (needs 11)
+**Tip**: Practice: 0-1 USDC, Real: 1-2 USDC for safety
+
+---
+
+#### 8. Recent Activity Deterrent (0-100)
+**Role**: How much to avoid Guardian when competition is active
+**How it works**: Reduces attractiveness score based on recent purchases (last 10 min)
+**Weight**: 20% of attractiveness score
+**Range**: 0 (ignore activity) to 100 (maximum deterrence)
+**Effect**:
+- **0**: Agent doesn't care about recent activity
+- **50**: Moderate penalty when others are active
+- **100**: Strongly avoids contested Guardian
+
+**Mechanism**: Recent sends counted → Activity score → Penalty applied
+**Tip**: 30-50 for balanced competition, 70+ to avoid bidding wars
+
+---
+
+#### 9. Price Escalation Tolerance (0-100)
+**Role**: How much to tolerate rapid price increases
+**How it works**: Reduces attractiveness score if price jumped >50% in last 30 minutes
+**Weight**: 20% of attractiveness score
+**Range**: 0 (very intolerant) to 100 (completely tolerant)
+**Effect**:
+- **0-30**: Backs off when price escalates quickly
+- **50-70**: Moderate tolerance
+- **80-100**: Ignores price escalation
+
+**Example**: Price was 1 USDC 30 min ago, now 2 USDC (+100%)
+- Tolerance=20 → Large penalty to score
+- Tolerance=80 → Small penalty
+
+**Tip**: 40-60 for balanced approach, lower if budget-conscious
+
+---
+
+#### 10. Random Factor (0-100)
+**Role**: Adds unpredictability to prevent agent patterns
+**How it works**: Adds random variance (-factor to +factor) to final score
+**Range**: 0 (completely predictable) to 100 (maximum chaos)
+**Effect**:
+- **0**: Agent behaves identically every time
+- **20**: Small variance, mostly predictable
+- **50**: Moderate variance, decisions vary noticeably
+- **100**: High variance, very unpredictable
+
+**Why useful**: Prevents other agents from perfectly predicting your behavior
+**Tip**: 10-30 for subtle variance, 0 for pure deterministic testing

package/docs/game-guide.md

@@ -318,9 +318,9 @@ As time runs out:
 
 ---
 
-## 🤖 AI Magistrate (Guardian Bot)
+## 🤖 AI Magistrate - Complete Technical Guide
 
-An **autonomous AI agent** that competes for Guardian on your behalf - no manual gameplay needed!
+An **autonomous AI agent** that competes for Guardian throne on your behalf using a sophisticated 10-parameter decision algorithm. No manual gameplay needed - configure once, let it compete all cycle!
 
 ### 🎯 Practice Mode vs 💎 Real Mode
 
@@ -345,84 +345,177 @@ An **autonomous AI agent** that competes for Guardian on your behalf - no manual
 4. **Compete**: Agent uses its 10 virtual USDC every cycle
 5. **Learn**: Analyze results and adjust strategy
 
-### ⚙️ Configuration Parameters (Detailed Guide)
-
-Fine-tune your agent with 11 configurable parameters. Understanding each one is key to building a winning strategy:
-
-#### Budget & Risk Management
-
-**1. Risk Tolerance (0-100)**
-- **What it does**: Controls how aggressively your agent competes
-- **Low (0-30)**: Conservative, waits for good opportunities, preserves budget
-- **Medium (40-60)**: Balanced approach, competes moderately
-- **High (70-100)**: Aggressive, fights for Guardian even at high prices
-- **Tip**: Start at 40-50 in practice mode, adjust based on results
-
-**2. Max Spend Per Cycle (USDC)**
-- **What it does**: Hard cap on total USDC your agent can spend in one cycle
-- **Example**: Set to 8 USDC means agent stops after spending 8, even if it has 10
-- **Strategy**: Leave room for late-cycle opportunities, don't max out early
-- **Tip**: In practice mode (10 USDC), try 6-8 to preserve budget
-
-**3. Max Price Per Purchase (USDC)**
-- **What it does**: Maximum USDC your agent will pay for a single Guardian send
-- **Example**: Set to 2 USDC means agent won't send if price exceeds 2
-- **Strategy**: Prevents overpaying at peak prices
-- **Tip**: Set to 30-50% of your max cycle spend
-
-**4. Reserve Buffer (USDC)**
-- **What it does**: Amount of USDC to keep reserved, never spent
-- **Example**: 2 USDC reserve means agent only uses 8 out of 10 available
-- **Strategy**: Safety net for unexpected situations
-- **Tip**: Set to 1-2 USDC in practice mode
-
-#### Timing Strategy
-
-**5. Entry Timing (0-480 minutes)**
-- **What it does**: How many minutes into the cycle before agent starts competing
-- **0 minutes**: Agent starts immediately when cycle begins
-- **240 minutes**: Agent waits 4 hours before first send
-- **Strategy**: Late entry can be cheaper but risks losing hold time
-- **Tip**: Try 0 (early bird), 120 (mid-cycle), or 300 (late sniper)
-
-**6. Send Frequency (minutes)**
-- **What it does**: Minimum time between sends when actively competing
-- **Example**: 30 minutes means agent waits at least 30 min between sends
-- **Strategy**: Lower frequency = more conservative, higher = more aggressive
-- **Tip**: Match to your risk tolerance (high risk = low frequency)
-
-**7. Deterrent Delay (minutes)**
-- **What it does**: How long agent waits after being overtaken before responding
-- **Example**: 15 minutes means agent waits 15 min after losing Guardian
-- **Strategy**: Longer delay saves budget, shorter delay maintains position
-- **Tip**: 10-20 minutes balances responsiveness and efficiency
-
-#### Advanced Tactics
-
-**8. Deterrent Threshold (%)**
-- **What it does**: How much more expensive must it be before agent gives up position
-- **Example**: 150% means agent stops if next send costs 1.5× current price
-- **Strategy**: Higher threshold = more stubborn, lower = more flexible
-- **Tip**: 120-150% is balanced
-
-**9. Late Cycle Aggression Boost (%)**
-- **What it does**: Risk multiplier applied in final 60 minutes of cycle
-- **Example**: 150% boost turns risk 50 into effective 75 near cycle end
-- **Strategy**: Push harder when it matters most
-- **Tip**: 120-150% for moderate boost, 200%+ for all-in finale
-
-**10. Competition Response Mode**
-- **What it does**: How agent reacts when multiple agents are active
-- **Passive**: Backs off when competition is high
-- **Balanced**: Adjusts strategy based on competitors
-- **Aggressive**: Fights harder when challenged
-- **Tip**: Try "Balanced" first, adjust based on leaderboard
-
-**11. Price Ceiling (% of Budget)**
-- **What it does**: Never pay more than this % of total budget for one send
-- **Example**: 30% ceiling with 10 USDC means max 3 USDC per send
-- **Strategy**: Prevents budget depletion on single expensive send
-- **Tip**: 25-40% is reasonable
+### 🧠 How the AI Decision Algorithm Works
+
+Your agent runs a **3-phase decision algorithm** every few minutes during the cycle:
+
+**Phase 1: Hard Blockers** (Instant rejection if any fail)
+1. Price too high (> max_price_per_purchase) → **NO**
+2. Insufficient balance (< price + reserve) → **NO**
+3. Cycle budget exhausted → **NO**
+4. Entry timing not reached yet → **WAIT**
+5. Late entry cutoff exceeded → **NO**
+
+**Phase 2: Attractiveness Score** (0-100 calculated from 4 factors)
+1. **Price Attractiveness (30% weight)**: Lower price = higher score
+2. **Activity Deterrent (20% weight)**: Recent competition reduces score
+3. **Price Escalation (20% weight)**: Rapid price increases reduce score
+4. **Risk Tolerance (30% weight)**: Your configured risk level
+
+**Phase 3: Decision**
+- If attractiveness score ≥ purchase_threshold → **BUY**
+- Otherwise → **WAIT**
+
+This algorithm runs continuously every ~5-10 minutes (depending on competition) for 7.5 hours per cycle.
+
+---
+
+### ⚙️ Configuration Parameters - Complete Reference
+
+Your agent has **10 configurable parameters**. Master these to build winning strategies:
+
+#### 1. Risk Tolerance (0-100)
+**Role**: Direct 30% contribution to attractiveness score
+**How it works**: Higher value = higher base willingness to purchase
+**Range**: 0 (ultra-conservative) to 100 (ultra-aggressive)
+**Effect**:
+- **0-30**: Extreme caution, waits for perfect opportunities
+- **40-60**: Balanced, competes when conditions are favorable
+- **70-100**: Aggressive, pushes hard even in tough conditions
+
+**Tip**: Start at 50 in practice mode, adjust ±10 based on results
+
+---
+
+#### 2. Purchase Threshold (0-100)
+**Role**: Minimum attractiveness score required to trigger purchase
+**How it works**: Agent calculates score (0-100), only buys if score ≥ threshold
+**Range**: 0 (always buy unless hard blocked) to 100 (nearly impossible to buy)
+**Effect**:
+- **Low (20-40)**: Triggers easily, frequent purchases
+- **Medium (50-70)**: Requires favorable conditions
+- **High (80-100)**: Extremely selective, rare purchases
+
+**Relationship**: Works WITH risk tolerance (high risk + low threshold = very aggressive)
+**Tip**: 60 is balanced, lower for more activity, higher for pickier agents
+
+---
+
+#### 3. Entry Timing (0-100%)
+**Role**: Earliest point in cycle (as %) when agent can start competing
+**How it works**: Hard blocker - agent waits until cycle progress ≥ this value
+**Range**: 0% (start immediately) to 100% (never enter)
+**Effect**:
+- **0%**: Early bird, competes from cycle start
+- **25%**: Waits 2 hours (25% of 8-hour cycle)
+- **50%**: Mid-cycle entry (4 hours in)
+- **75%**: Late sniper (6 hours in)
+
+**Strategy**: Late entry = lower prices but less hold time
+**Tip**: 0-20% for active competition, 40-60% for budget preservation
+
+---
+
+#### 4. Late Entry Deterrent (0-100%) - *UI: "Cutoff"*
+**Role**: Latest point in cycle (as %) when agent will still enter
+**How it works**: Hard blocker - agent won't buy if cycle progress > this value
+**Range**: 0% (never enter) to 100% (no cutoff)
+**Effect**:
+- **50%**: Only competes in first half of cycle
+- **75%**: Allows entry up to 6 hours into cycle
+- **90%**: Nearly full cycle access
+- **100%**: No restriction (can buy until executor stops at 7.5 hours)
+
+**Works with**: Entry Timing (e.g., Entry=10%, Cutoff=60% = compete in 10-60% window)
+**Tip**: 80-100% unless testing specific time-window strategies
+
+---
+
+#### 5. Max Spend Per Cycle (USDC)
+**Role**: Hard cap on total USDC spent in one cycle
+**How it works**: Hard blocker - agent stops when cycle_spent + price > this value
+**Range**: 0.01 to your available balance
+**Effect**:
+- **Practice Mode**: 0-10 USDC (you have 10 virtual)
+- **Real Mode**: Depends on your agent wallet balance
+
+**Example**: Set to 7 USDC → Agent stops after spending 7, saves 3 for next cycle
+**Tip**: Practice: 7-9 USDC (save some), Real: 70-90% of balance
+
+---
+
+#### 6. Max Price Per Purchase (USDC)
+**Role**: Hard cap on single Guardian send price
+**How it works**: Hard blocker - agent won't buy if price > this value
+**Also affects**: Price attractiveness score (lower price/max ratio = higher score)
+**Range**: 0.01 to max_spend_per_cycle
+**Effect**: Prevents expensive rage-buys at peak competition
+- **Practice Mode**: 0.5-5 USDC typical
+- **Real Mode**: Depends on strategy and budget
+
+**Relationship**: Should be ≤ max_spend_per_cycle
+**Tip**: Set to 40-60% of max_spend_per_cycle for balanced approach
+
+---
+
+#### 7. Reserve Buffer (USDC)
+**Role**: Safety reserve that agent never spends
+**How it works**: Hard blocker - agent needs (price + reserve) ≤ balance to buy
+**Range**: 0 to your balance
+**Effect**:
+- **0 USDC**: No reserve, can spend everything
+- **2 USDC**: Always keeps 2 USDC untouched
+
+**Example**: Balance=10, Reserve=2, Price=9 → Won't buy (needs 11)
+**Tip**: Practice: 0-1 USDC, Real: 1-2 USDC for safety
+
+---
+
+#### 8. Recent Activity Deterrent (0-100)
+**Role**: How much to avoid Guardian when competition is active
+**How it works**: Reduces attractiveness score based on recent purchases (last 10 min)
+**Weight**: 20% of attractiveness score
+**Range**: 0 (ignore activity) to 100 (maximum deterrence)
+**Effect**:
+- **0**: Agent doesn't care about recent activity
+- **50**: Moderate penalty when others are active
+- **100**: Strongly avoids contested Guardian
+
+**Mechanism**: Recent sends counted → Activity score → Penalty applied
+**Tip**: 30-50 for balanced competition, 70+ to avoid bidding wars
+
+---
+
+#### 9. Price Escalation Tolerance (0-100)
+**Role**: How much to tolerate rapid price increases
+**How it works**: Reduces attractiveness score if price jumped >50% in last 30 minutes
+**Weight**: 20% of attractiveness score
+**Range**: 0 (very intolerant) to 100 (completely tolerant)
+**Effect**:
+- **0-30**: Backs off when price escalates quickly
+- **50-70**: Moderate tolerance
+- **80-100**: Ignores price escalation
+
+**Example**: Price was 1 USDC 30 min ago, now 2 USDC (+100%)
+- Tolerance=20 → Large penalty to score
+- Tolerance=80 → Small penalty
+
+**Tip**: 40-60 for balanced approach, lower if budget-conscious
+
+---
+
+#### 10. Random Factor (0-100)
+**Role**: Adds unpredictability to prevent agent patterns
+**How it works**: Adds random variance (-factor to +factor) to final score
+**Range**: 0 (completely predictable) to 100 (maximum chaos)
+**Effect**:
+- **0**: Agent behaves identically every time
+- **20**: Small variance, mostly predictable
+- **50**: Moderate variance, decisions vary noticeably
+- **100**: High variance, very unpredictable
+
+**Why useful**: Prevents other agents from perfectly predicting your behavior
+**Tip**: 10-30 for subtle variance, 0 for pure deterministic testing
 
 ### 💰 Rewards
 

package/index.js

@@ -295,6 +295,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
           },
           required: []
         },
+      },
+      {
+        name: 'legends_game_guide',
+        description: 'Get comprehensive game guide information about Legends of Champz. Use this tool when users ask about game mechanics, how to play, strategies, features, or any game-related questions. Covers: battles, elements, Guardian, Elemental Charge, AI Magistrate, rewards, achievements, tiers, AP system, and pro tips.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            topic: {
+              type: 'string',
+              description: 'Optional: specific topic to search for (e.g., "elemental charge", "AI magistrate", "guardian", "battles", "achievements"). If not provided, returns overview.',
+            }
+          },
+          required: []
+        },
       }
     ];
 
@@ -1460,6 +1474,86 @@ You can still ask about:
         };
       }
 
+    case 'legends_game_guide':
+      try {
+        const docPath = join(__dirname, 'docs', 'game-guide.md');
+        const fullGuide = readFileSync(docPath, 'utf-8');
+
+        const topic = request.params.arguments?.topic;
+
+        if (!topic) {
+          // Return full guide overview
+          return {
+            content: [
+              {
+                type: 'text',
+                text: fullGuide,
+              },
+            ],
+          };
+        }
+
+        // Search for specific topic (case-insensitive)
+        const topicLower = topic.toLowerCase();
+        const lines = fullGuide.split('\n');
+        let relevantSection = '';
+        let inRelevantSection = false;
+        let sectionDepth = 0;
+
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          const lineLower = line.toLowerCase();
+
+          // Check if this line is a header that matches our topic
+          if (line.startsWith('#')) {
+            const headerLevel = line.match(/^#+/)[0].length;
+
+            if (lineLower.includes(topicLower)) {
+              inRelevantSection = true;
+              sectionDepth = headerLevel;
+              relevantSection = line + '\n';
+            } else if (inRelevantSection && headerLevel <= sectionDepth) {
+              // Hit a same-level or higher-level header, section ended
+              break;
+            }
+          }
+
+          if (inRelevantSection) {
+            relevantSection += line + '\n';
+          }
+        }
+
+        if (relevantSection) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Found relevant section about "${topic}":\n\n${relevantSection}`,
+              },
+            ],
+          };
+        } else {
+          // Topic not found, return full guide
+          return {
+            content: [
+              {
+                type: 'text',
+                text: `Topic "${topic}" not found in specific section. Here's the complete game guide:\n\n${fullGuide}`,
+              },
+            ],
+          };
+        }
+      } catch (error) {
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `Error reading game guide: ${error.message}`,
+            },
+          ],
+        };
+      }
+
     case 'show_throne':
       if (!hasWalletAuth) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@champz-llc/legends-mcp-server",
-  "version": "1.8.0",
+  "version": "1.8.2",
   "description": "MCP server for Legends of Champz - Query game stats, access personal data with signature auth, and claim rewards through Claude Desktop",
   "type": "module",
   "main": "index.js",