Minecraft MCP Server

Instructions

Implementation Reference

• mcp-server/src/skills/verified/runAway.ts:26-179 (handler)

  The core handler function implementing the 'runAway' tool logic. Detects nearby hostile mobs or specified targets, computes a weighted escape vector, and uses pathfinder to move to a safe distance.

  export const runAway = async (
    bot: Bot,
    params: ISkillParams,
    serviceParams: ISkillServiceParams,
  ): Promise<boolean> => {
    const skillName = 'runAway';
    const requiredParams: string[] = [];
    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;
    }
  
    const unpackedParams = {
      targetType: params.targetType ?? 'mob',
      targetName: params.targetName ?? '',
      runDistance: params.runDistance ?? 10,
      signal: serviceParams.signal,
    };
    let { targetType, targetName, runDistance, signal } = unpackedParams;
    // Define the radius within which you want to detect mobs
    const NEARBY_ENTITY_RADIUS = bot.nearbyEntityRadius;
    const MIN_DISTANCE = 0.01; // Minimum distance to avoid extremely small values
  
    targetName = targetName ?? '';
  
    const targetStr = targetName ? targetName : targetType;
    targetName = targetName.replace(/\s/g, '_'); // Replace spaces in name with _
  
    if (targetType == 'mob') {
      targetType = 'hostile';
    }
  
    // Check if entities are available
    if (!bot.entities) return;
  
    const allEntities = Object.values(bot.entities);
  
    // Filter function to identify mobs within the specified radius
    const isNearbyEntity = (entity: Entity) => {
      return (
        entity.position.distanceTo(bot.entity.position) < NEARBY_ENTITY_RADIUS
      );
    };
  
    // Filter for nearby hostile mobs
    const hostileMobs = allEntities.filter((entity) => {
      const version = parseInt(bot.version.split('.')[1]);
      const NBT_HEALTH =
        version < 10 ? 6 : version < 14 ? 7 : version < 17 ? 8 : 9;
      if (targetName) {
        if (targetType === 'player') {
          const closestPlayer = findClosestPlayerByName(bot, { name: targetName });
          return (
            isNearbyEntity(entity) &&
            entity.username !== bot.entity.username &&
            entity.username == closestPlayer.username
          );
        } else {
          return (
            isNearbyEntity(entity) &&
            entity.name.toLowerCase() === targetName.toLowerCase()
          );
        }
      }
      return (
        isNearbyEntity(entity) &&
        entity.type === targetType &&
        entity.metadata[NBT_HEALTH] &&
        entity.username !== bot.entity.username
      );
    });
  
    // Check if there are no hostile mobs
    if (hostileMobs.length === 0) {
      return bot.emit(
        'alteraBotEndObservation',
        `There are no ${targetType}s to run away from.`,
      );
    }
  
    // Calculate the weighted vector direction to run away
    const runVector = { x: 0, y: 0, z: 0 };
    hostileMobs.forEach((mob) => {
      const vector = {
        x: bot.entity.position.x - mob.position.x,
        y: bot.entity.position.y - mob.position.y,
        z: bot.entity.position.z - mob.position.z,
      };
  
      const distance = Math.sqrt(vector.x ** 2 + vector.y ** 2 + vector.z ** 2);
      const weight = 1 / Math.max(distance, MIN_DISTANCE); // Avoid division by extremely small values
  
      runVector.x += vector.x * weight;
      runVector.y += vector.y * weight;
      runVector.z += vector.z * weight;
    });
  
    // Normalize the resulting vector
    const vectorLength = Math.sqrt(
      runVector.x ** 2 + runVector.y ** 2 + runVector.z ** 2,
    );
    if (vectorLength > 0) {
      runVector.x /= vectorLength;
      runVector.y /= vectorLength;
      runVector.z /= vectorLength;
    }
  
    // Determine the destination position
    const runDestination = new Vec3(
      bot.entity.position.x + runVector.x * runDistance,
      bot.entity.position.y + runVector.y * runDistance,
      bot.entity.position.z + runVector.z * runDistance,
    );
  
    if (bot.pathfinder.isMoving()) await bot.pathfinder.stop();
  
    await bot.waitForTicks(1); // give the pathfinder some time to stop
  
    // Make the bot move to the destination position
    const goal = new GoalXZ(runDestination.x, runDestination.z);
  
    // execute a cancelable move to the destination
    const result = await cancelableMove(bot, { goal, signal });
  
    // check signal 1st
    if (isSignalAborted(signal)) {
      return bot.emit(
        'alteraBotEndObservation',
        `You decided to do something else and stop running away.`,
      );
    }
  
    if (result.error) {
      return bot.emit(
        'alteraBotEndObservation',
        `You couldn't finish running away, but did your best.`,
      );
    }
  
    // Print out the list of all nearby hostile mobs
    // const hostileMobNames = hostileMobs.map(entity => entity.name);
    // const uniqueHostileMobTypes = [...new Set(hostileMobNames)];
    // console.log(`Nearby hostile mobs: ${hostileMobNames.join(', ')}`);
    return bot.emit('alteraBotEndObservation', `You have finished running away!`);
  };

• mcp-server/src/skillRegistry.ts:191-199 (schema)

  Input schema and metadata definition for the 'runAway' tool used during registration, specifying parameters like targetType (required), targetName, and runDistance.

  runAway: {
      description: "Run away from a threat",
      params: {
          targetType: { type: "string", description: "Type of threat: 'player', 'mob', or 'animal'" },
          targetName: { type: "string", description: "Optional: Specific name of the threat" },
          runDistance: { type: "number", description: "Distance to run away (default: 20)" }
      },
      required: ["targetType"]
  },

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

  Generic registration logic in loadSkills() that registers all skills including 'runAway' from SKILL_METADATA by creating SkillDefinition objects with schema and dynamic executor.

      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;
  }