get_ai_usage_guide

Instructions

Implementation Reference

• index.js:561-731 (handler)

  Primary handler function implementing the get_ai_usage_guide tool logic. Builds a detailed markdown guide with context-specific recommendations for using Quake achievements in coding workflows.

  async getAIUsageGuide(args) {
    const { context } = args;
  
    let guide = `🤖 **ENHANCED QUAKE ARENA - AI USAGE GUIDE** 🤖\n\n`;
    guide += `📚 Learn when and how to trigger Quake sounds for optimal coding motivation!\n\n`;
  
    if (context && context !== 'all') {
      // Context-specific guidance
      const contexts = {
        debugging: {
          title: "🔍 DEBUGGING BATTLES",
          triggers: [
            "First bug found → 🎯 FIRST BLOOD",
            "Bug fixed quickly → 🎯 HUMILIATION achievement",
            "Complex bug solved → 🎯 WICKED SICK achievement",
            "All bugs defeated → 🎯 DOMINATING achievement"
          ],
          examples: [
            "🔍 Bug located! 🎯 First blood!",
            "✅ Bug defeated! 🎯 HUMILIATION for that pesky error!",
            "🧠 Brilliant debugging! 🎯 WICKED SICK!"
          ]
        },
        features: {
          title: "🚀 FEATURE DEVELOPMENT",
          triggers: [
            "Feature complete → 🎯 EXCELLENT achievement",
            "Multiple features → 🎯 RAMPAGE achievement",
            "Complex implementation → 🎯 DOMINATING achievement",
            "Perfect implementation → 🎯 PERFECT achievement"
          ],
          examples: [
            "✅ Feature implemented! 🎯 EXCELLENT achievement at 80% volume!",
            "🚀 3 features complete! 🎯 RAMPAGE! You're on fire!",
            "💡 Perfect implementation! 🎯 PERFECT achievement!"
          ]
        },
        quality: {
          title: "✨ CODE QUALITY MOMENTS",
          triggers: [
            "Clean code → 🎯 PERFECT achievement",
            "Elegant solution → 🎯 IMPRESSIVE achievement",
            "Excellent code → 🎯 EXCELLENT achievement",
            "Legendary code → 🎯 GODLIKE achievement"
          ],
          examples: [
            "🧹 Code refactored beautifully! 🎯 PERFECT achievement!",
            "💡 Elegant solution! 🎯 IMPRESSIVE achievement!",
            "🏆 Legendary implementation! 🎯 GODLIKE at 100% volume!"
          ]
        },
        productivity: {
          title: "📈 PRODUCTIVITY STREAKS",
          triggers: [
            "Quick succession tasks → 🎯 RAMPAGE achievement",
            "Unstoppable progress → 🎯 UNSTOPPABLE achievement",
            "Major milestone → 🎯 DOMINATING achievement",
            "Session start → 🎯 PREPARE TO FIGHT"
          ],
          examples: [
            "⚡ 3 tasks in quick succession! 🎯 RAMPAGE achievement!",
            "🔥 You're unstoppable! 🎯 UNSTOPPABLE achievement!",
            "🎯 Time to code! PREPARE TO FIGHT achievement!"
          ]
        }
      };
  
      const ctx = contexts[context];
      if (ctx) {
        guide += `${ctx.title}\n\n`;
        guide += `**🎯 When to Trigger:**\n`;
        ctx.triggers.forEach(trigger => {
          guide += `• ${trigger}\n`;
        });
        guide += `\n**💬 Example Responses:**\n`;
        ctx.examples.forEach(example => {
          guide += `• ${example}\n`;
        });
      }
    } else {
      // Complete guide
      guide += `## ⚡ **INSTANT TRIGGER CHEAT SHEET**\n\n`;
  
      guide += `### **Code Quality Moments:**\n`;
      guide += `• "Perfect code" → 🎯 **PERFECT** achievement\n`;
      guide += `• "Excellent solution" → 🎯 **EXCELLENT** achievement\n`;
      guide += `• "Brilliant approach" → 🎯 **IMPRESSIVE** achievement\n`;
      guide += `• "Clean implementation" → 🎯 **PERFECT** at 70% volume\n\n`;
  
      guide += `### **Problem Solving Victories:**\n`;
      guide += `• "First bug found" → 🎯 **FIRST BLOOD**\n`;
      guide += `• "Bug defeated" → 🎯 **HUMILIATION** achievement\n`;
      guide += `• "Clever solution" → 🎯 **WICKED SICK** achievement\n`;
      guide += `• "Breakthrough moment" → 🎯 **DOMINATING** achievement\n\n`;
  
      guide += `### **Productivity Streaks:**\n`;
      guide += `• "3 tasks complete" → 🎯 **RAMPAGE** achievement\n`;
      guide += `• "Quick succession" → 🎯 **RAMPAGE** at 80% volume\n`;
      guide += `• "On a roll" → 🎯 **DOMINATING** achievement\n`;
      guide += `• "Unstoppable" → 🎯 **UNSTOPPABLE** achievement\n\n`;
  
      guide += `### **Exceptional Achievements:**\n`;
      guide += `• "Legendary solution" → 🎯 **GODLIKE** at 100% volume\n`;
      guide += `• "Amazing work" → 🎯 **GODLIKE** achievement\n`;
      guide += `• "Incredible" → 🎯 **GODLIKE** at 90% volume\n`;
      guide += `• "Mind-blowing" → 🎯 **GODLIKE** at 100% volume\n\n`;
  
      guide += `### **Project Start:**\n`;
      guide += `• "Let's code" → 🎯 **PREPARE TO FIGHT** achievement\n`;
      guide += `• "Time to start" → 🎯 **PREPARE TO FIGHT** achievement\n`;
      guide += `• "Begin coding" → 🎯 **PREPARE TO FIGHT** achievement\n\n`;
  
      guide += `## 🔊 **VOLUME GUIDELINES**\n\n`;
      guide += `• **30-50%:** Small victories, minor fixes, subtle celebrations\n`;
      guide += `• **60-80%:** Good solutions, feature completion, moderate excitement\n`;
      guide += `• **90-100%:** Exceptional achievements, breakthroughs, major celebrations\n\n`;
  
      guide += `## ✅ **DO's AND ❌ DON'Ts**\n\n`;
      guide += `**✅ DO use for:**\n`;
      guide += `• User expresses satisfaction with solution\n`;
      guide += `• Code runs successfully without errors\n`;
      guide += `• Creative or clever problem solving\n`;
      guide += `• Multiple quick wins in succession\n`;
      guide += `• Learning moments and breakthroughs\n\n`;
  
      guide += `**❌ DON'T overuse for:**\n`;
      guide += `• Every single line of code\n`;
      guide += `• Simple explanations or routine tasks\n`;
      guide += `• Failed attempts or errors\n`;
      guide += `• When user is frustrated\n`;
      guide += `• Unremarkable accomplishments\n\n`;
  
      guide += `## 📝 **SAMPLE AI RESPONSES**\n\n`;
      guide += `\`\`\n`;
      guide += `✅ Perfect implementation! 🎯 Play perfect achievement at 70% volume\n\n`;
      guide += `🔍 Bug found and fixed! 🎯 First blood!\n\n`;
      guide += `🚀 Feature complete! 🎯 Excellent achievement at 80% volume\n\n`;
      guide += `💡 Brilliant solution! 🎯 Impressive achievement at 85% volume\n\n`;
      guide += `🏆 That's legendary! 🎯 GODLIKE ACHIEVEMENT at 100% volume!\n`;
      guide += `\`\`\n\n`;
  
      guide += `## 🎪 **CONTEXTUAL EXAMPLES**\n\n`;
      guide += `**Early Morning Coding:**\n`;
      guide += `User: "Time to start coding for the day!"\n`;
      guide += `AI: "☕ Coffee ready! 🎯 Prepare to fight achievement! Let's make today productive!"\n\n`;
  
      guide += `**Debugging Session:**\n`;
      guide += `User: "Finally found that annoying bug!"\n`;
      guide += `AI: "🎯 First blood! 🎯 HUMILIATION for the bug that challenged you!"\n\n`;
  
      guide += `**Feature Development:**\n`;
      guide += `User: "This API endpoint works perfectly!"\n`;
      guide += `AI: "✅ Perfect implementation! 🎯 Perfect achievement!"\n\n`;
  
      guide += `**Complex Problem:**\n`;
      guide += `User: "This solution is incredible!"\n`;
      guide += `AI: "🏆 Legendary work! 🎯 GODLIKE ACHIEVEMENT at 100% volume!"\n`;
    }
  
    guide += `\n\n🎯 **ENHANCED QUAKE ARENA - MAKING EVERY CODING SESSION EPIC!** 🎮✨`;
    guide += `\n📊 Available achievements: ${Object.keys(ENHANCED_ACHIEVEMENTS).length}`;
    guide += `\n🔧 Current volume: ${enhancedStats.volume}%`;
  
    return {
      success: true,
      message: "🤖 AI usage guide retrieved! Master the art of motivational coding!",
      guide: guide,
      context: context || 'all',
      available_achievements: Object.keys(ENHANCED_ACHIEVEMENTS).length
    };
  }

