VRChat MCP OSC

Instructions

Implementation Reference

• packages/mcp-server/src/tools/avatarTools.ts:70-135 (handler)

  Implementation of the getAvatarName method in AvatarTools class, which fetches the current avatar name from WebSocket client with retry logic, validation, logging, and fallback handling.

  public async getAvatarName(ctx?: ToolContext): Promise<string> {
    if (ctx) {
      await ctx.info('Getting avatar name');
    }
    
    try {
      // Multiple retry attempts
      let attempts = 0;
      const maxAttempts = 3;
      let lastError: Error | null = null;
      
      while (attempts < maxAttempts) {
        attempts++;
        logger.info(`Getting avatar info (attempt ${attempts}/${maxAttempts})`);
        
        try {
          // Get the latest avatar info with increased timeout
          const avatarInfo = await this.wsClient.getAvatarInfo();
          
          // Validate the response
          if (!avatarInfo || !avatarInfo.id) {
            throw new Error('Invalid avatar info response');
          }
          
          // Update stored info and return the name
          this.currentAvatarInfo = avatarInfo;
          logger.info(`Got avatar info: ${JSON.stringify(this.currentAvatarInfo)}`);
          
          // Return result
          if (ctx) {
            await ctx.info(`Current avatar: ${this.currentAvatarInfo.name}`);
          }
          
          return this.currentAvatarInfo.name;
        } catch (error) {
          lastError = error instanceof Error ? error : new Error(String(error));
          logger.warn(`Attempt ${attempts} failed: ${lastError.message}`);
          
          // Wait before retry
          if (attempts < maxAttempts) {
            const delay = 500 * attempts; // Increasing delay for each retry
            logger.info(`Retrying in ${delay}ms...`);
            await new Promise(resolve => setTimeout(resolve, delay));
          }
        }
      }
      
      // All attempts failed
      if (lastError) {
        throw lastError;
      } else {
        throw new Error('Failed to get avatar name after multiple attempts');
      }
    } catch (error) {
      logger.error(`Failed to get avatar info: ${error instanceof Error ? error.message : String(error)}`);
      
      // Try to fall back to loaded config info if available
      const fallbackName = this.getFallbackAvatarName();
      
      if (ctx) {
        await ctx.warning(`Could not get avatar name: ${error instanceof Error ? error.message : String(error)}. Using fallback: ${fallbackName}`);
      }
      
      return fallbackName;
    }
  }

• packages/mcp-server/src/server.ts:366-384 (registration)

  MCP server registration of the 'get_avatar_name' tool using server.tool(), which delegates to avatarTools.getAvatarName() and handles response formatting and errors.

  server.tool(
    'get_avatar_name',
    'Get the name of the current avatar.',
    {},
    async () => {
      try {
        const name = await avatarTools.getAvatarName();
        return { content: [{ type: 'text', text: name }] };
      } catch (error) {
        return { 
          content: [{ 
            type: 'text', 
            text: `Error getting avatar name: ${error instanceof Error ? error.message : String(error)}` 
          }],
          isError: true
        };
      }
    }
  );