Minecraft Bedrock MCP Server

Instructions

Implementation Reference

• src/tools/advanced/building/build-hyperboloid.ts:139-308 (handler)

  The main execute method that implements the build_hyperboloid tool. Validates inputs, calculates hyperboloid positions using calculateHyperboloidPositions utility, and executes the build using executeBuildWithOptimization.

  async execute(args: {
      action?: string;
      centerX: number;
      centerY: number;
      centerZ: number;
      baseRadius: number;
      waistRadius: number;
      height: number;
      material?: string;
      hollow?: boolean;
      axis?: 'x' | 'y' | 'z';
  }): Promise<ToolCallResult> {
      try {
          // Socket-BE API接続確認
          if (!this.world) {
              return { success: false, message: "World not available. Ensure Minecraft is connected." };
          }
  
          const { 
              action = 'build',
              centerX, 
              centerY, 
              centerZ, 
              baseRadius, 
              waistRadius, 
              height, 
              material = 'minecraft:stone', 
              hollow = false, 
              axis = 'y' 
          } = args;
          
          // actionパラメータをサポート（現在は build のみ）
          if (action !== 'build') {
              return this.createErrorResponse(`Unknown action: ${action}. Only 'build' is supported.`);
          }
          
          // 座標の整数化
          const center = {
              x: Math.floor(centerX),
              y: Math.floor(centerY),
              z: Math.floor(centerZ)
          };
          
          // Y座標の検証
          if (center.y < -64 || center.y + height > 320) {
              return {
                  success: false,
                  message: 'Hyperboloid extends beyond valid Y coordinates (-64 to 320)'
              };
          }
          
          // パラメータの検証
          if (baseRadius < 3 || baseRadius > 50) {
              return {
                  success: false,
                  message: 'Base radius must be between 3 and 50'
              };
          }
          
          if (waistRadius < 1 || waistRadius > 30) {
              return {
                  success: false,
                  message: 'Waist radius must be between 1 and 30'
              };
          }
          
          if (waistRadius >= baseRadius) {
              return {
                  success: false,
                  message: 'Waist radius must be smaller than base radius'
              };
          }
          
          if (height < 4 || height > 100) {
              return {
                  success: false,
                  message: 'Height must be between 4 and 100'
              };
          }
          
          // ブロックIDの正規化
          let blockId = material;
          if (!blockId.includes(':')) {
              blockId = `minecraft:${blockId}`;
          }
          
          const commands: string[] = [];
          let blocksPlaced = 0;
          
          const baseRadiusInt = Math.round(baseRadius);
          const waistRadiusInt = Math.round(waistRadius);
          const heightInt = Math.round(height);
          
          // 座標変換ヘルパー関数
          const transformCoordinates = (localX: number, localY: number, localZ: number): {x: number, y: number, z: number} => {
              switch (axis) {
                  case 'x':
                      // X軸ハイパーボロイド: Y-Z平面で展開、X方向に伸びる
                      return {
                          x: center.x + localY,
                          y: center.y + localZ,
                          z: center.z + localX
                      };
                  case 'z':
                      // Z軸ハイパーボロイド: X-Y平面で展開、Z方向に伸びる
                      return {
                          x: center.x + localX,
                          y: center.y + localZ,
                          z: center.z + localY
                      };
                  case 'y':
                  default:
                      // Y軸ハイパーボロイド（デフォルト）: X-Z平面で展開、Y方向に伸びる
                      return {
                          x: center.x + localX,
                          y: center.y + localY,
                          z: center.z + localZ
                      };
              }
          };
          
          // 双曲面の座標を計算
          const positions = calculateHyperboloidPositions(center, baseRadiusInt, heightInt, waistRadiusInt / baseRadiusInt, hollow);
          
          if (positions.length > BUILD_LIMITS.HYPERBOLOID) {
              return {
                  success: false,
                  message: `Too many blocks to place (maximum ${BUILD_LIMITS.HYPERBOLOID.toLocaleString()})`
              };
          }
          
          try {
              // 最適化されたビルド実行
              const result = await executeBuildWithOptimization(
                  this.world,
                  positions,
                  blockId,
                  {
                      type: 'hyperboloid',
                      center: center,
                      baseRadius: baseRadiusInt,
                      waistRadius: waistRadiusInt,
                      height: heightInt,
                      material: blockId,
                      hollow: hollow,
                      axis: axis,
                      apiUsed: 'Socket-BE'
                  }
              );
              
              if (!result.success) {
                  return this.createErrorResponse(result.message);
              }
              
              return {
                  success: true,
                  message: result.message,
                  data: result.data
              };
          } catch (buildError) {
              return this.createErrorResponse(`Building error: ${buildError instanceof Error ? buildError.message : String(buildError)}`);
          }
  
      } catch (error) {
          return {
              success: false,
              message: `Error building hyperboloid: ${error instanceof Error ? error.message : String(error)}`
          };
      }
  }

• src/tools/advanced/building/build-hyperboloid.ts:44-101 (schema)

  Input schema defining the required and optional parameters for the build_hyperboloid tool, including coordinates, radii, height, material, hollow option, and axis.

  readonly inputSchema: InputSchema = {
      type: 'object',
      properties: {
          action: {
              type: 'string',
              description: 'Build action to perform',
              enum: ['build'],
              default: 'build'
          },
          centerX: {
              type: 'number',
              description: 'Center X coordinate (east-west position of hyperboloid base center)'
          },
          centerY: {
              type: 'number',
              description: 'Center Y coordinate (height/vertical position of hyperboloid base, typically 64-100)'
          },
          centerZ: {
              type: 'number',
              description: 'Center Z coordinate (north-south position of hyperboloid base center)'
          },
          baseRadius: {
              type: 'number',
              description: 'Radius at the base in blocks. Small: 5-8, Medium: 10-15, Large: 20-30',
              minimum: 3,
              maximum: 50
          },
          waistRadius: {
              type: 'number',
              description: 'Radius at the narrowest point (waist) in blocks. Should be smaller than baseRadius',
              minimum: 1,
              maximum: 30
          },
          height: {
              type: 'number',
              description: 'Total height of the hyperboloid in blocks. Small: 10-15, Medium: 20-30, Large: 40-60',
              minimum: 4,
              maximum: 100
          },
          material: {
              type: 'string',
              description: 'Block type to build with (e.g. stone, glass, wool, concrete, etc.)',
              default: 'minecraft:stone'
          },
          hollow: {
              type: 'boolean',
              description: 'Make it hollow (true) for tower shell, or solid (false) for full hyperboloid',
              default: false
          },
          axis: {
              type: 'string',
              description: 'Hyperboloid axis direction: x (east-west), y (up-down), z (north-south)',
              enum: ['x', 'y', 'z'],
              default: 'y'
          }
      },
      required: ['centerX', 'centerY', 'centerZ', 'baseRadius', 'waistRadius', 'height']
  };

• src/server.ts:365-365 (registration)

  Instantiation of the BuildHyperboloidTool class, added to the tools array for MCP registration.

  new BuildHyperboloidTool(), // ✅ 基本動作

• src/server.ts:16-16 (registration)

  Import statement for the BuildHyperboloidTool class.

  import { BuildHyperboloidTool } from "./tools/advanced/building/build-hyperboloid";