Minecraft MCP Server

Instructions

Implementation Reference

• mcp-server/src/skills/verified/lookAround.ts:195-330 (handler)

  The main handler function for the 'lookAround' tool. It gathers comprehensive environmental data including position, health, time, weather, biome, held item, nearby visible blocks (top 15 types), nearby entities, inventory summary (top 10 items), oxygen level, and open interfaces, then emits a formatted observation via bot events.

  export const lookAround = async (
      bot: Bot,
      params: ISkillParams,
      serviceParams: ISkillServiceParams,
  ): Promise<boolean> => {
      const skillName = 'lookAround';
      const requiredParams: string[] = [];
      const isParamsValid = validateSkillParams(
          { ...serviceParams },
          requiredParams,
          skillName,
      );
      if (!isParamsValid) {
          serviceParams.cancelExecution?.();
          bot.emit(
              'alteraBotEndObservation',
              `Mistake: You didn't provide all of the required parameters ${requiredParams.join(', ')} for the ${skillName} skill.`,
          );
          return false;
      }
  
      bot.emit(
          'alteraBotStartObservation',
          `🔍 SCANNING ENVIRONMENT 🔍`,
      );
  
      const mcData = minecraftData(bot.version);
  
      try {
          bot.emit('alteraBotStartObservation', 'Looking around to observe the environment...');
  
          // Gather all observations
          const observations: string[] = [];
  
          // Location
          const pos = bot.entity.position;
          observations.push(`You are at coordinates X:${Math.floor(pos.x)}, Y:${Math.floor(pos.y)}, Z:${Math.floor(pos.z)}.`);
  
          // Health and food
          observations.push(`Your health is ${bot.health}/20 and hunger is ${bot.food}/20.`);
  
          // Time and weather
          const timeOfDay = getTimeOfDay(bot);
          const weather = getWeather(bot);
          observations.push(`It is ${timeOfDay} and the weather is ${weather}.`);
  
          // Biome
          const block = bot.blockAt(bot.entity.position);
          if (block && block.biome) {
              const biomeName = mcData.biomes[block.biome.id]?.name || 'unknown';
              observations.push(`You are in a ${biomeName} biome.`);
          }
  
          // Held item
          const heldItem = bot.heldItem;
          if (heldItem) {
              observations.push(`You are holding ${heldItem.name}.`);
          } else {
              observations.push(`You are not holding anything.`);
          }
  
          // Nearby blocks
          const nearbyBlocks = getNearbyBlocks(bot, 16);
          if (nearbyBlocks.length > 0) {
              observations.push(`\nYou see these blocks around you:`);
              // Group similar blocks
              const blockCounts: Record<string, number> = {};
              nearbyBlocks.forEach(block => {
                  blockCounts[block] = (blockCounts[block] || 0) + 1;
              });
  
              // Sort by count (most common first)
              const sortedBlocks = Object.entries(blockCounts)
                  .sort((a, b) => b[1] - a[1])
                  .slice(0, 15); // Limit to top 15 for readability
  
              sortedBlocks.forEach(([block, count]) => {
                  observations.push(`- ${count} ${block}`);
              });
  
              if (nearbyBlocks.length > 15) {
                  observations.push(`... and ${nearbyBlocks.length - 15} other block types`);
              }
          }
  
          // Nearby entities
          const nearbyEntities = getNearbyEntities(bot, 16);
          if (nearbyEntities.length > 0) {
              observations.push(`\nYou see these entities nearby:`);
              nearbyEntities.forEach(entity => {
                  observations.push(`- ${entity}`);
              });
          }
  
          // Inventory summary
          const inventory = getInventorySummary(bot);
          const itemCount = Object.keys(inventory).length;
          if (itemCount > 0) {
              observations.push(`\nYour inventory contains ${itemCount} different items:`);
              const sortedInventory = Object.entries(inventory)
                  .sort((a, b) => b[1] - a[1])
                  .slice(0, 10); // Show top 10 items
  
              sortedInventory.forEach(([item, count]) => {
                  observations.push(`- ${item}: ${count}`);
              });
  
              if (itemCount > 10) {
                  observations.push(`... and ${itemCount - 10} other item types`);
              }
          } else {
              observations.push(`\nYour inventory is empty.`);
          }
  
          // Check if drowning
          if (bot.oxygenLevel && bot.oxygenLevel < 20) {
              observations.push(`\nWARNING: You are underwater! Oxygen level: ${bot.oxygenLevel}/20`);
          }
  
          // Current interface
          if ((bot as any).currentInterface) {
              const currentInterface = (bot as any).currentInterface;
              observations.push(`\nYou have a ${currentInterface.title || 'interface'} open.`);
          }
  
          // Combine all observations
          const fullObservation = observations.join('\n');
          bot.emit('alteraBotEndObservation', fullObservation);
  
          return true;
      } catch (error) {
          console.error(`Error in lookAround skill: ${error}`);
          bot.emit('alteraBotEndObservation', `Failed to look around: ${error}`);
          return false;
      }
  }

• mcp-server/src/skillRegistry.ts:230-234 (schema)

  Schema definition and metadata for the 'lookAround' tool, specifying no input parameters are required and providing the tool description.

  lookAround: {
      description: "Look around and observe the environment, providing a detailed text-based view of surroundings",
      params: {},
      required: []
  },

• mcp-server/src/skillRegistry.ts:350-367 (registration)

  The loadSkills function registers all skills including 'lookAround' by creating SkillDefinition objects from SKILL_METADATA and dynamic executors that import and run the skill modules.

  export async function loadSkills(): Promise<SkillDefinition[]> {
      const skills: SkillDefinition[] = [];
  
      for (const [skillName, metadata] of Object.entries(SKILL_METADATA)) {
          skills.push({
              name: skillName,
              description: metadata.description,
              inputSchema: {
                  type: "object",
                  properties: metadata.params,
                  required: metadata.required
              },
              execute: createSkillExecutor(skillName)
          });
      }
  
      return skills;
  }