• index.js:309-322 (registration)

  Tool registration including name, description, and input schema definition for get_ai_usage_guide in the ListTools response.

  {
    name: "get_ai_usage_guide",
    description: "🤖 AI Usage Guide: Learn when and how to trigger Quake sounds for optimal coding motivation",
    inputSchema: {
      type: "object",
      properties: {
        context: {
          type: "string",
          description: "🎯 Get specific guidance for contexts like debugging, feature development, code review",
          enum: ["debugging", "features", "quality", "productivity", "all"],
        },
      },
    },
  },

• index.js:226-227 (schema)

  Dispatch case in the central CallToolRequestSchema handler that routes to the getAIUsageGuide method.

  case "get_ai_usage_guide":
    return await this.getAIUsageGuide(args);

• src/tools/guides.ts:64-123 (registration)

  Alternative tool registration and inline handler in guides.ts module for registering guide tools on an MCP server.

      server.registerTool(
          "get_ai_usage_guide",
          {
              description: "🤖 Get context-specific usage tips and best practices for AI assistants using this MCP server. Provides recommendations on when to trigger achievements, how to use voice packs effectively, and integration patterns for gamifying development workflows.",
              inputSchema: {
                  context: z.enum(["coding", "testing", "debugging", "deployment", "general"]).optional().describe("🎯 Context for usage guide. Options: 'coding' (during code writing/refactoring), 'testing' (during test execution), 'debugging' (when fixing bugs), 'deployment' (during deployment processes), 'general' (general usage patterns). If omitted, returns comprehensive guide. Examples: 'coding', 'debugging'"),
              },
              annotations: {
                  title: "🤖 Get AI Usage Guide",
                  readOnlyHint: true,
                  destructiveHint: false,
                  idempotentHint: true,
                  openWorldHint: false
              }
          },
          async ({ context }) => {
              const contextGuides: Record<string, string> = {
                  coding: `💻 Coding Context:
  - Trigger EXCELLENT/PERFECT when code passes linting
  - Use IMPRESSIVE for creative solutions
  - Play FIRST BLOOD when starting a new feature
  - Use GODLIKE for completing major refactoring
  - Switch to female voice for variety`,
                  testing: `🧪 Testing Context:
  - Play FIRST BLOOD when first test passes
  - Use MULTI KILL for multiple passing tests
  - Trigger WICKED SICK for 100% test coverage
  - Use HOLY SHIT for unexpected test discoveries`,
                  debugging: `🐛 Debugging Context:
  - Play FIRST BLOOD when finding the bug
  - Use HEADSHOT for quick bug fixes
  - Trigger HUMILIATION for fixing embarrassing bugs
  - Use BOTTOM FEEDER when learning from mistakes`,
                  deployment: `🚀 Deployment Context:
  - Play PREPARE TO FIGHT before deployment
  - Use RAMPAGE for successful deployments
  - Trigger GODLIKE for zero-downtime deployments
  - Use PLAY to celebrate going live`,
                  general: `🌟 General Usage:
  - Set volume to 60-80% for comfortable listening
  - Switch between male/female voices for variety
  - Use random achievements for surprise celebrations
  - Track stats to see your productivity patterns
  - Combine achievements for epic moments`
              };
  
              const guide = context 
                  ? contextGuides[context] 
                  : Object.entries(contextGuides).map(([ctx, text]) => text).join('\n\n');
  
              return {
                  content: [{
                      type: "text",
                      text: `🤖 AI Usage Guide${context ? ` (${context} context)` : ''}\n\n${guide}\n\n💡 Pro Tips:\n- Use voiceGender parameter to override default voice\n- Check stats regularly to track progress\n- Combine multiple achievements for epic moments\n- Adjust volume based on environment (lower in shared spaces)`
                  }],
                  context: context || "all",
                  guide
              };
          }
      );