move_avatar

Instructions

Implementation Reference

• packages/mcp-server/src/server.ts:488-510 (registration)

  Registers the 'move_avatar' MCP tool with input schema (direction: enum['forward','backward','left','right'], duration: number default 1.0) and thin handler delegating to InputTools.move via ToolContext.

  server.tool(
    'move_avatar',
    'Move the avatar in a specific direction.',
    {
      direction: z.enum(['forward', 'backward', 'left', 'right']).describe('Direction to move'),
      duration: z.number().default(1.0).describe('Duration in seconds')
    },
    async ({ direction, duration }, extra) => {
      try {
        const ctx = createToolContext(extra);
        const result = await inputTools.move(direction as MovementDirection, duration, ctx);
        return { content: [{ type: 'text', text: result }] };
      } catch (error) {
        return { 
          content: [{ 
            type: 'text', 
            text: `Error moving avatar: ${error instanceof Error ? error.message : String(error)}` 
          }],
          isError: true
        };
      }
    }
  );

• packages/mcp-server/src/tools/inputTools.ts:34-177 (handler)

  Core handler logic: Maps direction to OSC input (MoveForward/Backward/left/right), sends value=1 via wsClient.sendInput with retries, delays for duration, releases to 0 with safety timeout and multiple retry attempts to ensure input release.

  public async move(
    direction: MovementDirection,
    duration: number,
    ctx?: ToolContext
  ): Promise<string> {
    if (ctx) {
      await ctx.info(`Moving ${direction} for ${duration} seconds`);
    }
    
    let inputName: string;
    let value: number;
    let releaseTimer: NodeJS.Timeout | null = null;
    
    try {
      // Map direction to input name and value
      switch (direction) {
        case 'forward':
          inputName = 'MoveForward';
          value = 1;
          break;
        case 'backward':
          inputName = 'MoveBackward';
          value = 1;
          break;
        case 'left':
          inputName = 'Moveleft';
          value = 1;
          break;
        case 'right':
          inputName = 'MoveRight';
          value = 1;
          break;
        default:
          return `Unknown direction: ${direction}`;
      }
      
      // Log the action
      logger.info(`Starting movement: ${direction} (${inputName}=${value}) for ${duration} seconds`);
      
      // Helper function to ensure input release
      const ensureInputRelease = async (): Promise<boolean> => {
        // Try up to 3 times to release the input
        for (let attempt = 1; attempt <= 3; attempt++) {
          try {
            logger.debug(`Releasing input ${inputName} (attempt ${attempt})`);
            const success = await this.wsClient.sendInput(inputName, 0.0);
            if (success) {
              logger.info(`Successfully released input ${inputName}`);
              return true;
            } else {
              logger.warn(`Failed to release input ${inputName} (attempt ${attempt})`);
              // Wait a short time before retry
              if (attempt < 3) await delay(100);
            }
          } catch (error) {
            logger.error(`Error releasing input ${inputName} (attempt ${attempt}): ${error instanceof Error ? error.message : String(error)}`);
            // Wait a short time before retry
            if (attempt < 3) await delay(200);
          }
        }
        return false;
      };
      
      // Always ensure input is released, even if there's an error
      const cleanupAndExit = async (message: string): Promise<string> => {
        if (releaseTimer) {
          clearTimeout(releaseTimer);
          releaseTimer = null;
        }
        
        await ensureInputRelease();
        return message;
      };
      
      // Set up a safety release timer that's longer than the requested duration
      // This ensures movement stops even if there's a problem during the normal flow
      releaseTimer = setTimeout(async () => {
        logger.warn(`Safety timeout for ${inputName} movement triggered`);
        await ensureInputRelease();
      }, (duration + 0.5) * 1000);
      
      // Send input press - use a retry mechanism
      let pressSuccess = false;
      for (let attempt = 1; attempt <= 3; attempt++) {
        try {
          logger.debug(`Sending input ${inputName}=${value} (attempt ${attempt})`);
          pressSuccess = await this.wsClient.sendInput(inputName, value);
          if (pressSuccess) {
            logger.info(`Successfully sent input ${inputName}=${value}`);
            break;
          } else {
            logger.warn(`Failed to send input ${inputName}=${value} (attempt ${attempt})`);
            if (attempt < 3) await delay(100);
          }
        } catch (error) {
          logger.error(`Error sending input ${inputName}=${value} (attempt ${attempt}): ${error instanceof Error ? error.message : String(error)}`);
          if (attempt < 3) await delay(200);
        }
      }
      
      if (!pressSuccess) {
        return await cleanupAndExit(`Failed to start movement: ${direction}`);
      }
      
      // Wait for duration
      logger.debug(`Waiting for ${duration} seconds before releasing ${inputName}`);
      await delay(duration * 1000);
      
      // Send input release
      const releaseSuccess = await ensureInputRelease();
      
      // Clean up the safety timer
      if (releaseTimer) {
        clearTimeout(releaseTimer);
        releaseTimer = null;
      }
      
      if (!releaseSuccess) {
        return `Started moving ${direction} but failed to stop completely`;
      }
      
      return `Moved ${direction} for ${duration} seconds`;
    } catch (error) {
      const errorMsg = `Error during ${direction} movement: ${error instanceof Error ? error.message : String(error)}`;
      logger.error(errorMsg);
      
      // Ensure cleanup happens even on error
      if (releaseTimer) {
        clearTimeout(releaseTimer);
      }
      
      // Try to release the input if we got far enough to define inputName
      if (inputName!) {
        try {
          await this.wsClient.sendInput(inputName, 0.0);
          logger.info(`Emergency release of ${inputName} after error`);
        } catch (releaseError) {
          logger.error(`Failed emergency release: ${releaseError instanceof Error ? releaseError.message : String(releaseError)}`);
        }
      }
      
      return errorMsg;
    }
  }

• packages/mcp-server/src/server.ts:491-493 (schema)

  Zod input schema validation for move_avatar tool parameters.

  {
    direction: z.enum(['forward', 'backward', 'left', 'right']).describe('Direction to move'),
    duration: z.number().default(1.0).describe('Duration in seconds')