Minecraft MCP Server

Instructions

Implementation Reference

• src/bot.ts:469-493 (handler)

  The handler function for the 'find-block' tool. It searches for the nearest block of the specified type within maxDistance using bot.findBlock, using minecraftData to resolve block ID by name.

  async ({ blockType, maxDistance = 16 }): Promise<McpResponse> => {
    try {
      const mcData = minecraftData(bot.version);
      const blocksByName = mcData.blocksByName;
  
      if (!blocksByName[blockType]) {
        return createResponse(`Unknown block type: ${blockType}`);
      }
  
      const blockId = blocksByName[blockType].id;
  
      const block = bot.findBlock({
        matching: blockId,
        maxDistance: maxDistance
      });
  
      if (!block) {
        return createResponse(`No ${blockType} found within ${maxDistance} blocks`);
      }
  
      return createResponse(`Found ${blockType} at position (${block.position.x}, ${block.position.y}, ${block.position.z})`);
    } catch (error) {
      return createErrorResponse(error as Error);
    }
  }

• src/bot.ts:465-468 (schema)

  Input schema for the 'find-block' tool using Zod: blockType (string, required), maxDistance (number, optional).

  {
    blockType: z.string().describe("Type of block to find"),
    maxDistance: z.number().optional().describe("Maximum search distance (default: 16)")
  },

• src/bot.ts:462-494 (registration)

  Registration of the 'find-block' tool using server.tool() in registerBlockTools function, including inline schema and handler.

  server.tool(
    "find-block",
    "Find the nearest block of a specific type",
    {
      blockType: z.string().describe("Type of block to find"),
      maxDistance: z.number().optional().describe("Maximum search distance (default: 16)")
    },
    async ({ blockType, maxDistance = 16 }): Promise<McpResponse> => {
      try {
        const mcData = minecraftData(bot.version);
        const blocksByName = mcData.blocksByName;
  
        if (!blocksByName[blockType]) {
          return createResponse(`Unknown block type: ${blockType}`);
        }
  
        const blockId = blocksByName[blockType].id;
  
        const block = bot.findBlock({
          matching: blockId,
          maxDistance: maxDistance
        });
  
        if (!block) {
          return createResponse(`No ${blockType} found within ${maxDistance} blocks`);
        }
  
        return createResponse(`Found ${blockType} at position (${block.position.x}, ${block.position.y}, ${block.position.z})`);
      } catch (error) {
        return createErrorResponse(error as Error);
      }
    }
  );