change_background_color

Modify the background color of a 3D scene by specifying a hex color code or color name to alter the visual environment.

Instructions

Change the background color of the 3D scene

Input Schema

TableJSON Schema

Name	Required	Description	Default
`color`	Yes	Hex color code (e.g., "#ff0000") or Apple crayon color name (e.g., "maraschino", "turquoise", "lemon"). Available colors: licorice, lead, tungsten, iron, steel, tin, nickel, aluminum, magnesium, silver, mercury, snow, cayenne, mocha, asparagus, fern, clover, moss, teal, ocean, midnight, eggplant, plum, maroon, maraschino, tangerine, lemon, lime, spring, sea foam, turquoise, aqua, blueberry, grape, magenta, strawberry, salmon, cantaloupe, banana, honeydew, flora, spindrift, ice, sky, orchid, lavender, bubblegum, carnation

Implementation Reference

server.js:508-547 (handler)

Complete tool registration and handler for change_background_color. Validates the color input using normalizeColorToHex, routes the command to the current session via WebSocket, and returns a success message with the display name of the color.

// Register tool: change_background_color
mcpServer.registerTool(
  'change_background_color',
  {
    title: 'Change Background Color',
    description: 'Change the background color of the 3D scene',
    inputSchema: {
      color: colorSchema
    }
  },
  async ({ color }) => {
    const hexColor = normalizeColorToHex(color);
    if (!hexColor) {
      return {
        content: [
          {
            type: 'text',
            text: `Invalid color: ${color}. Please use a hex code (e.g., "#000000") or an Apple crayon color name.`
          }
        ],
        isError: true
      };
    }

    routeToCurrentSession({
      type: 'changeBackgroundColor',
      color: hexColor
    });

    const displayName = /^#[0-9A-Fa-f]{6}$/.test(color) ? hexColor : `${color} (${hexColor})`;
    return {
      content: [
        {
          type: 'text',
          text: `Background color changed to ${displayName}`
        }
      ]
    };
  }
);

server.js:389-407 (schema)

Zod schema for color input validation. Accepts hex color codes (e.g., '#ff0000') or Apple crayon color names (e.g., 'maraschino'). Used by change_background_color and other color tools.

// Zod schema for color input - accepts hex codes or Apple crayon color names
const colorSchema = z.string().refine(
  (val) => {
    // Accept hex codes
    if (/^#[0-9A-Fa-f]{6}$/.test(val)) {
      return true;
    }
    // Accept Apple crayon color names (case-insensitive)
    let normalizedName = val.toLowerCase().trim();
    // Handle "sea foam" variations
    if (normalizedName === 'seafoam' || normalizedName === 'sea-foam') {
      normalizedName = 'sea foam';
    }
    return appleCrayonColorsHexStrings.has(normalizedName);
  },
  {
    message: `Must be a hex color code (e.g., "#ff0000") or an Apple crayon color name. Available colors: ${availableColorNames}`
  }
).describe(`Hex color code (e.g., "#ff0000") or Apple crayon color name (e.g., "maraschino", "turquoise", "lemon"). Available colors: ${availableColorNames}`);

server.js:69-95 (helper)

Helper function normalizeColorToHex that converts color input (hex code or Apple crayon color name) to a normalized hex color code. Returns null if invalid. Used by change_background_color handler.

function normalizeColorToHex(colorInput) {
  if (!colorInput || typeof colorInput !== 'string') {
    return null;
  }
  
  // Check if it's already a hex code
  if (/^#[0-9A-Fa-f]{6}$/.test(colorInput)) {
    return colorInput.toLowerCase();
  }
  
  // Normalize the input: lowercase, trim, and handle variations
  let normalizedName = colorInput.toLowerCase().trim();
  
  // Handle "sea foam" variations (with space, without space, with hyphen)
  if (normalizedName === 'seafoam' || normalizedName === 'sea-foam') {
    normalizedName = 'sea foam';
  }
  
  // Try to find it as an Apple crayon color name
  const hexColor = appleCrayonColorsHexStrings.get(normalizedName);
  
  if (hexColor) {
    return hexColor.toLowerCase();
  }
  
  return null;
}

Hello3DMCP Server