mcp-minecraft

Instructions

Implementation Reference

• src/tools/flight-tools.ts:43-76 (handler)

  Handler function for the 'fly-to' tool. Uses bot.creative.flyTo to fly to the specified coordinates with timeout and cancellation support.

  async ({ x, y, z }) => {
    const bot = getBot();
  
    if (!bot.creative) {
      return factory.createResponse("Creative mode is not available. Cannot fly.");
    }
  
    const controller = new AbortController();
    const FLIGHT_TIMEOUT_MS = 20000;
  
    const timeoutId = setTimeout(() => {
      if (!controller.signal.aborted) {
        controller.abort();
      }
    }, FLIGHT_TIMEOUT_MS);
  
    try {
      const destination = new Vec3(x, y, z);
      await createCancellableFlightOperation(bot, destination, controller);
      return factory.createResponse(`Successfully flew to position (${x}, ${y}, ${z}).`);
    } catch (error) {
      if (controller.signal.aborted) {
        const currentPosAfterTimeout = bot.entity.position;
        return factory.createErrorResponse(
          `Flight timed out after ${FLIGHT_TIMEOUT_MS / 1000} seconds. The destination may be unreachable. ` +
          `Current position: (${Math.floor(currentPosAfterTimeout.x)}, ${Math.floor(currentPosAfterTimeout.y)}, ${Math.floor(currentPosAfterTimeout.z)})`
        );
      }
      throw error;
    } finally {
      clearTimeout(timeoutId);
      bot.creative.stopFlying();
    }
  }

• src/tools/flight-tools.ts:39-42 (schema)

  Input schema for 'fly-to' tool using Zod, defining x, y, z coordinates as numbers.

    x: z.number().describe("X coordinate"),
    y: z.number().describe("Y coordinate"),
    z: z.number().describe("Z coordinate")
  },

• src/tools/flight-tools.ts:35-77 (registration)

  Registers the 'fly-to' tool with the ToolFactory, including name, description, schema, and handler.

  factory.registerTool(
    "fly-to",
    "Make the bot fly to a specific position",
    {
      x: z.number().describe("X coordinate"),
      y: z.number().describe("Y coordinate"),
      z: z.number().describe("Z coordinate")
    },
    async ({ x, y, z }) => {
      const bot = getBot();
  
      if (!bot.creative) {
        return factory.createResponse("Creative mode is not available. Cannot fly.");
      }
  
      const controller = new AbortController();
      const FLIGHT_TIMEOUT_MS = 20000;
  
      const timeoutId = setTimeout(() => {
        if (!controller.signal.aborted) {
          controller.abort();
        }
      }, FLIGHT_TIMEOUT_MS);
  
      try {
        const destination = new Vec3(x, y, z);
        await createCancellableFlightOperation(bot, destination, controller);
        return factory.createResponse(`Successfully flew to position (${x}, ${y}, ${z}).`);
      } catch (error) {
        if (controller.signal.aborted) {
          const currentPosAfterTimeout = bot.entity.position;
          return factory.createErrorResponse(
            `Flight timed out after ${FLIGHT_TIMEOUT_MS / 1000} seconds. The destination may be unreachable. ` +
            `Current position: (${Math.floor(currentPosAfterTimeout.x)}, ${Math.floor(currentPosAfterTimeout.y)}, ${Math.floor(currentPosAfterTimeout.z)})`
          );
        }
        throw error;
      } finally {
        clearTimeout(timeoutId);
        bot.creative.stopFlying();
      }
    }
  );

• src/main.ts:56-56 (registration)

  Calls registerFlightTools in main to initialize and register all flight tools including 'fly-to'.

  registerFlightTools(factory, getBot);

• src/tools/flight-tools.ts:6-32 (helper)

  Helper utility that makes the flight operation cancellable via AbortController.

  function createCancellableFlightOperation(
    bot: mineflayer.Bot,
    destination: Vec3,
    controller: AbortController
  ): Promise<boolean> {
    return new Promise((resolve, reject) => {
      let aborted = false;
  
      controller.signal.addEventListener('abort', () => {
        aborted = true;
        bot.creative.stopFlying();
        reject(new Error("Flight operation cancelled"));
      });
  
      bot.creative.flyTo(destination)
        .then(() => {
          if (!aborted) {
            resolve(true);
          }
        })
        .catch((err: Error) => {
          if (!aborted) {
            reject(err);
          }
        });
    });
  }