Minecraft MCP Server

Instructions

Implementation Reference

• mcp-server/src/skills/verified/attackSomeone.ts:20-51 (handler)

  The main exported handler function for the 'attackSomeone' MCP tool. It validates the input parameters and delegates execution to the core 'attack' helper function.

  export const attackSomeone = async (
    bot: Bot,
    params: ISkillParams,
    serviceParams: ISkillServiceParams,
  ): Promise<boolean> => {
    const skillName = 'attackSomeone';
    const requiredParams = ['targetType'];
    const isParamsValid = validateSkillParams(
      params,
      requiredParams,
      skillName,
    );
    if (!isParamsValid) {
      serviceParams.cancelExecution?.();
      bot.emit(
        'alteraBotEndObservation',
        `Mistake: You didn't provide all of the required parameters ${requiredParams.join(', ')} for the ${skillName} skill.`,
      );
      return false;
    }
  
    return attack(bot, {
      targetType: params.targetType ?? null,
      targetName: params.targetName ?? '',
      duration: params.duration ?? 20,
      killNumber: params.count ?? 1,
      signal: serviceParams.signal,
      getStatsData: serviceParams.getStatsData,
      setStatsData: serviceParams.setStatsData,
      resetTimeout: serviceParams.resetTimeout,
    });
  };

• mcp-server/src/skills/library/attack.ts:33-233 (helper)

  Core helper function implementing the attack logic: finds targets, equips sword, attacks, handles multiple kills, collects loot by navigating to death position, manages timeouts and cancellations.

  export const attack = async (
    bot: Bot,
    options: IAttackOptions,
  ): Promise<boolean> => {
    const defaultOptions = {
      targetType: '',
      targetName: '',
      duration: 20,
      killNumber: 1,
    };
    let {
      targetType,
      targetName,
      duration,
      killNumber,
      signal,
      setStatsData,
      getStatsData,
      resetTimeout,
    } = {...defaultOptions, ...options};
    const ENTITY_RADIUS = bot.nearbyEntityRadius;
    const WAIT_TIME = 10; // 10 milliseconds
    const MAX_DURATION = 60; // 60 seconds
    const MAX_KILL_NUMBER = 5; // Maximum number of entities to kill
  
    // Stop attacking anyone before attacking someone else
    bot.pvp.forceStop();
  
    let kills = 0;
    targetName = targetName ?? '';
  
    const targetStr = targetName ? targetName : targetType;
    targetName = targetName.replace(/\s/g, '_'); // Replace spaces in name with _
  
    duration = Math.min(duration, MAX_DURATION); // Set max duration to 60 seconds.
    killNumber = Math.min(killNumber, MAX_KILL_NUMBER); // Set max duration to 60 seconds.
  
    // filter for the target using the entity type
    let target = findTarget(bot, {targetType, targetName});
  
    if (!target) {
      return bot.emit(
        'alteraBotEndObservation',
        `Mistake: You chose to attack ${targetName} but you couldn't find anyone with that name.`,
      );
    }
  
    if (
      target.position.distanceTo(bot.entity.position) > ENTITY_RADIUS &&
      (targetType === 'mob' || targetType === 'animal')
    ) {
      return bot.emit(
        'alteraBotEndObservation',
        `There's no ${targetStr} close enough for you to attack.`,
      );
    }
  
    autoEquipSword(bot);
  
    const startTime = Date.now();
  
    let endMessage = null;
  
    try {
      // Event handler to collect loot after killing the target
      const handleDeath = async (entity: Entity) => {
        // console.log(entity === target)
        if (entity === target) {
          bot.pvp.forceStop();
  
          kills++;
          resetTimeout(); // reset the skill timeout on the bot to make sure the bot doesn't stop the skill while it's still attacking
          if (kills < killNumber)
            bot.emit(
              'alteraBotTextObservation',
              `You have killed ${kills} of ${killNumber} ${targetStr}.`,
            );
  
          // move to the target's last known position to (hopefully) collect loot
          const navigateFunc = async function () {
            return navigateToLocation(bot, {
              x: target.position.x,
              y: target.position.y,
              z: target.position.z,
              range: 0.5,
            });
          };
          await asyncwrap({func: navigateFunc, setStatsData, getStatsData});
  
          // Check if we're done killing
          await bot.waitForTicks(2);
  
          if (isSignalAborted(signal)) {
            stopAttack();
            endMessage = `You decided to do something else after you killed ${kills} ${targetStr}.`;
            return;
          }
  
          // check signal for cancellation
          if (kills >= killNumber) {
            stopAttack();
            endMessage = `You finished killing ${kills} ${targetStr}.`;
            return;
          }
  
          // Select a new target, since there are more to kill
          let newTarget = findTarget(bot, {targetType, targetName});
  
          // make sure the target is the entity we just killed and that we have a new target
          // find target may still find the same target for a brief window
          let findTargetLimit = 40; // emergency limit to prevent infinite loop // this is in ticks
          while (newTarget == target && findTargetLimit >= 0) {
            newTarget = findTarget(bot, {targetType, targetName});
            await bot.waitForTicks(1);
            findTargetLimit--;
          }
  
          if (findTargetLimit <= 0) {
            stopAttack();
            endMessage = `ERROR: couldn't find a new ${targetStr} to kill.`;
            return;
          }
  
          target = newTarget;
  
          if (
            !target ||
            (target.position.distanceTo(bot.entity.position) > ENTITY_RADIUS &&
              (targetType === 'mob' || targetType === 'animal'))
          ) {
            stopAttack();
            endMessage = `You killed ${kills} ${targetStr} and there are no more ${targetStr} nearby.`;
            return;
          }
  
          console.log(` attacking the next ${targetStr}.`);
  
          // re-equip a sword (in case old one broke)
          autoEquipSword(bot);
          bot.pathfinder.stop(); // Stop pathfinding
  
          // Reset the loot trigger and start attacking the new target
          bot.waitForTicks(2);
  
          bot.pvp.attack(target);
        }
        return;
      };
  
      bot.on('entityDead', handleDeath);
  
      // await asyncwrap(async function(){return bot.pvp.attack(target)});
      bot.pvp.attack(target);
  
      let cleanUpTimeout;
      let stoppedAttacking = false;
  
      const stopAttack = () => {
        if (!stoppedAttacking) {
          bot.removeListener('entityDead', handleDeath);
          bot.pvp.forceStop();
          stoppedAttacking = true;
          attacking = false;
        }
      };
  
      let attackTime = 0;
      let attacking = true;
      const totalDuration = duration * 1000;
      while (attacking && attackTime < totalDuration) {
        // check signal for cancellation
        // this check may be redundant, but it's here just in case
        if (isSignalAborted(signal)) {
          stopAttack();
          if (!endMessage)
            endMessage = `You decided to do something else instead of attacking ${targetStr}.`;
          return bot.emit('alteraBotEndObservation', endMessage);
        }
  
        // wait for 10 milliseconds
        await new Promise((resolve) => setTimeout(resolve, WAIT_TIME));
  
        attackTime += WAIT_TIME;
      }
  
      console.log(` stopped attacking after ${duration} seconds.`);
  
      stopAttack();
  
      if (!endMessage)
        endMessage = `You stopped attacking ${targetStr} after ${duration} seconds.`;
  
      return bot.emit('alteraBotEndObservation', endMessage);
    } catch (err) {
      const error = err as Error;
      return bot.emit(
        'alteraBotEndObservation',
        `You couldn't attack ${targetStr} because: ${error.message}`,
      );
    }
  };

