find-entity
Locate and retrieve the nearest specified entity in Minecraft using defined search parameters such as type and maximum distance. Integrates with MCP server for real-time in-game entity detection 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/tools/entity-tools.ts:15-32 (handler)Handler function that implements the 'find-entity' tool logic: filters entities by type, finds the nearest one using bot.nearestEntity, checks distance, and returns position info.async ({ type = '', maxDistance = 16 }) => { const bot = getBot(); const entityFilter = (entity: NonNullable<Entity>) => { if (!type) return true; if (type === 'player') return entity.type === 'player'; if (type === 'mob') return entity.type === 'mob'; return Boolean(entity.name && entity.name.includes(type.toLowerCase())); }; const entity = bot.nearestEntity(entityFilter); if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) { return factory.createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`); } const entityName = entity.name || (entity as { username?: string }).username || entity.type; return factory.createResponse(`Found ${entityName} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`); }
- src/tools/entity-tools.ts:11-14 (schema)Input schema using Zod for validating 'type' and 'maxDistance' parameters of the 'find-entity' tool.{ 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/tools/entity-tools.ts:8-33 (registration)Registration of the 'find-entity' tool with ToolFactory, including name, description, schema, and handler function.factory.registerTool( "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 }) => { const bot = getBot(); const entityFilter = (entity: NonNullable<Entity>) => { if (!type) return true; if (type === 'player') return entity.type === 'player'; if (type === 'mob') return entity.type === 'mob'; return Boolean(entity.name && entity.name.includes(type.toLowerCase())); }; const entity = bot.nearestEntity(entityFilter); if (!entity || bot.entity.position.distanceTo(entity.position) > maxDistance) { return factory.createResponse(`No ${type || 'entity'} found within ${maxDistance} blocks`); } const entityName = entity.name || (entity as { username?: string }).username || entity.type; return factory.createResponse(`Found ${entityName} at position (${Math.floor(entity.position.x)}, ${Math.floor(entity.position.y)}, ${Math.floor(entity.position.z)})`); } );
- src/main.ts:54-54 (registration)Top-level call to registerEntityTools which in turn registers the 'find-entity' tool.registerEntityTools(factory, getBot);