Minecraft MCP Server

Instructions

Implementation Reference

• mcp-server/src/skills/verified/harvestMatureCrops.ts:25-74 (handler)

  Main handler function that validates parameters, finds mature crops nearby, and harvests them by navigating to each position and digging.

  export const harvestMatureCrops = async (
    bot: Bot,
    params: ISkillParams,
    serviceParams: ISkillServiceParams,
  ): Promise<boolean> => {
    const skillName = 'harvestMatureCrops';
    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 = {
      number: params.number ?? 1000,
      radius: params.radius ?? 16,
    };
  
    const { number, radius } = unpackedParams;
    const { signal, getStatsData, setStatsData } = serviceParams;
  
    // Define crop types and their mature stage block state
    const cropsInfo = [
      { name: 'wheat', matureState: 7 },
      { name: 'carrots', matureState: 7 },
      { name: 'potatoes', matureState: 7 },
      { name: 'beetroots', matureState: 3 }, // Note: Beetroots mature at state 3
    ];
  
    const matureCrops = await findMatureCrops(bot, { cropsInfo, number, radius });
  
    // console.log("Mature crops found: ", matureCrops.length)
    if (matureCrops.length === 0) {
      return bot.emit(
        'alteraBotEndObservation',
        'You tried to harvest crops but there are no mature crops found nearby.',
      );
    }
  
    await harvestCrops(bot, { matureCrops, signal, getStatsData, setStatsData });
    bot.emit('alteraBotEndObservation', 'You have finished harvesting crops');
  };

• mcp-server/src/skills/verified/harvestMatureCrops.ts:91-112 (helper)

  Helper function to find positions of mature wheat, carrots, potatoes, and beetroots within the specified radius using bot.findBlocks.

  const findMatureCrops = async (
    bot: Bot,
    options: IFindMatureCropsOptions,
  ): Promise<Array<{ x: number; y: number; z: number }>> => {
    const { cropsInfo, number, radius } = options;
    const matureCrops = [];
    for (const cropInfo of cropsInfo) {
      const cropBlockId = bot.registry.blocksByName[cropInfo.name]?.id;
      if (!cropBlockId) continue; // Skip if crop type is not found in registry
  
      const positions = bot.findBlocks({
        point: bot.entity.position,
        matching: (block) =>
          block.type === cropBlockId && block.metadata === cropInfo.matureState,
        maxDistance: radius,
        count: number,
      });
  
      matureCrops.push(...positions);
    }
    return matureCrops;
  };

• mcp-server/src/skills/verified/harvestMatureCrops.ts:131-177 (helper)

  Helper function that iterates over mature crop positions, moves the bot to each using pathfinder, digs the block, emits observations, and handles errors and cancellation.

  const harvestCrops = async (
    bot: Bot,
    options: IHarvestCrops,
  ): Promise<boolean> => {
    const { matureCrops, signal, getStatsData, setStatsData } = options;
  
    for (const pos of matureCrops) {
      try {
        const block = bot.blockAt(new Vec3(pos.x, pos.y, pos.z));
        if (block) {
          const goal = new GoalNear(pos.x, pos.y, pos.z, 1);
          const result = cancelableMove(bot, { goal, signal });
          // check for cancelation signal
          if (isSignalAborted(signal)) {
            return bot.emit(
              'alteraBotEndObservation',
              `You decided to do something else and stopped harvesting.`,
            );
          }
  
          const digFn = async function () {
            return bot.dig(block);
          };
          await asyncwrap({ func: digFn, getStatsData, setStatsData });
  
          bot.emit(
            'alteraBotTextObservation',
            `Harvested ${block.name} at (${pos.x}, ${pos.y}, ${pos.z})`,
          );
  
          // Wait for items to drop
          const waitFn = async function () {
            return new Promise((resolve) => setTimeout(resolve, 1000));
          };
          await asyncwrap({ func: waitFn, setStatsData, getStatsData }); // Wait for 1 second
        }
      } catch (error) {
        console.error(
          `Failed to harvest at (${pos.x}, ${pos.y}, ${pos.z}): ${error}`,
        );
        bot.emit(
          'alteraBotEndObservation',
          `Failed to harvest at (${pos.x}, ${pos.y}, ${pos.z}): ${error}`,
        );
      }
    }
  };

• mcp-server/src/skillRegistry.ts:123-130 (schema)

  Schema definition for the harvestMatureCrops tool including input parameters (number and radius) and description.

  harvestMatureCrops: {
      description: "Harvest mature crops from nearby farmland",
      params: {
          number: { type: "number", description: "Number of crops to harvest" },
          radius: { type: "number", description: "Search radius (default: 30)" }
      },
      required: []
  },

• mcp-server/src/skillRegistry.ts:354-364 (registration)

  Generic registration code in loadSkills that adds all skills from SKILL_METADATA to the skills array, dynamically loading the handler via createSkillExecutor.

      skills.push({
          name: skillName,
          description: metadata.description,
          inputSchema: {
              type: "object",
              properties: metadata.params,
              required: metadata.required
          },
          execute: createSkillExecutor(skillName)
      });
  }