• mcp-server/src/skillRegistry.ts:39-48 (schema)

  Input schema and metadata definition for the 'attackSomeone' tool, including parameters, descriptions, and required fields.

  attackSomeone: {
      description: "Attack, kill, defend against, or initiate combat with someone",
      params: {
          targetType: { type: "string", description: "The type of target: 'player', 'mob', or 'animal'" },
          targetName: { type: "string", description: "Optional: The specific name of the entity to attack" },
          duration: { type: "number", description: "Optional: Duration in seconds to attack (default: 20, max: 120)" },
          count: { type: "number", description: "Optional: Number of kills to achieve (default: 1)" }
      },
      required: ["targetType"]
  },

• mcp-server/src/skillRegistry.ts:350-367 (registration)

  Dynamic registration of all skills, including 'attackSomeone', by iterating over SKILL_METADATA and creating SkillDefinition objects with schema and executor.

  export async function loadSkills(): Promise<SkillDefinition[]> {
      const skills: SkillDefinition[] = [];
  
      for (const [skillName, metadata] of Object.entries(SKILL_METADATA)) {
          skills.push({
              name: skillName,
              description: metadata.description,
              inputSchema: {
                  type: "object",
                  properties: metadata.params,
                  required: metadata.required
              },
              execute: createSkillExecutor(skillName)
          });
      }
  
      return skills;
  }