MCP Minecraft Remote

Instructions

Implementation Reference

• src/tools/blocks.ts:77-146 (handler)

  Handler function that implements the placeBlock tool logic: validates connection, locates and equips the item, iterates over possible faces to find a suitable reference block, and places the block.

    async ({ x, y, z, itemName }) => {
      if (!botState.isConnected || !botState.bot) {
        return createNotConnectedResponse()
      }
  
      try {
        // Find item from inventory
        const item = botState.bot.inventory
          .items()
          .find((item) => item.name.toLowerCase() === itemName.toLowerCase())
  
        if (!item) {
          return createSuccessResponse(
            `Item "${itemName}" not found in inventory.`
          )
        }
  
        // Hold item in hand
        await botState.bot.equip(item, 'hand')
  
        // Get reference block and placement face for target position
        const targetPos = { x, y, z }
        const faceVectors = [
          { x: 0, y: 1, z: 0 }, // Up
          { x: 0, y: -1, z: 0 }, // Down
          { x: 1, y: 0, z: 0 }, // East
          { x: -1, y: 0, z: 0 }, // West
          { x: 0, y: 0, z: 1 }, // South
          { x: 0, y: 0, z: -1 }, // North
        ]
  
        // Check each face to see if placement is possible
        for (const faceVector of faceVectors) {
          const referencePos = {
            x: targetPos.x - faceVector.x,
            y: targetPos.y - faceVector.y,
            z: targetPos.z - faceVector.z,
          }
  
          const referenceBlock = botState.bot.blockAt(
            new Vec3(referencePos.x, referencePos.y, referencePos.z)
          )
  
          if (referenceBlock && referenceBlock.name !== 'air') {
            try {
              // Place the block
              await botState.bot.placeBlock(
                referenceBlock,
                new Vec3(faceVector.x, faceVector.y, faceVector.z)
              )
  
              return createSuccessResponse(
                `Successfully placed ${itemName} at X=${x}, Y=${y}, Z=${z}`
              )
            } catch (err) {
              // If placement fails on this face, try the next face
              continue
            }
          }
        }
  
        // If placement fails on all faces
        return createSuccessResponse(
          `Failed to place ${itemName}. No suitable surface found or not enough space.`
        )
      } catch (error) {
        return createErrorResponse(error)
      }
    }
  )

• src/tools/blocks.ts:71-76 (schema)

  Zod schema defining input parameters for placeBlock tool: coordinates (x,y,z) and itemName.

  {
    x: z.number().describe('X coordinate'),
    y: z.number().describe('Y coordinate'),
    z: z.number().describe('Z coordinate'),
    itemName: z.string().describe('Name of the item to place'),
  },

• src/tools/blocks.ts:68-70 (registration)

  Registers the placeBlock tool using server.tool, specifying name, description, input schema, and handler function.

  server.tool(
    'placeBlock',
    'Place a block at the specified location',

• src/tools/index.ts:25-25 (registration)

  Calls registerBlockTools which includes the placeBlock tool registration.

  registerBlockTools()

• src/index.ts:7-7 (registration)

  Top-level call to registerAllTools, which triggers the chain leading to placeBlock registration.

  registerAllTools()