Minecraft MCP Server

Instructions

Implementation Reference

• mcp-server/src/skills/verified/giveItemToSomeone.ts:18-54 (handler)

  The primary handler function for the 'giveItemToSomeone' tool. It validates input parameters, unpacks them, logs the action, and delegates the tossing logic to the tossItemTowardsPlayer helper.

  export const giveItemToSomeone = async (
    bot: Bot,
    params: ISkillParams,
    serviceParams: ISkillServiceParams,
  ): Promise<boolean> => {
    const skillName = 'giveItemToSomeone';
    const requiredParams = ['userName', 'itemName'];
    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 = {
      playerName: params.userName,
      itemName: params.itemName,
      itemCount: params.itemCount ?? 1,
    };
  
    console.log(
      `Giving ${unpackedParams.itemCount} of ${unpackedParams.itemName} to ${unpackedParams.playerName}`,
    );
    return tossItemTowardsPlayer(bot, {
      playerName: unpackedParams.playerName,
      itemName: unpackedParams.itemName,
      itemCount: unpackedParams.itemCount,
      signal: serviceParams.signal,
    });
  };

• mcp-server/src/skills/library/tossItemTowardsPlayer.ts:33-143 (helper)

  Core helper function that performs the actual item tossing: validates conditions, moves near the player using pathfinder, looks at the player, and tosses the specified item count using bot.toss().

  export const tossItemTowardsPlayer = async (
    bot: Bot,
    options: ITossItemTowardsPlayerOptions,
  ): Promise<boolean> => {
    const defaultOptions = {
      itemCount: 1,
    };
    const { playerName, itemName, itemCount, signal } = {
      ...defaultOptions,
      ...options,
    };
  
    // max reasonable distance to trade is currently set to same as nearbyPlayerRadius
    const maxGiveDistance = bot.nearbyPlayerRadius;
  
    // Ensure target is a string
    if (typeof playerName !== 'string') {
      return bot.emit(
        'alteraBotEndObservation',
        `Mistake: Invalid playerName: playerName must be a string.`,
      );
    }
  
    const closestItemName = findClosestItemName(bot, { name: itemName });
  
    if (!closestItemName) {
      return bot.emit(
        'alteraBotEndObservation',
        `Mistake: You couldn't give ${itemName} because there's no item named ${itemName} in minecraft.`,
      );
    }
  
    const player = findClosestPlayerByName(bot, { name: playerName });
  
    if (!player) {
      console.log('Player not found!');
      return bot.emit(
        'alteraBotEndObservation',
        `Mistake: The player ${playerName} could not be found.`,
      );
    }
  
    const playerPos = player.position;
    const botPos = bot.entity.position;
    const distanceToPlayer = calculateDistance(botPos, playerPos);
  
    if (distanceToPlayer > maxGiveDistance) {
      bot.emit(
        'alteraBotEndObservation',
        `The player ${playerName} is too far away, you may want to go to their position at ${Math.floor(playerPos.x)}, ${Math.floor(playerPos.y)}, ${Math.floor(playerPos.z)}.`,
      );
      return;
    }
  
    const hasEnough = checkInventoryForItem(bot, closestItemName, itemCount);
    if (!hasEnough) {
      return bot.emit(
        'alteraBotEndObservation',
        `You do not have ${itemCount} of ${closestItemName} to give to ${playerName}.`,
      );
    }
  
    // Stop any existing movement / pathing
    if (bot.pathfinder.isMoving()) {
      await bot.pathfinder.stop();
    }
  
    await bot.waitForTicks(1);
  
    // Create a goal to move near the player
    const maxDistance = 3; // Maximum distance to toss item
    const {
      goals: { GoalNear },
    } = mineflayer_pathfinder;
    const goal = new GoalNear(playerPos.x, playerPos.y, playerPos.z, maxDistance);
    // Move close to the player
    try {
      let reachedGiveTarget = false;
      // start pathfinder to move to the player
      bot.pathfinder.goto(goal).then(() => {
        reachedGiveTarget = true;
      });
  
      // check for a cancel signal during pathing
      // in absolute worst case scenario, the skill will fully time out after 30 seconds
      while (!reachedGiveTarget) {
        if (isSignalAborted(signal)) {
          return bot.emit(
            'alteraBotEndObservation',
            `You decided to do something else instead of giving ${closestItemName}to ${playerName}.`,
          );
        }
  
        await bot.waitForTicks(1);
      }
    } catch (err) {
      const error = err as Error;
      console.log(
        `Failed to reach player in tossItemTowardsPlayer: ${error.message}`,
      );
      return bot.emit(
        'alteraBotEndObservation',
        `You couldn't reach to ${playerName} to give them ${closestItemName}.`,
      );
    }
  
    const itemForToss = bot.inventory
      .items()
      .find((item) => item.name === closestItemName);
    return tossItem(bot, { player, item: itemForToss, itemCount });
  };

• mcp-server/src/skillRegistry.ts:95-103 (schema)

  Schema definition for the giveItemToSomeone tool inputs, including parameter types, descriptions, and required fields used for validation.

  giveItemToSomeone: {
      description: "Give items to another player",
      params: {
          userName: { type: "string", description: "Username of the player to give items to" },
          itemName: { type: "string", description: "Name of the item to give" },
          itemCount: { type: "number", description: "Number of items to give" }
      },
      required: ["userName", "itemName", "itemCount"]
  },

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

  The loadSkills function registers the giveItemToSomeone tool (along with others) by iterating over SKILL_METADATA, creating SkillDefinition objects with schema and dynamic executor that imports and runs the handler.

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