Minecraft MCP Server

Instructions

Implementation Reference

• mcp-server/src/skills/verified/dropItem.ts:19-104 (handler)

  The main handler function that implements the dropItem tool logic: validates parameters, finds the item in inventory, optionally tosses towards a player, and drops the specified count of items using bot.toss().

  export const dropItem = async (
    bot: Bot,
    params: ISkillParams,
    serviceParams: ISkillServiceParams,
  ): Promise<boolean> => {
    const skillName = 'dropItem';
    const requiredParams = ['name'];
    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 { getStatsData, setStatsData } = serviceParams;
  
    const unpackedParams = {
      name: params.name,
      count: params.count ?? 1,
      playerName: params.userName ?? null,
      signal: serviceParams.signal,
    };
  
    if (
      unpackedParams.playerName != null &&
      unpackedParams.playerName != bot.username
    ) {
      return tossItemTowardsPlayer(bot, {
        playerName: unpackedParams.playerName,
        itemName: unpackedParams.name,
        itemCount: unpackedParams.count,
        signal: serviceParams.signal,
      });
    }
  
    // Find the closest item name from the input
    const closestItemName = findClosestItemName(bot, { name: unpackedParams.name });
    if (!closestItemName) {
      return bot.emit(
        'alteraBotEndObservation',
        `Error: There's no item named ${unpackedParams.name} in minecraft.`,
      );
    }
    unpackedParams.name = closestItemName;
  
    // Find the item in the bot's inventory
    const itemToDrop = bot.inventory
      .items()
      .find((item) => item.name === unpackedParams.name);
  
    if (!itemToDrop) {
      return bot.emit(
        'alteraBotEndObservation',
        `mistake: You don't have '${unpackedParams.name}'.`,
      );
    }
  
    try {
      // Drop the item
      const dropItemCount = Math.min(
        unpackedParams.count,
        countItems(bot, unpackedParams.name),
      );
      const tossFn = async function () {
        return bot.toss(itemToDrop.type, null, dropItemCount);
      };
      await asyncwrap({ func: tossFn, getStatsData, setStatsData });
      return bot.emit(
        'alteraBotEndObservation',
        `You dropped ${dropItemCount} ${unpackedParams.name}.`,
      );
    } catch (err) {
      const error = err as Error;
      console.log(`dropItem Error: ${error.message}`);
      return bot.emit(
        'alteraBotEndObservation',
        `You failed to drop ${unpackedParams.name}.`,
      );
    }
  };

• mcp-server/src/skillRegistry.ts:74-82 (schema)

  The input schema definition for the dropItem tool, including parameters, descriptions, and required fields.

  dropItem: {
      description: "Drop items from inventory",
      params: {
          name: { type: "string", description: "Name of the item to drop" },
          count: { type: "number", description: "Optional: Number of items to drop (default: all)" },
          userName: { type: "string", description: "Optional: Drop near a specific player" }
      },
      required: ["name"]
  },

• mcp-server/src/skillRegistry.ts:74-82 (registration)

  Registration of the dropItem tool in SKILL_METADATA, which is used by loadSkills() to create and register the SkillDefinition.

  dropItem: {
      description: "Drop items from inventory",
      params: {
          name: { type: "string", description: "Name of the item to drop" },
          count: { type: "number", description: "Optional: Number of items to drop (default: all)" },
          userName: { type: "string", description: "Optional: Drop near a specific player" }
      },
      required: ["name"]
  },

• mcp-server/src/skills/verified/dropItem.ts:106-110 (helper)

  Helper function to count the total number of a specific item in the bot's inventory, used to limit the drop count.

  const countItems = (bot: Bot, itemName: string) => {
    return bot.inventory.items().reduce((total, item) => {
      return item.name === itemName ? total + item.count : total;
    }, 0);
  };