find-entity
Locate the nearest in-game entity of a specific type within a defined distance. Use this tool to efficiently search and identify entities in your Minecraft environment for enhanced control and interaction.
Instructions
Find the nearest entity of a specific type
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| maxDistance | No | Maximum search distance (default: 16) | |
| type | No | Type of entity to find (empty for any entity) |
Implementation Reference
- src/bot.ts:507-526 (handler)The handler function for the 'find-entity' tool. It defines an entity filter based on the provided type and uses bot.nearestEntity to find the closest matching entity within the maxDistance, then returns its position.async ({ type = '', maxDistance = 16 }): Promise<McpResponse> => { try { const entityFilter = (entity: any) => { if (!type) return true; if (type === 'player') return entity.type === 'player'; if (type === 'mob') return entity.type === 'mob'; return entity.name && entity.name.includes(type.toLowerCase()); }; const entity = bot.nearestEntity(entityFilter); if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) { return createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`); } return createResponse(`Found ${entity.name || (entity as any).username || entity.type} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`); } catch (error) { return createErrorResponse(error as Error); } }
- src/bot.ts:503-505 (schema)Input schema for the 'find-entity' tool, defining optional 'type' (string) and 'maxDistance' (number) parameters using Zod validation.{ type: z.string().optional().describe("Type of entity to find (empty for any entity)"), maxDistance: z.number().optional().describe("Maximum search distance (default: 16)")
- src/bot.ts:500-527 (registration)Registration of the 'find-entity' tool using server.tool, including name, description, schema, and handler.server.tool( "find-entity", "Find the nearest entity of a specific type", { type: z.string().optional().describe("Type of entity to find (empty for any entity)"), maxDistance: z.number().optional().describe("Maximum search distance (default: 16)") }, async ({ type = '', maxDistance = 16 }): Promise<McpResponse> => { try { const entityFilter = (entity: any) => { if (!type) return true; if (type === 'player') return entity.type === 'player'; if (type === 'mob') return entity.type === 'mob'; return entity.name && entity.name.includes(type.toLowerCase()); }; const entity = bot.nearestEntity(entityFilter); if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) { return createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`); } return createResponse(`Found ${entity.name || (entity as any).username || entity.type} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`); } catch (error) { return createErrorResponse(error as Error); } } );
- src/bot.ts:499-528 (registration)The registerEntityTools function that contains the tool registration.function registerEntityTools(server: McpServer, bot: any) { server.tool( "find-entity", "Find the nearest entity of a specific type", { type: z.string().optional().describe("Type of entity to find (empty for any entity)"), maxDistance: z.number().optional().describe("Maximum search distance (default: 16)") }, async ({ type = '', maxDistance = 16 }): Promise<McpResponse> => { try { const entityFilter = (entity: any) => { if (!type) return true; if (type === 'player') return entity.type === 'player'; if (type === 'mob') return entity.type === 'mob'; return entity.name && entity.name.includes(type.toLowerCase()); }; const entity = bot.nearestEntity(entityFilter); if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) { return createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`); } return createResponse(`Found ${entity.name || (entity as any).username || entity.type} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`); } catch (error) { return createErrorResponse(error as Error); } } ); }
- src/bot.ts:143-143 (registration)Invocation of registerEntityTools in createMcpServer to register entity tools including 'find-entity'.registerEntityTools(server, bot);