Hello3DMCP Server

Instructions

Implementation Reference

• server.js:1860-1906 (registration)

  Registration of the 'get_model_color' tool with its handler implementation. The tool queries the browser state to get the current model color as a hex code, with proper error handling and session management.

    'get_model_color',
    {
      title: 'Get Model Color',
      description: 'Get the current model color as a hex color code (e.g., "#ff0000"). ' +
        'Query this before relative color changes (e.g., "darken by 10%") 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 color = state.model?.color || '#808080';
        
        return {
          content: [
            {
              type: 'text',
              text: formatStateResponse(color, 'Model color', sessionId, metadata)
            }
          ]
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: `Error retrieving model color: ${error.message}`
            }
          ],
          isError: true
        };
      }
    }
  );

• server.js:1868-1905 (handler)

  The handler function for 'get_model_color' that executes the tool logic: gets the current session ID, queries the browser state for the model color, formats the response with metadata, and handles errors appropriately.

  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 color = state.model?.color || '#808080';
      
      return {
        content: [
          {
            type: 'text',
            text: formatStateResponse(color, 'Model color', sessionId, metadata)
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error retrieving model color: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }

• server.js:284-316 (helper)

  Helper function that queries state from the browser with fallback to cached state. Used by get_model_color to retrieve the current model color. Returns state with metadata including source (fresh/cached) and timestamp.

  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 used by get_model_color to format the response with metadata. It formats the state value with property name, timestamp, source info, and a staleness warning if using cached state.

  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})`;
  }

• server.js:2882-2888 (helper)

  Helper function that retrieves the current session ID, working in both STDIO mode (using a unique ID) and HTTP mode (using AsyncLocalStorage context). Used by get_model_color to identify which browser session to query.

  function getCurrentSessionId() {
    if (isStdioMode) {
      return STDIO_SESSION_ID;
    } else {
      return sessionContext.getStore();
    }
  }