Quake Coding Arena MCP

Instructions

Implementation Reference

• src/tools/achievements.ts:89-120 (handler)

  Handler function that implements the core logic for the 'random_enhanced_achievement' tool: selects a random achievement by optional category filter, plays the sound, updates stats, and returns formatted response.

  async ({ category, volume }) => {
      const randomAchievement = EnhancedSoundOracle.getRandomAchievement(category);
  
      if (!randomAchievement) {
          return {
              content: [{
                  type: "text",
                  text: "❌ No achievements found for the specified category"
              }],
              success: false
          };
      }
  
      try {
          await EnhancedSoundOracle.playAchievementSound(randomAchievement, volume || 80, null, enhancedStats.voicePack);
          return {
              content: [{
                  type: "text",
                  text: `🎲 Random achievement: ${randomAchievement} played!`
              }],
              success: true,
              achievement: randomAchievement
          };
      } catch (error) {
          return {
              content: [{
                  type: "text",
                  text: `❌ Error playing ${randomAchievement}: ${error instanceof Error ? error.message : String(error)}`
              }],
              success: false
          };
      }

• src/tools/achievements.ts:78-80 (schema)

  Zod input schema defining parameters for the tool: optional 'category' enum and 'volume' number with validation.

      category: z.enum(["streak", "quality", "multi", "game", "team"]).optional().describe("🎯 Filter achievements by category. Options: 'streak' (RAMPAGE, DOMINATING, etc.), 'quality' (EXCELLENT, PERFECT, etc.), 'multi' (WICKED SICK, HEADSHOT, etc.), 'game' (FIRST BLOOD, HUMILIATION, etc.), 'team' (PREPARE TO FIGHT, PLAY). If omitted, selects from all categories."),
      volume: z.number().min(0).max(100).default(80).describe("🔊 Volume level for audio playback (0-100). Default is 80. Higher values increase audio volume."),
  },

• src/tools/achievements.ts:73-122 (registration)

  MCP server tool registration for 'random_enhanced_achievement' including full schema, annotations, and handler reference.

  server.registerTool(
      "random_enhanced_achievement",
      {
          description: "🎲 Play a random achievement sound from a specific category. Useful for surprise celebrations or testing different achievement sounds. Returns the selected achievement name.",
          inputSchema: {
              category: z.enum(["streak", "quality", "multi", "game", "team"]).optional().describe("🎯 Filter achievements by category. Options: 'streak' (RAMPAGE, DOMINATING, etc.), 'quality' (EXCELLENT, PERFECT, etc.), 'multi' (WICKED SICK, HEADSHOT, etc.), 'game' (FIRST BLOOD, HUMILIATION, etc.), 'team' (PREPARE TO FIGHT, PLAY). If omitted, selects from all categories."),
              volume: z.number().min(0).max(100).default(80).describe("🔊 Volume level for audio playback (0-100). Default is 80. Higher values increase audio volume."),
          },
          annotations: {
              title: "🎲 Random Achievement",
              readOnlyHint: false,
              destructiveHint: false,
              idempotentHint: false,
              openWorldHint: true
          }
      },
      async ({ category, volume }) => {
          const randomAchievement = EnhancedSoundOracle.getRandomAchievement(category);
  
          if (!randomAchievement) {
              return {
                  content: [{
                      type: "text",
                      text: "❌ No achievements found for the specified category"
                  }],
                  success: false
              };
          }
  
          try {
              await EnhancedSoundOracle.playAchievementSound(randomAchievement, volume || 80, null, enhancedStats.voicePack);
              return {
                  content: [{
                      type: "text",
                      text: `🎲 Random achievement: ${randomAchievement} played!`
                  }],
                  success: true,
                  achievement: randomAchievement
              };
          } catch (error) {
              return {
                  content: [{
                      type: "text",
                      text: `❌ Error playing ${randomAchievement}: ${error instanceof Error ? error.message : String(error)}`
                  }],
                  success: false
              };
          }
      }
  );

• index.js:754-770 (handler)

  Handler method in standalone MCP server implementation that handles 'random_enhanced_achievement' by selecting random achievement and delegating to general sound play handler.

  async playRandomEnhancedAchievement(args) {
    const { category, volume = enhancedStats.volume } = args;
  
    const randomAchievement = EnhancedSoundOracle.getRandomAchievement(category);
  
    if (!randomAchievement) {
      throw new McpError(
        ErrorCode.InternalError,
        "🎲 No enhanced achievements available for the specified category!"
      );
    }
  
    return await this.handleEnhancedSoundPlay({
      achievement: randomAchievement,
      volume: volume
    });
  }

• index.js:342-357 (schema)

  JSON schema for tool input in the ListTools response for 'random_enhanced_achievement'.

  inputSchema: {
    type: "object",
    properties: {
      category: {
        type: "string",
        description: "🎯 Filter by category (streak, quality, multi, game, team, powerup, custom)",
        enum: ["streak", "quality", "multi", "game", "team", "powerup", "custom"],
      },
      volume: {
        type: "number",
        description: "🔊 Enhanced volume level (0-100)",
        minimum: 0,
        maximum: 100,
        default: 80,
      },
    },