VRChat MCP OSC

Instructions

Implementation Reference

• packages/mcp-server/src/tools/avatarTools.ts:279-349 (handler)

  Core handler function in AvatarTools class that executes the avatar change logic, including validation, logging, retry mechanism (up to 3 attempts), and delegation to wsClient.setAvatar.

  public async setAvatar(
    avatarId: string,
    ctx?: ToolContext
  ): Promise<string> {
    if (!avatarId) {
      const errorMsg = 'Missing avatar ID';
      logger.error(errorMsg);
      if (ctx) await ctx.error(errorMsg);
      return errorMsg;
    }
  
    if (ctx) {
      await ctx.info(`Changing avatar to ${avatarId}`);
    }
  
    try {
      // Multiple retry attempts
      let attempts = 0;
      const maxAttempts = 3;
  
      while (attempts < maxAttempts) {
        attempts++;
        logger.info(`Changing avatar to ${avatarId} (attempt ${attempts}/${maxAttempts})`);
  
        try {
        //   // Get available avatars
        //   const avatars = await this.wsClient.getAvatarlist();
        //   if (!avatars || !avatars[avatarId]) {
        //     throw new Error(`Avatar ${avatarId} not found in available avatars`);
        //   }
  
          // Send avatar change request using the new method
          const success = await this.wsClient.setAvatar(avatarId);
  
          if (success) {
            // const successMsg = `Successfully changed avatar to ${avatars[avatarId]} (${avatarId})`;
            const successMsg = `Successfully changed avatar to (${avatarId})`;
            logger.info(successMsg);
            return successMsg;
          } else {
            logger.warn(`Failed to change avatar (attempt ${attempts})`);
  
            // Try again if we have attempts left
            if (attempts < maxAttempts) {
              const delay = 300 * attempts;
              logger.info(`Retrying in ${delay}ms...`);
              await new Promise(resolve => setTimeout(resolve, delay));
            }
          }
        } catch (error) {
          logger.warn(`Error changing avatar (attempt ${attempts}): ${error instanceof Error ? error.message : String(error)}`);
  
          // Try again if we have attempts left
          if (attempts < maxAttempts) {
            const delay = 300 * attempts;
            logger.info(`Retrying in ${delay}ms...`);
            await new Promise(resolve => setTimeout(resolve, delay));
          }
        }
      }
  
      // All attempts failed
      const failMsg = `Failed to change avatar after ${maxAttempts} attempts`;
      logger.error(failMsg);
      return failMsg;
    } catch (error) {
      const errorMsg = `Error changing avatar: ${error instanceof Error ? error.message : String(error)}`;
      logger.error(errorMsg);
      return errorMsg;
    }
  }

• packages/mcp-server/src/server.ts:343-364 (registration)

  MCP server.tool() registration for the 'set_avatar' tool, including description, input schema validation with Zod, and thin async handler that creates context and delegates to avatarTools.setAvatar with error handling.

  server.tool(
    'set_avatar',
    'Change to a specific avatar.',
    {
      avatar_id: z.string().describe('ID of the avatar to change to')
    },
    async ({ avatar_id }, extra) => {
      try {
        const ctx = createToolContext(extra);
        const result = await avatarTools.setAvatar(avatar_id, ctx);
        return { content: [{ type: 'text', text: result }] };
      } catch (error) {
        return {
          content: [{
            type: 'text',
            text: `Error changing avatar: ${error instanceof Error ? error.message : String(error)}`
          }],
          isError: true
        };
      }
    }
  );

• packages/mcp-server/src/server.ts:346-348 (schema)

  Zod input schema for the set_avatar tool, defining the required 'avatar_id' parameter as a string.

  {
    avatar_id: z.string().describe('ID of the avatar to change to')
  },