VibeTide MCP Server

Instructions

Args:
    encoded_level: The encoded level string from a URL or sharing link

Returns the decoded level data with visualization.

Implementation Reference

• vibe_tide_mcp_server.py:1118-1144 (handler)

  Primary implementation of the decode_level_from_url MCP tool handler. Uses the global level_encoder to decode the input string, generates ASCII visualization, builds play URL, and returns structured response.

  @mcp.tool()
  async def decode_level_from_url(encoded_level: str) -> Dict[str, Any]:
      """Decode a VibeTide level from an encoded URL string.
  
      Args:
          encoded_level: The encoded level string from a URL or sharing link
  
      Returns the decoded level data with visualization.
      """
      try:
          level_data = level_encoder.decode(encoded_level)
          visualization = visualize_level(level_data)
          play_url = f"{VIBE_TIDE_CONFIG['web_player_url']}?level={encoded_level}"
  
          return {
              "success": True,
              "level_data": level_data,
              "visualization": visualization,
              "play_url": play_url,
              "encoded_level": encoded_level,
              "message": f"Successfully decoded level: {level_data.get('name', 'Unnamed Level')}",
          }
  
      except Exception as e:
          logger.error(f"Failed to decode level: {e}")
          return {"success": False, "error": f"Failed to decode level: {str(e)}"}

• vibe_tide_mcp_server.py:136-204 (helper)

  Core helper method in LevelEncoder class that implements the decoding logic: base64url decode, parse dimensions and params, RLE decode, reconstruct 2D tiles, generate name from analysis.

  def decode(self, encoded_string: str) -> Dict[str, Any]:
      """Decode URL-safe string back to level data"""
      try:
          encoded_string = encoded_string.strip()
          if not encoded_string:
              raise ValueError("Empty encoded string")
  
          # Decode from base64url
          decoded = self._base64url_decode(encoded_string)
  
          # Parse parameters if present
          main_data = decoded
          game_params = {}
  
          if "|" in decoded:
              parts = decoded.split("|", 1)
              if len(parts) == 2:
                  main_data, params_data = parts
                  try:
                      params_json = self._base64url_decode(params_data)
                      game_params = json.loads(params_json)
                  except Exception as e:
                      logger.warning(f"Failed to parse parameters: {e}")
  
          # Parse format: widthxheight:encoded_data
          if ":" not in main_data:
              raise ValueError("Invalid format: missing colon")
  
          dimensions, tile_data = main_data.split(":", 1)
  
          if "x" not in dimensions:
              raise ValueError("Invalid format: missing dimensions")
  
          width, height = map(int, dimensions.split("x"))
  
          if width < 1 or height < 1:
              raise ValueError(f"Invalid dimensions: {width}x{height}")
  
          # Decode run-length encoding
          tile_string = self._run_length_decode(tile_data)
  
          # Convert back to 2D array
          tiles = []
          index = 0
  
          for y in range(height):
              tiles.append([])
              for x in range(width):
                  char = tile_string[index] if index < len(tile_string) else "."
                  tiles[y].append(self.char_tiles.get(char, 0))
                  index += 1
  
          result = {
              "tiles": tiles,
              "width": width,
              "height": height,
              "name": self._generate_level_name(tiles),
          }
  
          # Add game parameters
          for param in ["maxEnemies", "enemySpawnChance", "coinSpawnChance"]:
              if param in game_params:
                  result[param] = game_params[param]
  
          return result
  
      except Exception as e:
          logger.error(f"Failed to decode level: {e}")
          raise ValueError(f"Level decoding failed: {str(e)}")

• vibe_tide_mcp_server.py:1181-1182 (registration)

  Server startup logging that lists the decode_level_from_url tool as available.

  logger.info("  - decode_level_from_url: Decode level from URL")
  logger.info("  - get_tile_reference: Get tile type reference")

• setup_mcp.py:288-288 (registration)

  Setup script prints list of available tools including decode_level_from_url.

  print("- decode_level_from_url: Decode levels from sharing URLs")