Hello3DMCP Server

Instructions

Implementation Reference

• server.js:1355-1403 (handler)

  The tool handler implementation for get_fill_light_position_spherical. This function retrieves the current fill light position in camera-centric spherical coordinates (azimuth, elevation, distance) from the browser state and returns it formatted with metadata including source and timestamp.

  mcpServer.registerTool(
    'get_fill_light_position_spherical',
    {
      title: 'Get Fill Light Position (Spherical Coordinates)',
      description: 'Get the current fill light position in camera-centric spherical coordinates. ' +
        'Query this before relative position changes (e.g., "rotate light 10 degrees") to ensure accuracy. ' +
        'For absolute changes, you may use recently queried state from context if no manual interactions occurred.',
      inputSchema: {}
    },
    async () => {
      const sessionId = getCurrentSessionId();
      if (!sessionId) {
        return {
          content: [
            {
              type: 'text',
              text: 'Error: No active session found.'
            }
          ],
          isError: true
        };
      }
  
      try {
        const { state, metadata } = await getState(sessionId);
        const position = state.fillLight?.position || { azimuth: 0, elevation: 0, distance: 0 };
        const positionText = `azimuth ${position.azimuth}°, elevation ${position.elevation}°, distance ${position.distance}`;
        
        return {
          content: [
            {
              type: 'text',
              text: formatStateResponse(positionText, 'Fill light position', sessionId, metadata)
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error retrieving fill light position: ${error.message}`
            }
          ],
          isError: true
        };
      }
    }
  );

• server.js:1355-1363 (registration)

  Tool registration for get_fill_light_position_spherical. Registers the tool with MCP server including title, description, and empty inputSchema definition.

  mcpServer.registerTool(
    'get_fill_light_position_spherical',
    {
      title: 'Get Fill Light Position (Spherical Coordinates)',
      description: 'Get the current fill light position in camera-centric spherical coordinates. ' +
        'Query this before relative position changes (e.g., "rotate light 10 degrees") to ensure accuracy. ' +
        'For absolute changes, you may use recently queried state from context if no manual interactions occurred.',
      inputSchema: {}
    },

• server.js:1057-1068 (schema)

  Azimuth schema definition used by fill light position tools. Accepts numbers (0-360) or direction names as strings, with validation against availableDirectionNames.

  const azimuthSchema = z.union([
    z.number().min(0).max(360),
    z.string().refine(
      (val) => {
        const normalized = normalizeDirectionName(val);
        return normalized && directionToAzimuthMap.has(normalized);
      },
      {
        message: `Must be a number (0-360) or a direction name. Available directions: ${availableDirectionNames}`
      }
    )
  ]).describe(`Horizontal angle in degrees (0-360) or direction name (e.g., "north", "northwest", "NW"). 0° = camera forward (North), 90° = camera right (East), 180° = behind camera (South), 270° = camera left (West). Available directions: ${availableDirectionNames}`);

• server.js:284-316 (helper)

  Helper function getState that queries state from the browser (or uses cache if unavailable). Used by get_fill_light_position_spherical to retrieve current fill light position data.

  async function getState(sessionId) {
    let state;
    let source;
    let wasCached = false;
    
    // Always query browser for current state
    try {
      state = await queryStateFromBrowser(sessionId);
      source = 'fresh';
    } catch (error) {
      // If query fails, fall back to cache if available (browser may be disconnected)
      const cached = sessionStateCache.get(sessionId);
      if (cached) {
        console.warn(`Browser query failed for session ${sessionId}, returning cached state: ${error.message}`);
        state = cached.state;
        source = 'cache';
        wasCached = true;
      } else {
        // No cache available, throw error
        throw new Error(`Unable to retrieve state: ${error.message}. Browser may be disconnected.`);
      }
    }
    
    // Return state with metadata
    return {
      state,
      metadata: {
        source,
        wasCached,
        timestamp: new Date().toISOString()
      }
    };
  }

• server.js:319-327 (helper)

  Helper function formatStateResponse that formats state query responses with metadata (timestamp, source, staleness warning). Used by get_fill_light_position_spherical to format the output.

  function formatStateResponse(value, propertyName, sessionId, metadata) {
    const timestamp = metadata.timestamp;
    const source = metadata.source;
    const stalenessWarning = metadata.wasCached 
      ? ' (using cached state - browser may be disconnected)' 
      : '';
    
    return `${propertyName}: ${value} (queried at ${timestamp}, source: ${source}${stalenessWarning})`;
  }